1回のリクエストで最大500件のタスクを送れます

バッチエンドポイントは、複数のエンジンを混在させたタスクを1回の呼び出しで最大500件キューに入れ、項目ごとに結果を返します。

得られる結果

• POST /v1/async/task/batchは最大500件のタスクの配列を受け取ります。各項目は単一タスクと同じ形式です。
• エンジンは自由に混在でき、1回の呼び出しで質問セットをChatGPT、Gemini、Perplexityにまとめて送れます。
• results[]は項目ごとに結果を返します。作成されたタスク、またはその項目を拒否した理由が入ります。
• idempotencyKeyは項目ごとに効くため、バッチを再送すると作成済みのタスクがそのまま返ります。

仕組み

正しい形式のバッチは常に200で応答します。項目は1件ずつ個別に検証され、形式の誤りはその項目のresults[]に示され、残りのバッチはキューに入ります。作成されたタスクは単一タスクとまったく同じように実行、完了、課金され、それぞれが自分のwebhookを送ります。

バッチを使えば数千回のHTTP呼び出しが数回にまとまり、定期ジョブが速くシンプルになります。

活用例

• 毎朝、質問セット全体を複数のエンジンへ1回の呼び出しで送れます。
• 大量のキーワードリストを数回のリクエストで登録し、処理はキューに任せられます。

リクエストを送る

単一タスクと同じ形のタスクを、最大500件まで1つの JSON 配列で送ります。1つのバッチの中でエンジンと国を自由に組み合わせられます。

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

レスポンス

呼び出すと、送った順にタスクごとに1件ずつ入れて 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

送った順にタスクごとに1件。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 まで受け付けます。

料金

バッチの料金は、各エンジンの単価で計算したタスク料金の合計です。タスクごとに完了時に課金されます。