빠른 시작 V5 (beta)

봇 찾기부터 데이터 받기까지, 첫 수집을 5분 안에 끝냅니다.

v5 는 화면과 같은 말(봇 · 설정 · 주기 · 데이터셋)로 자원을 나눈 API 입니다. 한 봇에 주기를 여러 개 둘 수 있고, 데이터셋에서 그 수집이 수동인지 어느 주기인지, 어떤 조건으로 돌았는지까지 읽을 수 있습니다. 아래 명령은 YOUR_API_KEY만 바꾸면 그대로 동작합니다.

v4 를 쓰고 계신가요? v4 → v5 옮기기 안내를 먼저 보세요. v4 는 그대로 계속 동작합니다.

기계가 읽는 명세는 OpenAPI(JSON)로 받을 수 있습니다.

API 키 복사하기

내 정보 → API 키에서 키를 복사합니다. v4 와 같은 키를 씁니다. 모든 요청의 Authorization 헤더에 Bearer YOUR_API_KEY 형식으로 넣습니다.

키는 비밀번호와 같습니다. 코드 저장소·화면 공유에 노출하지 마세요.
내 정보에서 API 키 보기

연결 확인하기

GET

GET /v5/api/health는 키 없이 부를 수 있는 상태 확인입니다. GET /v5/api/me는 키가 가리키는 계정을 돌려줍니다.

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"
  }
}

"result": "success"와 내 이메일이 보이면 준비가 끝났습니다. 401이면 키를 다시 복사하세요.

수집할 봇 고르기

GET

내 봇 목록을 받아 수집할 봇의 id를 고릅니다. 봇 상세 화면의 더보기 → 봇 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가 봇 ID입니다. 다음 단계의 경로에 넣습니다.

수집 방법 확인하기

GET

고른 봇이 어떤 입력(키워드·정렬 등)을 받는지 확인합니다. inputs의 key(또는 alias)가 수집 요청 때 inputs에 넣을 이름이고, options가 있는 칸은 그 목록의 value 중에서 고릅니다.

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
      }
    ]
  }
}

봇이 쓰는 칸마다 key·name·options가 보입니다.

수집 요청하기

POST

고른 봇에 수집을 요청합니다. 수집 시작은 재시도 중복 방지 키(Idempotency-Key 헤더)가 필수입니다. 요청 한 번마다 새 키를 만들어 넣으세요(위 예시의 $(uuidgen)). 연결이 끊겨 다시 보낼 때만 같은 키를 씁니다. 자세한 규칙은 재시도 중복 방지 키.

save_to_settings의 기본값은 true입니다. 보낸 inputs가 봇 설정에 저장되고 그 값으로 수집합니다. 이번 한 번만 쓰려면 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": []
  }
}

data.id가 이번 수집(데이터셋)의 번호입니다. 크레딧은 수집이 시작될 때 쓰입니다.

완료될 때까지 확인하기

GET

수집은 백그라운드에서 진행됩니다. 10~30초 간격으로 상태를 조회하세요. 사이트와 수집량에 따라 수십 초에서 수십 분이 걸립니다.

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
  }
}

status가 done이면 완료입니다. waiting·running·retrying은 진행 중, failed·canceled는 끝났지만 데이터가 모두 모이지 않은 상태입니다.

데이터 받기

GET

완료된 데이터셋의 데이터를 받습니다. 한 번에 limit건씩 오며, 응답의 next_cursor를 다음 요청의 cursor로 넘겨 이어 받습니다.

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

next_cursor가 null이면 마지막 페이지입니다.

공통 규칙

주소 — 모든 경로는 https://www.hashscraper.com/v5/api 아래에 있습니다.
인증 — Authorization: Bearer <API 키>. health만 키 없이 부를 수 있습니다.
시각 — ISO 8601, 한국 시간대(+09:00)입니다.
크레딧 — 정수입니다.
주기 id — 어디서나 글자입니다("512"). 숫자로 비교하지 마세요.
요청 번호 — 요청에 X-Request-ID: req_...를 보내면 그대로 돌려주고, 없으면 서버가 만듭니다. 문의할 때 알려 주세요.

응답 칸	설명
`result`	`success` 또는 `error`. 여러 항목을 한 번에 처리하는 묶음 수집은 `partial_success`·`failure`도 있습니다.
`version`	항상 `v5`.
`request_id`	요청 번호.
`elapsed_sec`	응답을 만드는 데 걸린 시간(초).
`data`	결과. 목록이면 배열, 하나면 객체. 칸은 늘 같은 모양이고, 값이 없으면 빠지지 않고 `null`·빈 배열로 옵니다.
`count`·`next_cursor`	목록 응답에만. 이번에 받은 개수와 다음 쪽 표지(없으면 `null`).

목록 이어 받기

목록은 limit(기본 100, 최대 1000)건씩 옵니다. 응답의 next_cursor를 다음 요청의 cursor로 그대로 넘기세요. null이면 끝입니다. 이어 받는 도중 sorting 같은 조건을 바꾸지 마세요.

API 키 복사하기