バッチ出力ファイルの署名付きダウンロード URL を取得します。
GET /api/v1/forward/batches/{batch_id}/output
output.jsonl の OSS プリサインドダウンロード URL を返します。バッチは終端状態でなければならず、そうでない場合は 400 batch_not_ready を返します。
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT または SAT> |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
batch_id | string | Yes | バッチ ID。 |
Example request
Example response
HTTP 200 OK
Response fields
| Field | Type | Description |
|---|---|---|
url | string | OSS プリサインドダウンロード URL。Expires / OSSAccessKeyId / Signature および response-content-disposition を含みます。ダウンロード時のファイル名は batch-<batch_id>-output.jsonl です。 |
expires_at | string | リンクの有効期限。RFC 3339。この時刻までにダウンロードを完了する必要があります。 |
output.jsonl の行形式
各 Batch Task が 1 行に対応します。
template_id と identity_id は常に出力されます。session_id は Session が作成された場合にのみ出力されます。started_at と completed_at は RFC 3339 UTC 文字列で、値がない場合は null です。started_at は、永続化された最終実行試行の開始時刻を示します。
成功した行では response と error: null を出力します。それ以外のステータスでは response: null と {"code": string, "message": string} を出力します。有効な JSON 結果は response.body として直接返され、通常のテキストは {"text": ...} でラップされます。
artifacts は空でない場合にのみ行のトップレベルに現れます。各項目は file_id、name、size を使用し、提供元に値がある場合は content_type も含みます。filename や size_bytes は返さず、response.body 内にも artifacts を重複して含めません。
usage は、タスクに有効な CAS Session 使用量が永続化されている場合に行のトップレベルに現れます。現在は total_credits を含みます。明示的なゼロ値は保持され、使用量がないか無効な場合は省略されます。単位は CAS Credit であり、token 数や金額ではありません。一時的なエラーの再試行で新しい Session が作成された場合、最終または現在の Session の使用量のみを記録し、置き換えられた過去の Session 使用量は加算しません。
error.jsonl の行形式
失敗した行では元の body を保持し、output 行と同じステータス、Session/Template/Identity、時刻、構造化エラー、および任意のトップレベル artifacts を含めます。現在、error.jsonl は usage を出力しません。
body.resources は保持されます。Session の作成前に失敗した場合、session_id は省略されます。
invalid_line、config_error、permission_denied、および再試行を使い切った後の transient_error があります。失敗メッセージには安全な分類説明を使用し、ファイル所有者、上流の内部状態、ファイルが実際に存在するかどうかを示すメタデータは返しません。
Error codes
| HTTP | Type | Code | Trigger |
|---|---|---|---|
| 400 | invalid_request_error | batch_not_ready | バッチが終端状態ではありません。 |
| 404 | not_found_error | batch_not_found | バッチが存在しない、他ユーザーのもの、または出力ファイルが未生成です。 |
| 410 | not_found_error | file_expired | 出力ファイルは 30 日保持期間を過ぎて削除されています。 |
| 401 | authentication_error | authentication_required | PAT または SAT が無効、もしくは期限切れです。 |
Notes
- 出力ファイルは 30 日間保持されます。保持期間を過ぎると
410 file_expiredを返します。 - ダウンロードファイル名は
batch-<batch_id>-output.jsonlです。 - 失敗行の結果は
output.jsonlとerror.jsonlの両方に含まれます。後者は Batch の/errorエンドポイントからダウンロードします。 - Batch 結果ファイルは Forward の汎用ファイルリソースとして登録されないため、
/api/v1/forward/files/{file_id}または/contentから取得できません。