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

# 実行ステータス取得

> エージェント実行のステータスを確認する API

# 実行ステータス取得

エージェント実行の現在のステータスを取得します。長時間実行されるエージェントの進行状況をポーリングする場合に使用します。

## リクエスト

```
GET /api/v1/agent/run/{runId}/status
```

### パスパラメータ

| パラメータ   | 型        | 説明          |
| ------- | -------- | ----------- |
| `runId` | `string` | エージェント実行 ID |

### ヘッダー

| ヘッダー            | 必須 | 説明                             |
| --------------- | -- | ------------------------------ |
| `Authorization` | はい | `Bearer snorbe_...` 形式の API キー |

## レスポンス

```json theme={null}
{
  "id": "clxyz...",
  "status": "completed",
  "createdAt": "2026-04-16T09:36:01.351Z",
  "updatedAt": "2026-04-16T09:36:08.352Z",
  "pendingPlanDraft": false,
  "pendingReportDraft": false,
  "pendingMatrixDraft": false,
  "browseState": {
    "isBrowsing": true,
    "askHumanQuestion": "ログイン後の画面でどのメニューを開きますか？"
  },
  "skillState": {
    "isRunningSkill": true,
    "skillName": "patent-search",
    "pendingSecretKeys": ["PATENT_API_KEY"]
  }
}
```

### レスポンスフィールド

| フィールド                          | 型          | 説明                                           |
| ------------------------------ | ---------- | -------------------------------------------- |
| `id`                           | `string`   | エージェント実行 ID                                  |
| `status`                       | `string`   | ステータス（`"completed"`、`"running"`、`"error"` 等） |
| `createdAt`                    | `string`   | 作成日時（ISO 8601）                               |
| `updatedAt`                    | `string`   | 更新日時（ISO 8601）                               |
| `pendingPlanDraft`             | `boolean`  | プラン案の確認待ちかどうか                                |
| `pendingReportDraft`           | `boolean`  | レポート案の確認待ちかどうか                               |
| `pendingMatrixDraft`           | `boolean`  | マトリクス案の確認待ちかどうか                              |
| `browseState`                  | `object`   | browse ツールが実行中の場合のみ返ります                      |
| `browseState.isBrowsing`       | `boolean`  | ブラウザ操作が継続中かどうか                               |
| `browseState.askHumanQuestion` | `string`   | browse 中に人間の回答待ちになっている質問。ない場合は省略             |
| `skillState`                   | `object`   | skill ツールが実行中、または secret 入力待ちの場合のみ返ります       |
| `skillState.isRunningSkill`    | `boolean`  | skill セッションが実行中かどうか                          |
| `skillState.skillName`         | `string`   | 実行中または secret を要求している skill 名                |
| `skillState.pendingSecretKeys` | `string[]` | 登録待ちの secret キー名                             |

<Note>
  `pendingPlanDraft`、`pendingReportDraft`、`pendingMatrixDraft` が `true` の場合、対応する HITL エンドポイントで確認を完了させる必要があります。その後、[エージェント実行（ストリーミング）](/ja/api-reference/stream-agent-run) のレジュームエンドポイントで実行を再開できます。
</Note>

<Note>
  `browseState.askHumanQuestion` が返った場合は、プラン確認ではなくブラウザ操作中の質問です。`/agent/run/{runId}/...` ではなく `/browser/answer-question` に回答を送ります。回答には、実行中の SSE で受け取った `browse-start.payload.websocketInfo.session_id` が必要です。
</Note>

<Note>
  `skillState.pendingSecretKeys` に値がある場合は、skill が secret 登録待ちです。各キーを `/secret` に登録すると、待機中の skill 実行が再開できます。
</Note>

## 使用例

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://app.snorbe.deskrex.ai/api/v1/agent/run/clxyz123/status" \
    -H "Authorization: Bearer snorbe_your_api_key_here"
  ```

  ```python Python theme={null}
  import requests
  import time

  run_id = "clxyz123"

  while True:
      resp = requests.get(
          f"https://app.snorbe.deskrex.ai/api/v1/agent/run/{run_id}/status",
          headers={"Authorization": "Bearer snorbe_your_api_key_here"},
      )
      data = resp.json()
      print(f"Status: {data['status']}")

      if data["status"] == "completed":
          print("Done!")
          break
      if data["status"] == "error":
          print(f"Error occurred")
          break

      time.sleep(5)
  ```
</CodeGroup>

## エラーレスポンス

| HTTP ステータス | 説明             |
| ---------- | -------------- |
| 401        | API キーが無効      |
| 400        | 無効な `runId` 形式 |