[S] HashScraper API guide

Endpoints

POST /v5/api/bots/{bot_id}/collections Bot collection (manual)
POST /v5/api/plans/{plan_id}/run Run a plan once now
POST /v5/api/collections/bulk Several bots at once
POST /v5/api/collections/bulk_jobs Many at once — get a job id right away, processed in the background (up to 5,000)
GET /v5/api/collections/bulk_jobs/{job_id} Progress and item results of a bulk job
POST /v5/api/datasets/{dataset_id}/retry Retry a collection
POST /v5/api/datasets/{dataset_id}/cancel Cancel

Bot collection

Body (all optional): inputs (collects with the bot settings as they are when omitted) and save_to_settings (default true).

true — the inputs you send are saved to the bot settings first, then collected (same as the screen). The automatic conditions of the plan that follows the bot settings change with them, so plans_affected in the response lists the affected plans (the field is absent for accounts where multiple plans are not open).
false — used for this collection only and the bot settings do not change. For a bot that cannot have its own conditions per plan this is 422 PLAN_CONDITION_BLOCKED (send true).

The response is the dataset detail (trigger is api) with saved_to_settings added.

A new collection can overlap one that has not finished yet (ALREADY_RUNNING appears only for retry). Sending the same conditions back to back starts overlapping collections and each uses credits. If a script alternates between several conditions, use save_to_settings: false.

curl -X POST 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/collections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": {
    "param1": "sneakers"
  }
}'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "id": 239758028,
    "bot": {
      "id": "8f3a7c1e9b5d24f6",
      "name": "Sample shopping bot"
    },
    "status": "running",
    "data_count": 0,
    "union": false,
    "trigger": "api",
    "credits_used": 0,
    "created_at": "2026-10-04T09:00:02+09:00",
    "updated_at": "2026-10-04T09:00:02+09:00",
    "plan": null,
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "sneakers"
      }
    },
    "started_at": "2026-10-04T09:00:02+09:00",
    "elapsed_sec": 3,
    "saved_to_settings": true,
    "plans_affected": [
      {
        "id": "one-8f3a7c1e9b5d24f6",
        "name": "주기 1",
        "label": "매일 09:00 (KST)"
      }
    ]
  }
}

curl -X POST 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/collections' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": {
    "param1": "boots"
  },
  "save_to_settings": false
}'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "id": 239758028,
    "bot": {
      "id": "8f3a7c1e9b5d24f6",
      "name": "Sample shopping bot"
    },
    "status": "running",
    "data_count": 0,
    "union": false,
    "trigger": "api",
    "credits_used": 0,
    "created_at": "2026-10-04T09:00:02+09:00",
    "updated_at": "2026-10-04T09:00:02+09:00",
    "plan": null,
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "boots"
      }
    },
    "started_at": "2026-10-04T09:00:02+09:00",
    "elapsed_sec": 3,
    "saved_to_settings": false
  }
}

Bots with Excel input

Collecting with Excel is not available in v5 yet. A collection for a bot whose input_mode is excel does not start and gives 422 EXCEL_NOT_SUPPORTED_YET.

{
  "result": "error",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "code": "EXCEL_NOT_SUPPORTED_YET",
  "message": "Collecting with Excel input is not supported in v5 yet.",
  "elapsed_sec": 0.0011,
  "details": {
    "bot_id": "8f3a7c1e9b5d24f6"
  }
}

Run a plan now

Collects once with the plan's conditions and union, separately from its scheduled runs. There is no body. A plan that follows the bot settings (including plan 1) runs with the bot settings as they are. The dataset's trigger is period_manual and plan carries the plan. A plan that runs from Excel gives 422 EXCEL_NOT_SUPPORTED_YET. Accounts where multiple plans are not open get 404 PLAN_NOT_FOUND.

curl -X POST 'https://www.hashscraper.com/v5/api/plans/512/run' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)"

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "id": 239758028,
    "bot": {
      "id": "8f3a7c1e9b5d24f6",
      "name": "Sample shopping bot"
    },
    "status": "running",
    "data_count": 0,
    "union": false,
    "trigger": "period_manual",
    "credits_used": 0,
    "created_at": "2026-10-04T09:00:02+09:00",
    "updated_at": "2026-10-04T09:00:02+09:00",
    "plan": {
      "id": "512",
      "name": "주기 2",
      "label": "매주 월요일 09:00 (KST)",
      "scheduled_at": null
    },
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "sneakers"
      }
    },
    "started_at": "2026-10-04T09:00:02+09:00",
    "elapsed_sec": 3
  }
}

Several bots at once

Give items up to 100 of { bot_id, inputs?, save_to_settings? }. Items are handled separately, so if one is rejected the others still start. HTTP is 200; the top-level result is success, partial_success or failure, and success_count and failure_count are the counts. A failed item carries success: false with code, message and details. The whole request has one key, and if any item started, resending with the same key returns the first response unchanged.

The response comes after every item is handled, so many items mean a slow response. To hand over more than 100 items, or if you cannot wait long for the response, use many at once (bulk_jobs) below.

curl -X POST 'https://www.hashscraper.com/v5/api/collections/bulk' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "bot_id": "8f3a7c1e9b5d24f6",
      "inputs": {
        "param1": "sneakers"
      }
    },
    {
      "bot_id": "0123456789abcdef",
      "save_to_settings": false
    }
  ]
}'

{
  "result": "partial_success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "count": 2,
  "success_count": 1,
  "failure_count": 1,
  "data": {
    "items": [
      {
        "bot_id": "8f3a7c1e9b5d24f6",
        "success": true,
        "dataset": {
          "id": 239758028,
          "bot": {
            "id": "8f3a7c1e9b5d24f6",
            "name": "Sample shopping bot"
          },
          "status": "running",
          "data_count": 0,
          "union": false,
          "trigger": "api",
          "plan_id": null,
          "credits_used": 0,
          "created_at": "2026-10-04T09:00:02+09:00",
          "updated_at": "2026-10-04T09:00:02+09:00"
        },
        "saved_to_settings": true
      },
      {
        "bot_id": "0123456789abcdef",
        "success": false,
        "code": "BOT_NOT_FOUND",
        "message": "Bot not found.",
        "details": {
          "resource": "schedule",
          "id": "0123456789abcdef"
        }
      }
    ]
  }
}

Many at once — bulk jobs

Send POST /collections/bulk_jobs the same items as collections/bulk, up to 5,000. Before starting anything the server answers 202 with a job id (data.job.id, starting with bj_), then handles the items one by one in request order in the background. Each item is handled exactly like collections/bulk — same checks, same credits, same result shape. You no longer lose the connection while waiting and resend the same request.

Read progress and results with GET /collections/bulk_jobs/{job_id}. Ask every 10 to 30 seconds and stop when data.job.status is done. Items come in pages with cursor and limit (default 100, max 1000). Jobs are kept for 30 days; a job id that is not yours or does not exist is 404 BULK_JOB_NOT_FOUND.

The idempotency key belongs to the job request. Resending with the same key returns the first accepted response (still status: "queued") and creates no second job. Always read the current progress with GET. A bad item (unknown bot, unknown field and so on) is not rejected when the job is accepted; only that item fails when it is handled.

Field (in data)	Description
`job.status`	`queued` (accepted) → `running` (in progress) → `done` (every item handled).
`job.total`, `processed`	Items handed over and items handled.
`job.success_count`, `failure_count`	Items that started and items that failed.
`items`	Item results in request order. A handled item has the same shape as `data.items` of `collections/bulk` (`success` with `dataset`, or `code`, `message`, `details`); an item not handled yet is `{ bot_id, success: null }`.

curl -X POST 'https://www.hashscraper.com/v5/api/collections/bulk_jobs' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "items": [
    {
      "bot_id": "8f3a7c1e9b5d24f6",
      "inputs": {
        "param1": "sneakers"
      }
    },
    {
      "bot_id": "8f3a7c1e9b5d24f6",
      "inputs": {
        "param1": "boots"
      }
    },
    {
      "bot_id": "0123456789abcdef"
    }
  ]
}'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "job": {
      "id": "bj_5f0c2a9d1e7b4c3a8d6e2f10",
      "status": "queued",
      "total": 3,
      "created_at": "2026-10-04T09:00:00+09:00"
    }
  }
}

curl 'https://www.hashscraper.com/v5/api/collections/bulk_jobs/bj_5f0c2a9d1e7b4c3a8d6e2f10?limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "count": 3,
  "next_cursor": null,
  "data": {
    "job": {
      "id": "bj_5f0c2a9d1e7b4c3a8d6e2f10",
      "status": "running",
      "total": 3,
      "created_at": "2026-10-04T09:00:00+09:00",
      "processed": 2,
      "success_count": 1,
      "failure_count": 1,
      "started_at": "2026-10-04T09:00:01+09:00",
      "finished_at": null
    },
    "items": [
      {
        "bot_id": "8f3a7c1e9b5d24f6",
        "success": true,
        "dataset": {
          "id": 239758028,
          "bot": {
            "id": "8f3a7c1e9b5d24f6",
            "name": "Sample shopping bot"
          },
          "status": "running",
          "data_count": 0,
          "union": false,
          "trigger": "api",
          "plan_id": null,
          "credits_used": 0,
          "created_at": "2026-10-04T09:00:02+09:00",
          "updated_at": "2026-10-04T09:00:02+09:00"
        },
        "saved_to_settings": true
      },
      {
        "bot_id": "8f3a7c1e9b5d24f6",
        "success": false,
        "code": "CREDIT_EXHAUSTED",
        "message": "Credits exhausted.",
        "details": {
          "reason": "credit_exhausted"
        }
      },
      {
        "bot_id": "0123456789abcdef",
        "success": null
      }
    ]
  }
}

Retry

Hands a finished dataset back under the same id (no new dataset is created). If it is in progress (waiting, running, retrying, canceling) the result is 409 ALREADY_RUNNING.

curl -X POST 'https://www.hashscraper.com/v5/api/datasets/239758028/retry' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)"

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "id": 239758028,
    "bot": {
      "id": "8f3a7c1e9b5d24f6",
      "name": "Sample shopping bot"
    },
    "status": "running",
    "data_count": 0,
    "union": false,
    "trigger": "api",
    "credits_used": 0,
    "created_at": "2026-10-04T09:00:02+09:00",
    "updated_at": "2026-10-04T09:00:02+09:00",
    "plan": null,
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "sneakers"
      }
    },
    "started_at": "2026-10-04T09:00:02+09:00",
    "elapsed_sec": 3
  }
}

{
  "result": "error",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "code": "ALREADY_RUNNING",
  "message": "A collection is already running.",
  "elapsed_sec": 0.0011,
  "details": {
    "dataset_id": 239758028,
    "status": "running"
  }
}

Cancel

Asks a running collection to stop. The status becomes canceling and then canceled once cleanup is done. Stopping immediately is not guaranteed. On an already finished dataset it changes nothing and returns the current status.

curl -X POST 'https://www.hashscraper.com/v5/api/datasets/239758028/cancel' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)"

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "id": 239758028,
    "bot": {
      "id": "8f3a7c1e9b5d24f6",
      "name": "Sample shopping bot"
    },
    "status": "canceling",
    "data_count": 0,
    "union": false,
    "trigger": "api",
    "credits_used": 0,
    "created_at": "2026-10-04T09:00:02+09:00",
    "updated_at": "2026-10-04T09:00:02+09:00",
    "plan": null,
    "inputs": {
      "param1": {
        "name": "Keyword",
        "value": "sneakers"
      }
    },
    "started_at": "2026-10-04T09:00:02+09:00",
    "elapsed_sec": 3
  }
}

When it cannot start

If it cannot start, no credits are used and, even with save_to_settings: true, the bot settings are not saved.

Code	HTTP	Meaning
`CREDIT_EXHAUSTED`	402	Not enough credits.
`TICKET_EXPIRED`	402	The ticket has expired or is not valid (`details.reason`).
`BOT_MAINTENANCE`	409	This bot is under maintenance.
`EXECUTION_BLOCKED`	409	It could not start for another reason (`details.reason`).
`ALREADY_RUNNING`	409	The dataset to retry is in progress.
`EXCEL_NOT_SUPPORTED_YET`	422	Collecting with Excel input is not supported yet.
`PLAN_CONDITION_BLOCKED`	422	This bot cannot be collected once with different conditions.
`INVALID_PARAM`, `VALIDATION_FAILED`	400	`inputs` is wrong or failed the save validation.

{
  "result": "error",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "code": "CREDIT_EXHAUSTED",
  "message": "Credit exhausted",
  "elapsed_sec": 0.0011,
  "details": {
    "reason": "credit_exhausted"
  }
}

Collections V5 (beta)