Trigger Collection V4

POST www.hashscraper.com/v4/api/schedules/{schedule_id}/collections Content-Type: application/json

Triggers a new data collection job for a scraper.

Creates a new data set immediately and starts the collection in the background. Use the returned schedule_result_id for subsequent status and results lookups.

The request body has two groups: params (collection parameters) and settings (endpoint options). Every parameter marked as required by the scraper must appear inside the params group. Empty strings ("") are accepted as intentional empty values, but a missing key returns MISSING_PARAM. Use GET /v4/api/schedules/{id}/param_info to inspect required parameters.

By default the parameters are applied to this call only and the scraper itself is not modified. Pass settings.param_save: true to also persist them as the scraper's defaults.

If the scraper's union is true and at least one prior data set exists, the most recent data set is reused (results are accumulated into it) instead of creating a new one — the returned schedule_result_id is that reused data set's ID. If union is false or no prior data set exists, a new data set is created.

The request is rejected when the user's ticket is expired or credits are exhausted. Use the HTTP status and code field to distinguish reasons.

Request Parameters

  • Authorization: Header
    HashScraper API key. Send it in the form Bearer <api_key>.
    Example Bearer YOUR_API_KEY
  • schedule_id: String (path)
    ID of the scraper to collect from. Passed as the {schedule_id} path segment. You can copy the Bot ID from Actions → Copy Bot ID on the scraper's detail page.
    Example 8f3a7c1e9b5d24f6
  • params: optional Object
    Collection parameters group. Place the scraper's paramN keys inside this object.
    • param1 ~ param10: optional String
      Send inside the params group with keys param1~param10. If the bot has an alias configured, you may use that alias instead of paramN. The label text (the name/name_en fields in param_info) is display-only and cannot be used as a key. Required when the scraper has the slot marked as in-use; ignored when not in use. Empty strings ("") are accepted as intentional empty values and forwarded to the worker. Use GET /v4/api/schedules/{id}/param_info to inspect which slots are in use.
    • <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
    Endpoint options group. Place collection-related meta options inside this object.
    • param_save: optional Boolean
      settings.param_save. When true, the parameters are saved on the scraper itself as defaults for future runs. When false (default), they only apply to this call.
      Allowed true, false

Response Fields

  • result: String
    Result of the request.
    Allowed success, error
  • version: String
    API version.
    Example v4
  • request_id: String
    Request trace ID. Echoed from the client's X-Request-ID header when it starts with req_, otherwise generated by the server (req_<uuid>).
    Example req_5a8c1f1c-...
  • elapsed_sec: Float
    Time the server took to produce the response, in seconds (Float).
    Example 0.0123
  • data: Object
    Collection trigger result.
    • schedule_id: String
      ID of the requested scraper (echo).
    • name: String
      Name of the scraper.
    • schedule_result_id: Integer
      Integer ID of the data set created by this call. Use it for subsequent status and results lookups.
    • param_save: Boolean
      Echo of the settings.param_save value sent in the request.
    • param_info: Object
      Parameters used in this collection. Keys are stable (param1~paramN) and each entry contains name (label) and value. options (allowed values) is not included; use GET /v4/api/schedules/{id}/param_info to inspect option lists.

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
    A required parameter is missing from the request body. details.param_name identifies which parameter. (HTTP 400)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "MISSING_PARAM",
  "message": "Required parameter is missing.",
  "elapsed_sec": 0.0014,
  "details": { "param_name": "param2" }
}
  • VALIDATION_FAILED
    Multiple parameters are missing at once. details.errors[] lists each item. (HTTP 400)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "VALIDATION_FAILED",
  "message": "Validation failed.",
  "elapsed_sec": 0.0017,
  "details": {
    "errors": [
      { "code": "MISSING_PARAM", "param_name": "param1" },
      { "code": "MISSING_PARAM", "param_name": "param2" }
    ]
  }
}
  • SCHEDULE_NOT_FOUND
    No scraper matches the ID, or the caller does not have access. (HTTP 404)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "SCHEDULE_NOT_FOUND",
  "message": "Schedule not found.",
  "elapsed_sec": 0.0021,
  "details": { "resource": "schedule", "id": "8f3a7c1e9b5d24f6" }
}
  • TICKET_EXPIRED
    The service ticket is expired or no ticket is registered. (HTTP 402)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "TICKET_EXPIRED",
  "message": "Service ticket expired",
  "elapsed_sec": 0.0033,
  "details": { "reason": "ticket_expired" }
}
  • CREDIT_EXHAUSTED
    Available credits are exhausted; the collection cannot start. (HTTP 402)
    {
  "result": "error",
  "version": "v4",
  "request_id": "req_5a8c1f1c-...",
  "code": "CREDIT_EXHAUSTED",
  "message": "Credit exhausted",
  "elapsed_sec": 0.0033,
  "details": { "reason": "credit_exhausted" }
}

Related Guides

Example Request
  • cURL
  • Ruby
  • Python
  • NodeJS
  • PHP
  • Java
Optional
Example Response 200 
{
  "result": "success",
  "version": "v4",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "schedule_id": "8f3a7c1e9b5d24f6",
    "name": "네이버 뉴스 검색",
    "schedule_result_id": 239758028,
    "param_save": false,
    "param_info": {
      "param1": { "name": "키워드", "alias": "keyword", "value": "키성장" },
      "param2": { "name": "정렬",   "alias": "sorting", "value": "추천순" }
    }
  }
}