[S] HashScraper API 가이드

엔드포인트

POST /v5/api/bots/{bot_id}/collections 봇 수집(수동)
POST /v5/api/plans/{plan_id}/run 주기를 지금 한 번 돌리기
POST /v5/api/collections/bulk 여러 봇을 한 번에
POST /v5/api/collections/bulk_jobs 대량 수집 — 접수 번호를 먼저 받고 차례로 처리(최대 5,000개)
GET /v5/api/collections/bulk_jobs/{job_id} 대량 수집의 진행 상황과 항목별 결과
POST /v5/api/datasets/{dataset_id}/retry 재수집
POST /v5/api/datasets/{dataset_id}/cancel 취소

봇 수집

본문(모두 선택): inputs(없으면 봇 설정 그대로 수집), save_to_settings(기본 true).

true — 보낸 inputs를 봇 설정에 저장한 뒤 수집합니다(화면과 같습니다). 봇 설정을 따라가는 주기의 자동 수집 조건도 함께 바뀌므로 응답의 plans_affected가 영향받는 주기를 알려 줍니다(여러 주기 기능이 닫힌 계정에는 칸이 없습니다).
false — 이번 수집에만 쓰고 봇 설정은 바뀌지 않습니다. 이 봇이 주기마다 따로 조건을 둘 수 없는 경우에는 422 PLAN_CONDITION_BLOCKED입니다(true로 보내세요).

응답은 데이터셋 상세(trigger는 api)에 saved_to_settings가 더해진 모양입니다.

새 수집은 앞선 수집이 아직 끝나지 않아도 겹쳐서 시작할 수 있습니다(ALREADY_RUNNING은 재수집에서만 나옵니다). 같은 조건을 연달아 보내면 수집이 겹쳐 크레딧이 각각 쓰입니다. 스크립트로 여러 조건을 번갈아 돌린다면 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
  }
}

엑셀 입력 봇

엑셀로 수집하는 기능은 v5 에 아직 없습니다. input_mode가 excel인 봇의 수집은 시작되지 않고 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"
  }
}

주기 지금 돌리기

예정 회차와 별개로, 그 주기의 조건·유니온으로 한 번 수집합니다. 본문은 없습니다. 봇 설정을 따라가는 주기(주기 1 포함)는 봇 설정 그대로 돕니다. 데이터셋의 trigger는 period_manual, plan에 주기가 담깁니다. 엑셀로 도는 주기는 422 EXCEL_NOT_SUPPORTED_YET입니다. 여러 주기 기능이 닫힌 계정은 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
  }
}

여러 봇 한 번에

본문 items에 최대 100개의 { bot_id, inputs?, save_to_settings? }를 줍니다. 항목은 따로 처리되어 하나가 거절돼도 나머지는 그대로 시작됩니다. HTTP 는 200이고, 최상위 result가 success·partial_success·failure, success_count·failure_count가 개수입니다. 실패한 항목은 success: false와 code·message·details가 옵니다. 요청 전체에 키는 하나이고, 하나라도 시작했다면 같은 키의 재시도는 첫 응답을 그대로 돌려줍니다.

모든 항목을 처리한 뒤에 응답하므로 항목이 많으면 응답이 늦습니다. 100개를 넘게 보내거나 응답을 오래 기다리기 어렵다면 아래 대량 수집(bulk_jobs)을 쓰세요.

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

대량 수집 — 접수 번호를 먼저 받고 차례로 처리

POST /collections/bulk_jobs에 collections/bulk와 같은 items를 최대 5,000개 줍니다. 서버는 수집을 시작하기 전에 곧바로 202와 접수 번호(data.job.id, bj_로 시작)를 돌려주고, 항목은 그다음 요청 순서대로 하나씩 처리합니다. 항목 하나의 처리는 collections/bulk와 같습니다 — 같은 검사, 같은 크레딧, 같은 결과 모양입니다. 응답을 기다리다 연결이 끊겨 같은 요청을 다시 보내는 일이 없어집니다.

진행 상황과 결과는 GET /collections/bulk_jobs/{job_id}로 확인합니다. 10초에서 30초 간격으로 조회하다가 data.job.status가 done이 되면 멈추세요. 항목이 많으므로 cursor·limit(기본 100, 최대 1000)로 나눠 받습니다. 접수 기록은 30일 보관하고, 남의 접수 번호나 없는 번호는 404 BULK_JOB_NOT_FOUND입니다.

재시도 키는 접수에 붙습니다. 같은 키로 다시 보내면 처음 받은 접수 응답(status: "queued" 그대로)이 돌아오고 접수가 또 생기지 않습니다. 지금 진행은 꼭 GET으로 보세요. 없는 봇·모르는 칸 같은 잘못된 항목은 접수 때 거절하지 않고, 처리할 때 그 항목만 실패로 남습니다.

칸(data 안)	설명
`job.status`	`queued`(접수) → `running`(처리 중) → `done`(모든 항목 처리).
`job.total`·`processed`	접수한 항목 수와 처리한 항목 수.
`job.success_count`·`failure_count`	시작한 항목 수와 실패한 항목 수.
`items`	요청 순서대로 항목 결과. 처리한 항목은 `collections/bulk`의 `data.items`와 같은 모양(`success`·`dataset` 또는 `code`·`message`·`details`), 아직 처리하지 않은 항목은 `{ 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
      }
    ]
  }
}

재수집

끝난 데이터셋을 같은 id 로 다시 맡깁니다(새 데이터셋이 생기지 않습니다). 진행 중(waiting·running·retrying·canceling)이면 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"
  }
}

취소

진행 중인 수집을 멈추라고 알립니다. 상태는 canceling이 되고 정리가 끝나면 canceled가 됩니다. 즉시 멈추는 것은 보장되지 않습니다. 이미 끝난 데이터셋에 보내면 상태를 바꾸지 않고 지금 상태를 돌려줍니다.

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

시작하지 못할 때

시작하지 못하면 크레딧은 쓰이지 않고, save_to_settings: true여도 봇 설정은 저장되지 않습니다.

코드	HTTP	뜻
`CREDIT_EXHAUSTED`	402	크레딧이 부족합니다.
`TICKET_EXPIRED`	402	이용권이 만료됐거나 유효하지 않습니다(`details.reason`).
`BOT_MAINTENANCE`	409	이 봇은 점검 중입니다.
`EXECUTION_BLOCKED`	409	그 밖의 이유로 시작하지 못했습니다(`details.reason`).
`ALREADY_RUNNING`	409	재수집 대상이 진행 중입니다.
`EXCEL_NOT_SUPPORTED_YET`	422	엑셀 입력 수집은 아직 지원하지 않습니다.
`PLAN_CONDITION_BLOCKED`	422	이 봇은 이번만 다른 조건으로 수집할 수 없습니다.
`INVALID_PARAM`·`VALIDATION_FAILED`	400	`inputs`가 맞지 않거나 저장 검증에 걸렸습니다.

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

수집 V5 (beta)