---
title: ジョブ API
description: ジョブの一覧表示と確認、状態変更のストリーミング、キャンセル可能な処理の停止、結果リンクの再発行を行います。
species: reference
---
# ジョブ API

ジョブは、非同期処理の永続的な記録です。クエリジョブは、公開ステータス `queued`、`running`、`succeeded`、`failed`、`cancelled` を提供します。

## ジョブを一覧表示

```endpoint
GET /jobs
```

新しい順にジョブを返します。`limit` のデフォルトは 20 で、1～100 を指定できます。`has_more` が true の場合は、`next_cursor` を `starting_after` として渡してください。

## ジョブを 1 件取得

```endpoint
GET /jobs/{id}
```

現在のステータス、タイムスタンプ、種類、失敗情報を返します。`404 job_not_found` は、未知の ID と別の組織のジョブを区別しません。

## イベントを追跡

```endpoint
GET /jobs/{id}/events
```

この Server-Sent Events ストリームは、各データイベントに、安定した単調増加の `id` を付与します。`Last-Event-ID` を指定して再接続してください。ストリームは再試行間隔を 5 秒と通知し、3 秒ごとに永続化された状態を確認し、25 秒ごとにハートビートコメントを送信します。

接続は、ウェブ側の 120 秒の制限に達する少し前に閉じられます。再接続し、最終状態の判断には必ず `GET /jobs/{id}` を正として使用してください。無効なイベント ID は `400 invalid_last_event_id` を返します。

## 結果を取得

```endpoint
GET /jobs/{id}/result
```

成功したクエリジョブについて、有効期間が 1 時間の、新たに署名された Parquet URL を返します。これらの URL は、データへのアクセスを可能にするシークレットとして扱ってください。

## キャンセル

```endpoint
POST /jobs/{id}/cancel
```

待機中の処理はアトミックにキャンセルされます。実行中のクエリのキャンセルはベストエフォートで、`execution_may_continue: true` を返す場合があります。エンジンがすでに受け付けた処理は、完了する可能性があるためです。ジョブをポーリングして最終状態を確認してください。

`GET /version` は、レスポンスヘッダーで通知される公開 API の契約バージョンを返します。