배치 하나에 태스크 1만 개를 담아요

배치 하나에 태스크를 최대 1만 개 담으면 플랜 한도에 맞춰 처리하고, 모든 유료 플랜의 동시 실행 수도 늘었어요.

받는 결과

• POST /v1/batches는 항목을 최대 1만 개(32 MiB) 받습니다. 항목마다 taskType과 payload를 두고, 202로 배치를 응답합니다.
• GET /v1/batches/:id는 대기, 큐, 처리 중, 완료, 실패, 거절 수로 진행 상황을 알려 줍니다.
• GET /v1/batches/:id/items는 제출한 순서대로 항목을 보여 주고, include=response를 더하면 끝난 결과도 함께 담깁니다.
• 플랜별 동시 실행 태스크는 Basic 25, Pro 150, Scale 500, Max 1,000개입니다(이전 10, 25, 50, 100개). Free는 2개입니다.
• GET /v1/capabilities는 엔진별 입력 필드, 크레딧 가격, 국가 정책을 알려 줍니다. API 키가 필요 없습니다.

동작 방식

배치는 항목을 보관하고, 플랜의 동시 실행 한도 안에서 태스크로 시작합니다. 기다려야 하는 항목은 대기 상태로 남았다가 스스로 시작하므로, 배치는 한 번만 보내면 됩니다.

항목은 제출할 때 단일 태스크와 같은 규칙으로 검사합니다. 잘못된 항목이 하나라도 있으면 배치 전체가 400으로 거절되고, 항목 번호를 최대 50개 알려 주며, 아무것도 저장하지 않습니다. 같은 idempotencyKey로 다시 보내면 처음 만든 배치를 돌려줍니다. webhook.url을 지정하면 태스크 결과마다 알림이 가고, 배치가 끝나면 서명된 batch.completed 이벤트가 한 번 갑니다.

이렇게 활용하세요

• 하루치 질문 전체를 모든 엔진에 한 번의 제출로 추적합니다.
• 수천 개의 키워드 목록을 올리고 결과를 페이지 단위로 읽습니다.
• /v1/capabilities로 엔진과 국가 선택 목록을 만듭니다.

요청 보내기

items 배열을 보냅니다. customId는 항목에 붙이는 나만의 이름이며 결과에 그대로 돌아옵니다.

curl -X POST https://api.querying.ai/v1/batches \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "customId": "crm-chatgpt",
        "taskType": "CHATGPT",
        "payload": { "prompt": "best CRM for startups", "country": "US" }
      },
      {
        "customId": "crm-gemini",
        "taskType": "GEMINI",
        "payload": { "prompt": "best CRM for startups", "country": "US" }
      },
      {
        "customId": "crm-perplexity",
        "taskType": "PERPLEXITY",
        "payload": { "prompt": "best CRM for startups", "country": "US" }
      }
    ],
    "idempotencyKey": "daily-2026-10-09"
  }'

응답

호출하면 202로 배치를 응답합니다. 항목이 나가고 끝날 때마다 수가 바뀝니다.

{
  "success": true,
  "batch": {
    "id": "…",
    "status": "OPEN",
    "total": 3,
    "counts": {
      "pending": 3,
      "queued": 0,
      "processing": 0,
      "completed": 0,
      "failed": 0,
      "rejected": 0
    },
    "idempotencyKey": "daily-2026-10-09",
    "createdAt": "…"
  }
}

결과는 제출한 순서대로 페이지 단위로 읽습니다. 항목마다 상태와 태스크 ID가 보이고, include=response를 더하면 결과도 담깁니다.

curl "https://api.querying.ai/v1/batches/$BATCH_ID/items?include=response&limit=20" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

오류

PLAN_CONCURRENCY_LIMIT, QUEUE_BACKPRESSURE, KEY_DAILY_CREDIT_LIMIT으로 거절된 항목은 대기 상태로 남고 배치가 다시 시도합니다. 그 밖의 거절은 그 항목을 rejected로 끝내고 error에 코드를 담습니다.

VALIDATION_ERRORHTTP 400

필드가 빠졌거나 허용 범위를 벗어났습니다. details에 해당 필드가 나옵니다.

PAYLOAD_TOO_LARGEHTTP 413

본문이 1 MiB를 넘었습니다. 배치는 8 MiB까지 받습니다.

KEY_SCOPE_DENIEDHTTP 403

키의 허용 엔진 밖의 엔진입니다. 다른 키를 쓰거나 키 관리에서 엔진을 추가하세요.

INSUFFICIENT_CREDITSHTTP 402

잔액이 태스크 가격보다 적습니다. 크레딧을 충전하거나 플랜을 올린 뒤 다시 보내세요.

요금

항목마다 해당 엔진의 단일 태스크와 같은 크레딧이 듭니다. 플랜별 한도는 https://querying.ai/pricing 에서 볼 수 있습니다.