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

# 非同期ジョブ

> `jobs` エンドポイントはスクリーンショットタスクをキューに入れ、ステータスと結果をポーリングできます — 大量処理や長時間のキャプチャに最適です。

## はじめに

### ベース URL

```
https://screenshot.cleariflow.com/v1/jobs
```

## ジョブの作成

同期エンドポイントと同じ `ScreenshotRequest` ペイロードで非同期スクリーンショットジョブをキューに追加します。

### リクエスト例

```bash theme={"system"}
curl -X POST 'https://screenshot.cleariflow.com/v1/jobs' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "api_key": "YOUR_UNIQUE_API_KEY",
      "url": "https://cleariflow.com"
    },
    "priority": 10
  }'
```

成功したリクエストはジョブ ID を返します：

<ResponseExample>
  ```json theme={"system"}
  {
    "job_id": "550e8400-e29b-41d4-a716-446655440000"
  }
  ```
</ResponseExample>

### ジョブ作成パラメータ

<ParamField body="request" type="Object" required>
  同期スクリーンショットエンドポイントと同じフィールド（`url`、`render`、`actions`、`cookies` など）を持つ `ScreenshotRequest` オブジェクト。
</ParamField>

<ParamField body="priority" type="Integer">
  ジョブの優先度。値が大きいほど先に処理されます。デフォルト: 0。
</ParamField>

## ジョブステータスの取得

ID でジョブをポーリングし、ステータスを確認して完了後に結果を取得します。

### ベース URL

```
https://screenshot.cleariflow.com/v1/jobs/{job_id}
```

### リクエスト例

```bash theme={"system"}
curl 'https://screenshot.cleariflow.com/v1/jobs/550e8400-e29b-41d4-a716-446655440000'
```

ジョブ実行中：

<ResponseExample>
  ```json theme={"system"}
  {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "running"
  }
  ```
</ResponseExample>

ジョブが正常に完了した場合：

<ResponseExample>
  ```json theme={"system"}
  {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "done",
    "result": {
      "ok": true,
      "image_base64": "/9j/4AAQSkZJRg...",
      "content_type": "image/jpeg",
      "meta": {
        "elapsed_ms": 8123
      }
    }
  }
  ```
</ResponseExample>

### ジョブステータス値

| ステータス     | 説明                              |
| --------- | ------------------------------- |
| `queued`  | ジョブはキューで待機中です。                  |
| `running` | ブラウザセッションがアクティブです。              |
| `done`    | スクリーンショット完了；`result` に出力が含まれます。 |
| `failed`  | スクリーンショット失敗；`error` に説明が含まれます。  |

### レスポンスパラメータ

<ResponseField name="job_id" type="String">
  非同期ジョブの一意の識別子。
</ResponseField>

<ResponseField name="status" type="String">
  現在のジョブステータス: `queued`、`running`、`done` または `failed`。
</ResponseField>

<ResponseField name="result" type="Object">
  スクリーンショット結果オブジェクト（同期エンドポイントのレスポンスと同じ構造）。`status` が `done` のときに存在します。
</ResponseField>

<ResponseField name="error" type="String">
  エラーメッセージ。`status` が `failed` のときに存在します。
</ResponseField>

<ResponseField name="meta" type="Object">
  ジョブ実行に関する追加メタデータ。
</ResponseField>