ジョブ

Show:

ジョブは、ドキュメントの取り込みや埋め込み、APIタスクの実行などの非同期作業単位を表します。/v1/jobs エンドポイントを使用して、組織内のジョブを検査、制御、クリーンアップします。

Note: すべての /v1/jobs エンドポイントは、Authorization: Bearer <token> ヘッダーにワークスペースAPIキーが必要です。読み取り操作は有効なキーを受け入れますが、書き込み操作（cancel、reprocess、delete）には jobs:write スコープが必要です。

Job object

Field	Type	Description
`id`	`string`	ユニークなジョブ識別子。
`org_id`	`string`	ジョブを所有する組織。
`bucket_id`	`string`	ジョブが属するバケット。
`collection_id`	`string \| null`	ジョブが対象とするコレクション（ある場合）。
`document_id`	`string \| null`	リンクされた取り込みドキュメント（ある場合）。
`workflow_id`	`string \| null`	リンクされたワークフロー（ある場合）。
`source_entry_id`	`string \| null`	リンクされたソースエントリ（ある場合）。
`priority`	`integer`	数字が小さいほど先に実行されます（デフォルト `2`）。
`status`	`string`	`queued`、`extracting`、`chunking`、`embedding`、`indexing`、`ready`、`failed`、`cancelled` のいずれか。
`s3_key`	`string`	ソースファイルまたはアーティファクトのストレージキー。
`file_name`	`string`	元のファイル名。
`file_size`	`integer`	ファイルサイズ（バイト単位）。
`file_type`	`string \| null`	ファイルタイプ、例：`pdf`、`txt`、`embed_bulk`。
`processing_type`	`string \| null`	`source_connector`、`bucket_page_reindex`、または他のタスクタイプ。
`estimated_cost`	`number`	キュー時の推定コスト。
`actual_cost`	`number \| null`	完了後の実際のコスト。
`chunks_count`	`integer \| null`	生成されたチャンクの数（該当する場合）。
`failed_phase`	`string \| null`	失敗したフェーズ（ステータスが `failed` の場合）。
`error_category`	`string \| null`	カテゴリ化されたエラー理由。
`error_message`	`string \| null`	人間が読めるエラーメッセージ。
`retryable`	`boolean \| null`	失敗が再試行可能かどうか。
`retry_count`	`integer`	再試行の試行回数。
`reprocess_of_job_id`	`string \| null`	このジョブが再処理の再試行である場合の元のジョブID。
`worker_id`	`string \| null`	現在ジョブを処理しているワーカー。
`scheduled_at`	`string \| null`	ISO 8601スケジュール時間（延期された場合）。
`started_at`	`string \| null`	ISO 8601処理開始時間。
`completed_at`	`string \| null`	ISO 8601完了時間。
`created_at`	`string`	ISO 8601作成時間。
`updated_at`	`string`	ISO 8601最終更新時間。
`metadata_snapshot`	`object \| null`	監査の安全性のための元のドキュメントメタデータのスナップショット。

GET /v1/jobs/{job_id}

IDで単一のジョブを取得します。

Path parameters

Parameter	Type	Required	Description
`job_id`	`string`	Yes	ジョブ識別子。

Response example

{
  "id": "job_01J8X...",
  "org_id": "org_abc123",
  "bucket_id": "bucket_legal",
  "collection_id": null,
  "document_id": "doc_01J8X...",
  "priority": 1,
  "status": "ready",
  "s3_key": "org_abc123/uploads/contract.pdf",
  "file_name": "contract.pdf",
  "file_size": 1048576,
  "file_type": "pdf",
  "estimated_cost": 0.05,
  "actual_cost": 0.047,
  "chunks_count": 42,
  "failed_phase": null,
  "error_category": null,
  "error_message": null,
  "retryable": null,
  "retry_count": 0,
  "reprocess_of_job_id": null,
  "worker_id": null,
  "scheduled_at": null,
  "started_at": "2026-06-19T04:12:00Z",
  "completed_at": "2026-06-19T04:12:08Z",
  "created_at": "2026-06-19T04:11:55Z",
  "updated_at": "2026-06-19T04:12:08Z",
  "metadata_snapshot": {
    "file_name": "contract.pdf",
    "source_path": "org_abc123/uploads/contract.pdf",
    "captured_at": "2026-06-19T04:11:55Z"
  }
}

Errors

Status	Cause
`404`	ジョブが見つからないか、組織に属していません。

GET /v1/jobs

組織のジョブを新しい順に一覧表示します。

Query parameters

Parameter	Type	Required	Default	Description
`bucket_id`	`string`	No	—	単一のバケットにフィルタリングします。
`status`	`string`	No	—	単一のステータスにフィルタリングします。
`limit`	`integer`	No	`50`	最大結果数。`1`から`200`の間で指定します。

Response example

[
  {
    "id": "job_01J8X...",
    "org_id": "org_abc123",
    "bucket_id": "bucket_legal",
    "status": "ready",
    "file_name": "contract.pdf",
    "file_size": 1048576,
    "file_type": "pdf",
    "priority": 1,
    "created_at": "2026-06-19T04:11:55Z",
    "updated_at": "2026-06-19T04:12:08Z"
  },
  {
    "id": "job_01J8Y...",
    "org_id": "org_abc123",
    "bucket_id": "bucket_hr",
    "status": "failed",
    "file_name": "handbook.docx",
    "file_size": 512000,
    "file_type": "docx",
    "priority": 2,
    "error_message": "Provider embedding timeout",
    "created_at": "2026-06-19T03:00:00Z",
    "updated_at": "2026-06-19T03:05:00Z"
  }
]

GET /v1/jobs/{job_id}/files

ジョブに関連付けられたファイルを一覧表示します。Schiftジョブは現在単一ドキュメントであるため、最大1つのファイルを返します。レスポンスの形状はOpenAIのvector_store.fileオブジェクトを反映しています。

Path parameters

Parameter	Type	Required	Description
`job_id`	`string`	Yes	ジョブ識別子。

Response example

{
  "object": "list",
  "data": [
    {
      "id": "doc_01J8X...",
      "object": "vector_store.file",
      "vector_store_id": "bucket_legal",
      "status": "uploaded",
      "filename": "contract.pdf",
      "created_at": "2026-06-19T04:11:55Z"
    }
  ],
  "has_more": false
}

Errors

Status	Cause
`404`	ジョブが見つからないか、組織に属していません。

GET /v1/jobs/{job_id}/download

ジョブに関連付けられたソースファイルをダウンロードします。レスポンスは添付ファイルのContent-Dispositionヘッダー付きのバイナリストリームとして返されます。

Path parameters

Parameter	Type	Required	Description
`job_id`	`string`	Yes	ジョブ識別子。

Response

バイナリファイルの内容。Content-Typeはジョブのfile_typeから取得され、デフォルトはapplication/octet-streamです。

Errors

Status	Cause
`404`	ジョブが見つからない、ジョブにファイルがない、またはストレージからファイルを取得できませんでした。

POST /v1/jobs/{job_id}/cancel

キューに入っているか進行中のジョブをキャンセルします。

Note: このエンドポイントには jobs:write スコープが必要です。

Path parameters

Parameter	Type	Required	Description
`job_id`	`string`	Yes	ジョブ識別子。

Query parameters

Parameter	Type	Required	Default	Description
`force`	`boolean`	No	`false`	ジョブが進行中でも強制キャンセルします。

Behavior

ジョブがすでに終端状態（ready、failed、cancelled）にある場合、レスポンスは現在のステータスをdetail: "job already in terminal state"と共に返します。
ジョブが進行中でforceがfalseの場合、エンドポイントは400を返し、?force=trueの使用を提案します。
force=trueの場合、ジョブは現在の進行中のステータスに関係なくcancelledとしてマークされます。

Response example

{
  "status": "cancelled"
}

Error examples

Status	Cause
`400`	進行中のジョブで`force=false`。
`404`	ジョブが見つからないか、組織に属していません。
`409`	ジョブがもはやキューに入っていない（競合状態）。

POST /v1/jobs/{job_id}/reprocess

失敗したか他の終端状態のジョブを再処理する新しいジョブを作成します。新しいジョブは元のソース、バケット、コレクション、優先度をコピーし、reprocess_of_job_idを介してリンクします。

Note: このエンドポイントには jobs:write スコープが必要です。

Path parameters

Parameter	Type	Required	Description
`job_id`	`string`	Yes	ジョブ識別子。

Response example

{
  "id": "job_01J8Z...",
  "org_id": "org_abc123",
  "bucket_id": "bucket_legal",
  "document_id": "doc_01J8X...",
  "status": "queued",
  "file_name": "contract.pdf",
  "file_size": 1048576,
  "priority": 1,
  "reprocess_of_job_id": "job_01J8X...",
  "created_at": "2026-06-19T05:00:00Z",
  "updated_at": "2026-06-19T05:00:00Z"
}

Errors

Status	Cause
`400`	ジョブが終端状態にありません。
`404`	ジョブが見つからないか、組織に属していません。

DELETE /v1/jobs/{job_id}

ジョブを削除します。進行中のジョブは削除できません。

Note: このエンドポイントには jobs:write スコープが必要です。

Path parameters

Parameter	Type	Required	Description
`job_id`	`string`	Yes	ジョブ識別子。

Response

成功時は204 No Content。

Errors

Status	Cause
`400`	進行中のジョブを削除できません。
`404`	ジョブが見つからないか、組織に属していません。

POST /v1/admin/reap-stale-jobs

長時間進行中のジョブを失敗としてマークします。このエンドポイントは、デッドワーカーからの回復のためにcronまたはプラットフォーム管理者向けです。

Note: このエンドポイントは通常のワークスペースAPIキーを使用しません。以下のいずれかを受け入れます：

Authorization: Bearer <token> に platform_admin JWTまたはAPIキー。

サーバーのCRON_SECRET環境変数と一致するX-Cron-Secretヘッダー。

Query parameters

Parameter	Type	Required	Default	Description
`timeout_minutes`	`integer`	No	`30`	ジョブが再処理されるまでにスタックしている必要がある時間。範囲は`1`–`1440`。

Request headers

Header	Required	Description
`X-Cron-Secret`	Conditional	クラウドスケジューラ/CLI呼び出し用のCronシークレット。
`Authorization`	Conditional	UIまたは手動使用のための`Bearer <platform_admin_token>`。

Response example

{
  "timeout_minutes": 30,
  "reaped_count": 2,
  "jobs": [
    {
      "job_id": "job_01J8X...",
      "org_id": "org_abc123",
      "stuck_status": "embedding"
    },
    {
      "job_id": "job_01J8Y...",
      "org_id": "org_def456",
      "stuck_status": "extracting"
    }
  ]
}

Errors

Status	Cause
`401`	有効な認証が提供されていません。
`403`	`X-Cron-Secret` ヘッダーが存在するが無効です。

ジョブ

Job object

GET /v1/jobs/{job_id}

Path parameters

Response example

Errors

GET /v1/jobs

Query parameters

Response example

GET /v1/jobs/{job_id}/files

Path parameters

Response example

Errors

GET /v1/jobs/{job_id}/download

Path parameters

Response

Errors

POST /v1/jobs/{job_id}/cancel

Path parameters

Query parameters

Behavior

Response example

Error examples

POST /v1/jobs/{job_id}/reprocess

Path parameters

Response example

Errors

DELETE /v1/jobs/{job_id}

Path parameters

Response

Errors

POST /v1/admin/reap-stale-jobs

Query parameters

Request headers

Response example

Errors

See also