Quickstart V5 (beta)

From finding a bot to downloading data. Finish your first collection in five minutes.

v5 splits resources using the same words as the product screens: bots, settings, plans and datasets. A bot can have several plans, and a dataset tells you whether it was collected manually or by which plan, and with which inputs. Replace only YOUR_API_KEY and the commands below work as they are.

Using v4 today? Start with Moving from v4 to v5. v4 keeps working as it is.

A machine-readable spec is available as OpenAPI (JSON).

Copy your API key

Copy the key from My info → API key. It is the same key as v4. Send it in the Authorization header of every request as Bearer YOUR_API_KEY.

Treat the key like a password. Never expose it in a code repository or a shared screen.
View my API key

Check the connection

GET

GET /v5/api/health is a status check that needs no key. GET /v5/api/me returns the account the key belongs to.

curl 'https://www.hashscraper.com/v5/api/health'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "status": "ok",
    "time": "2026-10-04T09:00:00+09:00"
  }
}

curl 'https://www.hashscraper.com/v5/api/me' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "email": "dev@example.com",
    "name": "Sample User"
  }
}

If you see "result": "success" and your email, you are ready. On 401, copy the key again.

Pick a bot

GET

List your bots and pick the id of the one to collect with. You can also copy it from the bot detail screen with More → Copy bot ID.

curl 'https://www.hashscraper.com/v5/api/bots' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "count": 1,
  "next_cursor": null,
  "data": [
    {
      "id": "8f3a7c1e9b5d24f6",
      "name": "Sample shopping bot",
      "description": "Collects product lists by keyword.",
      "schedule_group": null,
      "union": false,
      "created_at": "2026-08-12T10:21:05+09:00",
      "updated_at": "2026-10-01T18:02:40+09:00",
      "worker_source": {
        "name": "Shopping list",
        "version": 12,
        "updated_at": "2026-09-20T11:00:00+09:00",
        "price": 5
      },
      "credit_per_item": 5,
      "plans_count": 2,
      "active_plans": [
        {
          "id": "512",
          "name": "주기 2",
          "label": "매주 월요일 09:00 (KST)"
        }
      ],
      "period_summary": "주기 2 · 매주 월요일 09:00 (KST)",
      "next_run_at": "2026-10-05T09:00:00+09:00",
      "latest_dataset": {
        "id": 239758028,
        "status": "done",
        "data_count": 1280,
        "trigger": "period",
        "created_at": "2026-09-28T09:00:03+09:00"
      }
    }
  ]
}

data[].id is the bot ID. Use it in the path of the next steps.

Check the inputs

GET

See which inputs the bot takes (keyword, sort and so on). The key (or alias) of each entry in inputs is the name to use in inputs when you collect, and for fields with options pick one of the listed values.

curl 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/inputs' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "excel_supported": true,
    "inputs": [
      {
        "key": "param1",
        "name": "Keyword",
        "name_en": "Keyword",
        "alias": "keyword",
        "type": "text",
        "required": true,
        "options": [],
        "excel_supported": true
      }
    ]
  }
}

Each field the bot uses shows its key, name and options.

Start a collection

POST

Start a collection on the bot you picked. Starting a collection requires an idempotency key (the Idempotency-Key header). Create a new key for every request (the $(uuidgen) in the example above) and reuse the same key only when you resend after a dropped connection. See Idempotency key for the rules.

save_to_settings defaults to true: the inputs you send are saved to the bot settings and used for this collection. Send false to use them for this one collection only.

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": []
  }
}

data.id is the number of this collection (dataset). Credits are used when the collection starts.

Wait until it finishes

GET

Collections run in the background. Check the status every 10 to 30 seconds. Depending on the site and volume it takes from tens of seconds to tens of minutes.

curl 'https://www.hashscraper.com/v5/api/datasets/239758028' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "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": "done",
    "data_count": 1280,
    "union": false,
    "trigger": "api",
    "credits_used": 6400,
    "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": 94
  }
}

When status is done it has finished. waiting, running and retrying are in progress. failed and canceled have ended without collecting everything.

Download the data

GET

Download the data of the finished dataset. It arrives limit rows at a time. Pass the response next_cursor as the cursor of the next request to continue.

curl 'https://www.hashscraper.com/v5/api/datasets/239758028/results?limit=1000' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "count": 1,
  "next_cursor": null,
  "data": [
    {
      "id": 91000001,
      "created_at": "2026-10-04T09:00:40+09:00",
      "updated_at": "2026-10-04T09:00:40+09:00",
      "title": "Sneakers A",
      "price": "59000"
    }
  ]
}

When next_cursor is null you have the last page.

Common rules

Address — every path lives under https://www.hashscraper.com/v5/api.
Authentication — Authorization: Bearer <API key>. Only health works without a key.
Time — ISO 8601 in the Korea time zone (+09:00).
Credits — integers.
Plan id — always a string ("512"). Do not compare it as a number.
Request ID — send X-Request-ID: req_... and it is echoed back, otherwise the server makes one. Include it when you contact us.

Response field	Description
`result`	`success` or `error`. Bulk collection, which handles several items at once, can also return `partial_success` and `failure`.
`version`	Always `v5`.
`request_id`	The request ID.
`elapsed_sec`	Seconds taken to build the response.
`data`	The result: an array for lists, an object for a single item. Fields always have the same shape; missing values arrive as `null` or an empty array instead of being left out.
`count`, `next_cursor`	List responses only: how many items arrived and the marker for the next page (`null` when there is none).

Paging through lists

Lists arrive limit items at a time (default 100, maximum 1000). Pass the response next_cursor unchanged as the cursor of the next request. null means you are done. Do not change conditions such as sorting while paging.

Copy your API key