요청 한 번에 태스크 500개까지 보내요

배치 엔드포인트는 여러 엔진을 섞은 태스크 최대 500개를 한 번에 큐에 넣고, 항목마다 결과를 알려 줘요.

받는 결과

• POST /v1/async/task/batch는 최대 500개의 태스크 배열을 받습니다. 각 항목은 단일 태스크와 같은 형식입니다.
• 엔진을 자유롭게 섞을 수 있어, 한 번의 호출로 질문 세트를 ChatGPT, Gemini, Perplexity에 함께 보냅니다.
• results[]가 항목마다 결과를 따로 알려 줍니다. 만들어진 태스크나 그 항목이 거절된 이유가 담깁니다.
• idempotencyKey가 항목별로 적용되어, 배치를 다시 보내면 이미 만든 태스크를 그대로 돌려줍니다.

동작 방식

형식이 맞는 배치는 항상 200으로 응답합니다. 항목을 하나씩 따로 검사하므로, 형식이 잘못된 질문은 자기 results[] 항목에 표시되고 나머지 배치는 큐에 들어갑니다. 만들어진 태스크는 단일 태스크와 똑같이 실행, 완료, 과금되고, 각각 자기 webhook을 보냅니다.

배치를 쓰면 수천 번의 HTTP 호출이 몇 번으로 줄어, 예약 작업이 빠르고 단순해집니다.

이렇게 활용하세요

• 매일 아침 질문 세트 전체를 여러 엔진에 한 번의 호출로 보냅니다.
• 큰 키워드 목록을 몇 번의 요청으로 올리고, 처리는 큐에 맡깁니다.

요청 보내기

단일 태스크와 같은 형식의 태스크를 최대 500개까지 JSON 배열 하나로 보냅니다. 한 배치 안에서 엔진과 국가를 자유롭게 섞습니다.

curl -X POST https://api.querying.ai/v1/async/task/batch \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "CHATGPT",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    },
    {
      "taskType": "GEMINI",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    },
    {
      "taskType": "PERPLEXITY",
      "payload": { "prompt": "best CRM for startups", "country": "US" }
    }
  ]'

응답

호출하면 보낸 순서대로 태스크마다 항목 하나씩 담아 200으로 응답합니다. 여기서는 태스크 ID를 줄여 표시했습니다.

{
  "success": true,
  "summary": { "total": 3, "succeeded": 3, "failed": 0 },
  "results": [
    {
      "success": true,
      "index": 0,
      "task": {
        "id": "…",
        "taskType": "CHATGPT",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    },
    {
      "success": true,
      "index": 1,
      "task": {
        "id": "…",
        "taskType": "GEMINI",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    },
    {
      "success": true,
      "index": 2,
      "task": {
        "id": "…",
        "taskType": "PERPLEXITY",
        "status": "QUEUED",
        "priority": 1,
        "createdAt": "…"
      },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
    }
  ]
}

summaryobject

배치 집계: total, succeeded, failed.

resultsarray

보낸 순서대로 태스크마다 하나씩, index, success, 대기열에 들어간 task 또는 코드가 담긴 error가 옵니다.

결과 받기

요청하면 status가 QUEUED인 태스크가 바로 돌아옵니다. status가 COMPLETED나 FAILED가 될 때까지 GET /v1/async/task/{id}로 조회하거나, webhook.url을 넣어 같은 task, credits, response를 서버로 받으세요. 결과는 태스크가 끝난 뒤 24시간 동안 조회됩니다.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

오류

본문이 빈 배열이거나 500개를 넘으면 배치 전체가 400 VALIDATION_ERROR, 8 MiB를 넘으면 413으로 응답합니다. 크기가 맞는 배치에서 플랜 동시 실행 한도나 엔진 대기열 한도를 넘는 항목은 success가 false이고 error.code에 코드가 담기며, 나머지 항목은 대기열에 들어갑니다. 그 항목은 잠시 뒤 다시 보내세요.

PLAN_CONCURRENCY_LIMITHTTP 429

대기 중이거나 실행 중인 태스크가 플랜 한도에 닿았습니다. 무료 플랜 2개, Basic 10개, Pro 25개, Scale 50개, Max 100개입니다. Retry-After초 뒤에 다시 보내세요.

QUEUE_BACKPRESSUREHTTP 429

엔진 대기열이 잠시 가득 찼습니다. Retry-After초 뒤에 다시 보내세요.

VALIDATION_ERRORHTTP 400

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

PAYLOAD_TOO_LARGEHTTP 413

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

요금

배치 요금은 엔진별 가격으로 계산한 태스크 요금의 합이고, 태스크마다 완료될 때 차감됩니다.