イベント実行ステータスの取得

メソッド

この API は REST の方法論に従います。

HTTP メソッド

GET: オンボーディングイベント実行のライブステータスを読み取ります — プラグインの Setup 進行ステッパーを駆動するポーリングです。

すべてのオンボーディングトリガー（rules、components、component-captures、resync）は eventRunId を返します。このエンドポイントはそのハンドルを進行状況に変換します。

オンボーディング実行は内部実行です — ai-status Webhook を発行せず、PostgreSQL の行にも触れません。したがってこのステータス文書が、外部から実行を観測する 唯一の 手段です。

命名規則

レスポンスは内部の wf2des-api データプレーンから 逐語でプロキシ されるため、フィールドは本 API の他の部分で使われる camelCase ではなく snake_case です。形状はワーカーが所有します。

リクエストとレスポンス

ヘッダー

リクエストヘッダー

Authorization
Accept
Accept-language

レスポンスヘッダー

Content-Type

イベントステータスの取得

URI

GET /api/v1/organizations/{organization_id}/projects/{project_id}/wf2des/events/{event_run_id}/status

パスパラメータ

名前	型	必須	説明
organization_id	integer	必須	組織 ID（正の整数）
project_id	integer	必須	プロジェクト ID（正の整数）
event_run_id	string	必須	トリガー側エンドポイントが返した `eventRunId`

レスポンス

レスポンスは JSON です（HTTP ステータス: 200 OK）。

{
  "event_run_id": "0190f3a1-2c4e-7b8d-9e0f-1a2b3c4d5e70",
  "event_type": "rule_upload",
  "state": "processing",
  "stage": "extract",
  "progress": { "done": 18, "total": 60 },
  "result": null,
  "error": null
}

レスポンスフィールド

名前	型	説明
event_run_id	string	この文書が示す実行。
event_type	string	生成元のトリガー — `rule_upload` / `component_upload` / `component_capture` / `resync`。
state	string	実行中は `processing`、成功時は `done`、終端的な失敗時は `failed`。
stage	string \| null	実行内部の名前付きステップ（ルール取り込み中の `extract` など）。ワーカー定義であり変更されうる。
progress	object \| null	総数が判明している場合は `{ done, total }`、それ以外は `null`。ルール取り込みはボード 1 枚を 1 単位として報告する。
result	object \| null	`state: "done"` のとき設定される — 例: 作成されたルールの `version` とボード数。
error	string \| null	`state: "failed"` のとき設定される。

この文書には TTL があります。完了から時間の経った実行のステータスは最終的に失効し、404 を返すようになります。これは失敗ではなく失効です。

認証

認証は Amazon Cognito が発行する JSON Web Token（JWT）で行われます。加えて、呼び出し元はプロジェクトへのアクセス権を保持している必要があります。

エラーハンドリング

説明	ステータスコード	ステータス名
認証情報の欠落	401	Unauthorized
権限不足	403	Forbidden
イベントステータスが見つからない（未知の `event_run_id`、または TTL 失効）	404	Not Found
上流の読み取り失敗（wf2des-api へ到達不可またはエラー）	500	Internal Server Error

トリガー直後の 404 は正常かつ一時的です: ステータス文書はワーカーがメッセージを取得した時点で書き込まれるため、SQS 配送と競合したポーリングはまだ何も見つけられません。クライアントは早期の 404 を「未開始」として扱い、ポーリングを継続してください。

処理フロー

パスパラメータから組織 ID、プロジェクト ID、event_run_id を取得する。
ユーザーがプロジェクトへのアクセス権を持つことを検証する。
組織とプロジェクトにスコープした上で、内部 wf2des-api データプレーンへ読み取りをプロキシする（X-AI-Service-Token）。
ステータス文書を逐語で返す。存在しない場合は 404 を返す。

バックエンドは文書を解釈も再整形もしません — 形状はワーカー所有であり、バックエンドを変更せずに新しいステージが現れることがあります。