Bulk Data Collection V4

• Authorization: Header
  HashScraper API key. Send it in the form Bearer <api_key>.

  Example Bearer YOUR_API_KEY
• schedules: Array<Object>
  Array of collection requests. Each element mirrors a single collect body: schedule_id plus the params and settings groups. Up to 100 items per request; anything larger is rejected with INVALID_PARAM (400).

  • schedule_id: String
    ID of the scraper to collect from. You can copy the Bot ID from Actions → Copy Bot ID on the scraper's detail page.

    Example 8f3a7c1e9b5d24f6
  • params: optional Object
    This collection request's parameters group. Place the scraper's paramN keys inside this object.

    • param1 ~ param10: optional String
      Scraper input parameters. Send inside this request's params group with keys param1~param10; if the bot has an alias configured you may use it instead of paramN. The label text (name/name_en) is display-only and not a valid key. Required if marked in-use; ignored otherwise. An empty string ("") is allowed as an intentional empty value.
    • <alias>: optional String
      Under params, you may use the English alias configured for the bot as the key instead of paramN. e.g. keyword instead of param1.
  • settings: optional Object
    This collection request's endpoint options group. Settings are decided per request and do not affect other requests.

    • param_save: optional Boolean
      schedules[].settings.param_save. When true, this collection request's parameters are persisted on its scraper as the new defaults. false (default) applies them only to this call. Decided per request and independent of other requests.

      Allowed true, false

• result: String
  Overall result. success when every request succeeded, partial_success when only some failed, and failure when every request failed. The three labels are mutually exclusive, so a caller can branch on this single field.

  Allowed success, partial_success, failure
• version: String
  API version.

  Example v4
• request_id: String
  Request trace ID.

  Example req_5a8c1f1c-...
• elapsed_sec: Float
  Time the server took to produce the response, in seconds (Float).

  Example 0.7843
• count: Integer
  Number of collection requests received (length of the schedules array).
• success_count: Integer
  Number of collection requests that successfully entered the queue.
• failure_count: Integer
  Number of failed collection requests.
• data: Object
  Collection request results.

  • items: Array<Object>
    Per-request result array. The order matches the order of schedules[].

    • schedule_id: String
      Echo of this collection request's schedule_id. May be null if the request omitted it.
    • name: String
      On success: name of the scraper. Omitted on failure.
    • success: Boolean
      Whether this collection request was processed successfully.

      Allowed true, false
    • schedule_result_id: Integer
      On success: the data set ID created for this collection (Integer). Omitted on failure.
    • param_save: Boolean
      On success: echo of this collection request's settings.param_save. Lets the caller see at a glance which requests persisted to their scraper. Omitted on failure.
    • param_info: Object
      On success: snapshot of the parameters used. Keys are stable (param1~paramN) and each entry contains name (label) and value.
    • code: String
      On failure: this collection request's error code. One of MISSING_PARAM (missing schedule_id or a single missing parameter), VALIDATION_FAILED (multiple parameters missing), SCHEDULE_NOT_FOUND, TICKET_EXPIRED, CREDIT_EXHAUSTED, EXECUTION_BLOCKED.
    • message: String
      On failure: human-readable English error message.
    • details: Object
      On failure: code-specific extras. MISSING_PARAM includes param_name, VALIDATION_FAILED includes one errors[] entry per missing paramN, ticket/credit/execution blocks include reason.

Error Responses

• MISSING_API_KEY
  Missing or malformed Authorization header. Send as Authorization: Bearer <api_key>. (HTTP 401)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "MISSING_API_KEY",
    "message": "API key is missing.",
    "elapsed_sec": 0.0008,
    "details": { "hint": "Send `Authorization: Bearer <api_key>` header." }
  }

• INVALID_API_KEY
  No user matches the provided API key. (HTTP 401)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "INVALID_API_KEY",
    "message": "API key is invalid.",
    "elapsed_sec": 0.0011
  }

• MISSING_PARAM (schedules)
  The request body is missing schedules or it is empty. (HTTP 400)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "MISSING_PARAM",
    "message": "Required parameter is missing.",
    "elapsed_sec": 0.0013,
    "details": { "param_name": "schedules" }
  }

• INVALID_PARAM (schedules)
  schedules is not an array. Send it as a JSON array. (HTTP 400)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "INVALID_PARAM",
    "message": "schedules must be an array.",
    "elapsed_sec": 0.0015,
    "details": { "param_name": "schedules", "type": "Hash" }
  }

• INVALID_PARAM (too many schedules)
  The schedules array exceeds the maximum of 100 items. Split the request into batches of 100 or fewer. (HTTP 400)

  {
    "result": "error",
    "version": "v4",
    "request_id": "req_5a8c1f1c-...",
    "code": "INVALID_PARAM",
    "message": "schedules exceeds the maximum of 100 items.",
    "elapsed_sec": 0.0014,
    "details": { "param_name": "schedules", "max": 100, "size": 150 }
  }

Related Guides

• Collect V4
• Collect Status V4
• Parameter Info V4