> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# タスクの一括送信: バッチと位置グリッド

> 500タスクのバッチ、10,000タスクのバッチオブジェクト、位置グリッドから選び、送信して結果を読み取ります。

3つのエンドポイントで、1回のリクエストから多数のタスクを作成できます。いずれも通常のタスクを作成するため、ポーリング、Webhook、クレジット、プランの上限は単発のタスクと同じです。

## 3つのエンドポイントの比較

| | `POST /v1/async/task/batch` | `POST /v1/batches` | `POST /v1/async/task/grid` |
| - | - | - | - |
| 送信するもの | タスクリクエストのJSON配列 | `{ items, webhook?, metadata?, idempotencyKey? }` | 1つのタスクリクエストと `grid` |
| 最大タスク数 | 500 | 10,000 | 81(9 × 9のグリッド) |
| 最大本文サイズ | 8 MiB | 32 MiB | 1 MiB |
| 成功時のステータス | `200` | 作成時は `202`、`idempotencyKey` の重複時は `200` | `200` |
| 検証 | 項目ごとに個別。不正な項目はその場で失敗 | 先に全項目を検証。1件でも不正なら `400` でバッチ全体を拒否し、何も保存しない | 先に中心点を検証。拒否されたらグリッド全体を拒否 |
| プランの上限を超えた場合 | 超過分は `PLAN_CONCURRENCY_LIMIT` で失敗し、再送信が必要 | 項目はサーバー側で待機し、空きができ次第投入 | 超過した地点はその場で失敗 |
| 進捗 | 各タスクをポーリング | `GET /v1/batches/{id}` の件数 | `GET /v1/async/task/grid/{id}` |
| 完了の通知 | タスクごとにWebhook 1回 | タスクごとにWebhook 1回、その後 `batch.completed` | タスクごとにWebhook 1回 |

## どれを使うか

* **500タスクまでで、再試行を自分で扱う場合:** `POST /v1/async/task/batch`。レスポンスですべてのタスクidを受け取れます。
* **プランの同時実行数を超えるタスク、または数千件の日次ジョブ:** `POST /v1/batches`。サーバーが項目を保持し、[プランの上限](/ja/concepts/credits-and-limits.md#プランの同時実行数)と各エンジンのキューが許す分だけ投入するため、`429` や `503` を自分で再試行する必要はありません。
* **1つのプロンプトを、ある場所の周辺の多数の地点から問い合わせる場合:** `POST /v1/async/task/grid`。

## `POST /v1/async/task/batch`

最大500件のタスクリクエストの配列を送信します([リファレンス](/ja/api-reference/create-task-batch.md))。エンジンは混在できます。

```bash theme={"theme":"css-variables"}
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", "idempotencyKey": "job-42:p1:chatgpt", "payload": { "prompt": "best CRM for a small team", "country": "US" } },
    { "taskType": "GEMINI", "idempotencyKey": "job-42:p1:gemini", "payload": { "prompt": "best CRM for a small team", "country": "US" } }
  ]'
```

正しい形式のリクエストは `200` を返します。`results[i].index` は配列内の位置に対応し、各結果は `task` または `error` のどちらかを持ちます。

```json theme={"theme":"css-variables"}
{
  "success": true,
  "summary": { "total": 2, "succeeded": 1, "failed": 1 },
  "results": [
    { "success": true, "index": 0, "task": { "id": "8f2c1e40-...", "status": "QUEUED", "...": "..." }, "credits": { "creditsToCharge": 0, "creditsCharged": 0 } },
    {
      "success": false,
      "index": 1,
      "error": {
        "code": "PLAN_CONCURRENCY_LIMIT",
        "message": "free plan allows 2 concurrent tasks; 2 already active",
        "details": { "plan": "free", "limit": 2, "source": "plan", "active": 2, "retryAfterSec": 5 },
        "timestamp": "2026-10-19T04:12:00.000Z"
      }
    }
  ]
}
```

次の場合はリクエスト全体が拒否され、タスクは作成されません。

| ステータス | コード | 条件 |
| - | - | - |
| `400` | `VALIDATION_ERROR` | 有効なJSONでない、配列でない、空、または500件超 |
| `413` | `PAYLOAD_TOO_LARGE` | 本文が8 MiB超 |
| `503` | `SERVER_OVERLOADED` | 受け付けが飽和しています。`Retry-After` の後に再試行してください。 |
| `503` | `SERVER_OVERLOADED` | 全体のキューが満杯です。`Retry-After` の後に再試行してください。 |

`idempotencyKey` が重複した場合は、既存のタスクを成功として返します。[冪等性](/ja/concepts/idempotency.md)を参照してください。

## `POST /v1/batches`

最大10,000件の項目を送信します([リファレンス](/ja/api-reference/create-batch.md))。各項目はタスクのフィールド `taskType`、`payload`、`priority`、`idempotencyKey` に加え、結果にそのまま返る任意の `customId`(最大128文字)を受け付けます。`webhook.url` は項目ではなくバッチに指定してください。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/batches \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "daily-2026-10-19",
    "webhook": { "url": "https://hooks.example.com/querying" },
    "metadata": { "run": "daily" },
    "items": [
      { "customId": "crm-chatgpt-us", "taskType": "CHATGPT", "payload": { "prompt": "best CRM for a small team", "country": "US" } },
      { "customId": "crm-gemini-us", "taskType": "GEMINI", "payload": { "prompt": "best CRM for a small team", "country": "US" } }
    ]
  }'
```

レスポンスは `202` でバッチを返します。最初の項目は既に送信されています。

```json theme={"theme":"css-variables"}
{
  "success": true,
  "batch": {
    "id": "3f6b2a10-...",
    "status": "OPEN",
    "total": 2,
    "counts": { "pending": 0, "queued": 2, "processing": 0, "completed": 0, "failed": 0, "rejected": 0 },
    "createdAt": "2026-10-19T09:00:00.000Z",
    "completedAt": null,
    "idempotencyKey": "daily-2026-10-19",
    "webhook": { "url": "https://hooks.example.com/querying" },
    "metadata": { "run": "daily" }
  }
}
```

### エンベロープのルール

| フィールド | ルール |
| - | - |
| `items` | 1〜10,000個のオブジェクト |
| `webhook.url` | タスクと同じ[URLのルール](/ja/concepts/webhooks.md#urlのルール)。すべての項目に適用されます。 |
| `metadata` | JSONで8 KB以下のオブジェクト。そのまま返されます |
| `idempotencyKey` | 1〜256文字。重複時は最初のバッチを `200` で返します。 |
| 項目の `idempotencyKey` | バッチ内で一意である必要があります |
| 項目の `webhook` | 拒否されます。バッチの `webhook.url` を使ってください。 |

### すべてか無しかの検証

何かを保存する前に、すべての項目に単発タスクと同じ検査(フィールド、キーの範囲、非公開エンジン、専用エンドポイント、地域、`payload.location`)を行います。1件でも失敗すると、レスポンスは `400 VALIDATION_ERROR` で何も保存されず、`details` に失敗した項目を最大50件示します。

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "1 of 2 items are invalid; the batch was not stored",
    "details": {
      "invalidItems": 1,
      "items": [
        { "index": 1, "code": "VALIDATION_ERROR", "message": "Request validation failed", "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }] }
      ]
    },
    "timestamp": "2026-10-19T09:00:00.000Z"
  }
}
```

### 項目の実行

バッチは、プランの上限とエンジンのキューに空きがあるときに項目をタスクとして投入します。アカウントは順番に処理されるため、大きなバッチが他のアカウントの小さなバッチを妨げることはありません。投入された項目は単発タスクと同じ受け付け処理を通り、クレジットを確保し、キーの1日のクレジット上限にも計上されます。

項目が拒否されたときの扱いはコードで決まります。

| コード | 項目 |
| - | - |
| `PLAN_CONCURRENCY_LIMIT`、`KEY_DAILY_CREDIT_LIMIT`、`SERVER_OVERLOADED`、`DB_UNAVAILABLE`、`ENQUEUE_ERROR` | `PENDING` のまま残り、後で再度試行されます |
| `QUEUE_BACKPRESSURE`、`ENGINE_UNAVAILABLE` | `PENDING` のまま残り、後で再度試行されます |
| `API_KEY_INACTIVE` | `REJECTED`: バッチのキーが無効化または期限切れになったか、そのサブアカウントが停止されました |
| `INSUFFICIENT_CREDITS` を含むその他のコード | `REJECTED` |

保留中の項目がなくなり、すべてのタスクが終了すると、バッチは `COMPLETED` になります。`webhook.url` がある場合、サーバーはその後 [`batch.completed` イベント](/ja/concepts/webhooks#バッチ完了イベント)をPOSTします。

### 進捗と結果を読み取る

`GET /v1/batches/{id}` は、項目のステータス(`pending`、`queued`、`processing`、`completed`、`failed`、`rejected`)ごとの `counts` を含むバッチを返します。これをポーリングすると、保留中の項目の投入も進みます。

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/batches/3f6b2a10-... \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

`GET /v1/batches/{id}/items` は項目を送信順に一覧します。

```bash theme={"theme":"css-variables"}
curl "https://api.querying.ai/v1/batches/3f6b2a10-.../items?status=completed&include=response&limit=20" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

| クエリ | 説明 |
| - | - |
| `status` | `pending`、`queued`、`processing`、`completed`、`failed`、`rejected` のいずれか |
| `include=response` | 終了した各タスクの `response` または `error` を追加します |
| `limit` | 既定値100、最大1,000。`include=response` の場合は既定値20、最大100。 |
| `cursor` | 前のページの `nextCursor` |

```json theme={"theme":"css-variables"}
{
  "success": true,
  "items": [
    {
      "index": 0,
      "customId": "crm-chatgpt-us",
      "taskType": "CHATGPT",
      "status": "COMPLETED",
      "taskId": "8f2c1e40-...",
      "completedAt": "2026-10-19T09:01:40.000Z",
      "response": { "text": "...", "sources": [] }
    }
  ],
  "nextCursor": null
}
```

`REJECTED` の項目は `error: { code, message }` を持ちます。結果本文が含まれるのは、[非同期タスク](/ja/concepts/async-tasks.md#保持期間)の24時間のポーリング期間内だけです。[バッチを取得](/ja/api-reference/get-batch.md)と[バッチ項目を一覧](/ja/api-reference/list-batch-items.md)も参照してください。

## `POST /v1/async/task/grid`

中心の周囲にある正方形グリッドのすべての地点から、1つのプロンプトを問い合わせます([リファレンス](/ja/api-reference/create-task-grid.md))。各地点はその地点を `payload.location` とするタスクになるため、エンジンは位置を受け付けるもの(`CHATGPT`、`GEMINI`、`GOOGLE`、`AIMODE`、`GOOGLE_SERP`)である必要があります。`payload.location` は自分で指定しないでください。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task/grid \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "CHATGPT",
    "idempotencyKey": "soho-coffee-2026-10-19",
    "payload": { "prompt": "best coffee shops near me for working on a laptop", "country": "US" },
    "grid": { "center": { "latitude": 40.72288, "longitude": -73.99875 }, "size": 3, "radiusMeters": 1500 }
  }'
```

| フィールド | ルール |
| - | - |
| `grid.size` | 1辺あたり `3`、`5`、`7`、`9` 地点(9〜81タスク) |
| `grid.radiusMeters` | 100〜50,000。中心から各辺の中点までの距離です。地点の間隔は `2 × radius ÷ (size − 1)` です。 |
| `grid.center` | 10進数の緯度と経度。グリッドは緯度89度未満に収まる必要があります。 |
| `idempotencyKey` | 任意、1〜200文字。これがグリッドidになります。 |
| `priority`、`webhook` | すべての地点に適用されます |

行0が北端、列0が西端です。レスポンスは `grid`(`id` と `spacingMeters` を含む)、`summary`、行順の `points` を返し、各地点は `row`、`col`、`location` と、`task` または `error` のどちらかを持ちます。

中心点が最初に単独で受け付けられます。中心点が拒否された場合(たとえば `422 LOCATION_UNSUPPORTED`、`403 KEY_SCOPE_DENIED`、`402 INSUFFICIENT_CREDITS`、またはプランの上限に達している場合)、そのエラーがグリッド全体のレスポンスとなり、タスクは作成されません。中心点より後に容量の理由で拒否された地点は、`success: false` としてその場で失敗します。

グリッドは [`GET /v1/async/task/grid/{id}`](/ja/api-reference/get-task-grid) で読み取れます。`?include=response` を付けると、終了したタスクの結果が加わります。受け付けられなかった地点は含まれず、他のアカウントのグリッドidは `404` を返します。同じグリッドを同じidで再送信すると、欠けている地点だけが受け付けられます。[冪等性](/ja/concepts/idempotency.md#位置グリッド)を参照してください。

## 次のステップ

> **[冪等性](/ja/concepts/idempotency.md)**
>
> 各エンドポイントが重複したキーをどう扱うか。

> **[クレジットと上限](/ja/concepts/credits-and-limits.md)**
>
> プランの同時実行数とペース配分。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.