> ## 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.

# 非同期タスク

> タスクのライフサイクル、ステータス、優先度、保持期間。

同期エンドポイントはありません。AIエンジンへの問い合わせには数秒から数分かかるため、すべての
リクエストは後から受け取る永続的なキュータスクになります。

## ライフサイクル

```mermaid theme={null}
stateDiagram-v2
    [*] --> QUEUED: POST /v1/async/task
    QUEUED --> PROCESSING: worker claims
    PROCESSING --> COMPLETED: engine answered
    PROCESSING --> FAILED: retries exhausted
    PROCESSING --> QUEUED: transient error, requeued
    COMPLETED --> [*]: polling expires after 24h
    FAILED --> [*]: polling expires after 24h
```

## ステータス

<ResponseField name="QUEUED" type="status">
  受け付けられ、永続化された状態です。ワーカーを待っています。
</ResponseField>

<ResponseField name="PROCESSING" type="status">
  ワーカーがタスクのリースを保持し、エンジンを操作しています。
</ResponseField>

<ResponseField name="COMPLETED" type="status">
  終了状態です。`response` フィールドが設定されます。
</ResponseField>

<ResponseField name="FAILED" type="status">
  終了状態です。`error` フィールドに理由が入ります。
</ResponseField>

一時的な失敗(エンジンのタイムアウト、一時的なエラー)に遭遇したタスクは `QUEUED` に戻り、再試行されます。
再試行を使い切って初めて `FAILED` に確定するため、`PROCESSING → QUEUED` の遷移は正常であり、
アラート対象ではありません。

## 優先度

`priority` は互換性のために残されており、タスクのメタデータにそのまま返されます。`1` から `10` を受け付け、
既定値は `1` です。範囲外の値は拒否せず範囲内に丸めます。

```json theme={null}
{ "taskType": "GEMINI", "priority": 8, "payload": { "prompt": "..." } }
```

実行順序は優先度、送信時刻、アカウントのいずれによっても保証されません。依存する処理は、前のタスクが
完了してから次を送信してください。プランの同時実行上限は、待機中と処理中のタスクの両方に適用されます。

## 保持期間

終了したタスクは**完了後24時間**、公開ポーリングで取得できます。それ以降、`GET /v1/async/task/{id}` は
存在しなかったidと同じ `404 NOT_FOUND` を返します。元のレコードは永久に保持されます。期限切れは公開
ポーリングと手動のWebhook再送を制限するだけで、保存を制限するものではありません。自動のWebhook再試行は
これとは独立して続きます。

Webhookではなくポーリングに頼る場合は、この期間内に余裕をもって結果を回収してください。

## Webhookとポーリングの選択

Webhookを推奨します。ポーリングは復旧用の経路です。

| | Webhook | ポーリング |
| - | - | - |
| 結果までの遅延 | 完了と同時 | ポーリング間隔 |
| APIへの負荷 | タスクごとにPOST 1回 | タスクごとにポーリング回数分のGET |
| 公開エンドポイント | 必要 | 不要 |
| 自サーバー停止時 | 約30分再試行後に破棄 | 24時間は取得可能 |

堅牢なクライアントは両方を使います。Webhookを速い経路として受け取り、通知を受け取れなかったタスクは
保持期間が終わる前にポーリングで照合してください。