ワークフロー実行
Workflow Runs のドキュメント
Workflow Runs
ベースパス: /api/v1/workflow-runs
ワークフロー実行はワークフローの単一実行インスタンスです。ワークフローを実行し、SSE でリアルタイムに進捗を監視し、実行をキャンセルできます。
注記: 一覧、取得、ダッシュボード統計、キャンセルエンドポイントは
privateSvcAuthMiddlewareを使用し、有効な JWT（バックエンド経由のユーザー向け呼び出し）または プライベート IP / 信頼済み内部呼び出しを受け付けます。フロントエンドアプリは JWT で直接呼び出すのではなく、自前のバックエンド経由でプロキシしてください。
エンドポイント概要
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/v1/workflow-runs/execute | JWT/Key or internal | ワークフローを実行（ブロッキング） |
| POST | /api/v1/workflow-runs/execute/stream | JWT/Key or internal | ワークフローを実行（SSE ストリーム） |
| POST | /api/v1/workflow-runs/cancel | JWT/Key or internal | 1 件以上の実行をキャンセル |
| GET | /api/v1/workflow-runs | JWT/Key or internal | ワークフロー実行を一覧 |
| GET | /api/v1/workflow-runs/dashboard/:workflowId | JWT/Key or internal | ステータス別実行件数を取得 |
| GET | /api/v1/workflow-runs/:runId | JWT/Key or internal | 単一実行とアクティビティ実行を取得 |
POST /api/v1/workflow-runs/execute
ワークフローを同期的（ブロッキング）に実行します。結果を返す前にワークフロー完了を待ちます。
警告: 長時間実行になる場合があります。UI アプリではストリーミングエンドポイントを推奨します。
リクエストボディ（multipart/form-data）
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
workflowId | string (UUID) | Yes | – | 実行するワークフローの ID |
inputs | JSON object | No | {} | 入力名をキーとした入力値 |
envs | JSON object | No | {} | 環境変数の上書き（文字列から文字列） |
レスポンス 200 OK
POST /api/v1/workflow-runs/execute/stream
ワークフローを実行し、SSE でリアルタイム進捗更新をストリームします。
リクエストボディ（multipart/form-data）
ブロッキング実行エンドポイントと同じフィールド: workflowId、inputs、envs。
レスポンス
SSE ストリームを返します（Content-Type: text/event-stream）。
SSE イベント:
| Event | Data Shape | Description |
|---|---|---|
ping | { "content": "ping" } | 9 秒ごとのキープアライブ |
activity-run | { "content": { "workflowRunId": "...", "status": "..." } } | アクティビティ（ステップ）ステータス更新 |
workflow-run | { "content": { "workflowRunId": "...", "status": "..." } } | ワークフロー実行ステータス更新 |
thinking | { "content": "<text>", "stepId": "...", "activityRunId": "..." } | ステップの AI 推論トレース |
result | { "success": true, "workflowRun": { ... } } | 完了時の最終結果 |
error | { "error": "...", "details": "..." } | 実行失敗 |
例（JavaScript）
POST /api/v1/workflow-runs/cancel
1 件以上のワークフロー実行をキャンセルします。特定の実行 ID またはワークフローの全実行をキャンセルできます。
リクエストボディ（JSON）
runIds または workflowId のいずれかを指定（両方は不可）。
| Field | Type | Required | Description |
|---|---|---|---|
runIds | string[] | No* | キャンセルする実行 ID の配列 |
workflowId | string (UUID) | No* | このワークフローの非終端実行をすべてキャンセル |
reason | string | No | キャンセル理由（最大 500 文字） |
*runIds または workflowId の少なくとも一方が必要です。
レスポンス 200 OK
結果ステータス値:
| Status | Description |
|---|---|
cancelled | 正常にキャンセルされた |
already_completed | 実行は既に終端状態（completed/failed） |
not_eligible | 既にキャンセル済み、または Temporal ワークフローがない |
not_found | 実行 ID が見つからない |
error | キャンセル失敗（Temporal エラー） |
GET /api/v1/workflow-runs
オプションのフィルター付きでワークフロー実行を一覧します。
クエリパラメータ
| Parameter | Type | Default | Description |
|---|---|---|---|
workflowId | string (UUID) | – | ワークフロー ID でフィルター |
status | string | – | ステータスでフィルター: scheduled、running、completed、failed、cancelled、waiting |
page | number | 1 | ページ番号 |
limit | number | 10 | 1 ページあたり件数（最小: 1、最大: 100） |
search | string | – | ワークフロー名で検索 |
レスポンス 200 OK
ワークフロー実行フィールド:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | 実行 ID |
workflowId | string (UUID) | 親ワークフロー ID |
workflowName | string | null | 実行時点のワークフロー名 |
status | string | 実行ステータス |
inputs | array | この実行で使用した入力値 |
createdAt | string (ISO 8601) | 実行作成日時 |
updatedAt | string (ISO 8601) | 最終ステータス更新日時 |
実行ステータス値: scheduled、running、completed、failed、cancelled、waiting
GET /api/v1/workflow-runs/dashboard/:workflowId
特定ワークフローのステータス別実行件数内訳を返します。ダッシュボードウィジェット向けです。
パスパラメータ
| Parameter | Type | Description |
|---|---|---|
workflowId | string (UUID) | ワークフロー ID |
レスポンス 200 OK
GET /api/v1/workflow-runs/:runId
すべてのアクティビティ（ステップ）実行を含む単一ワークフロー実行を返します。
パスパラメータ
| Parameter | Type | Description |
|---|---|---|
runId | string (UUID) | ワークフロー実行 ID |
レスポンス 200 OK
アクティビティ実行フィールド:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | アクティビティ実行 ID |
stepId | string | ワークフローステップ ID |
stepName | string | null | ステップ名 |
status | string | ステップステータス |
outputs | object | null | ステップ出力データ |
attempt | number | リトライ試行回数（1 始まり） |
createdAt | string (ISO 8601) | 開始日時 |
updatedAt | string (ISO 8601) | 最終更新日時 |