Get Event-Run Status

Method

This API follows the REST methodology.

HTTP Method

GET: Read the live status of an onboarding event run — the poll behind the plugin's Setup progress stepper.

Every onboarding trigger (rules, components, component-captures, resync) returns an eventRunId. This endpoint turns that handle into live progress.

Onboarding runs are internal — they emit no ai-status webhook and touch no PostgreSQL row, so this status document is the only way to observe them from outside.

Naming Convention

The response is proxied verbatim from the internal wf2des-api data plane, so its fields are snake_case — unlike the camelCase used by the rest of this API. The shape is worker-owned.

Request and Response

Headers

Request Headers

• Authorization
• Accept
• Accept-language

Response Headers

• Content-Type

Get Event Status

URI

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

Path Parameters

Name	Type	Required	Description
organization_id	integer	Required	Organization ID (positive integer)
project_id	integer	Required	Project ID (positive integer)
event_run_id	string	Required	The eventRunId returned by the triggering endpoint

Response

The response is JSON (HTTP status: 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
}

Response Fields

Name	Type	Description
event_run_id	string	The run this document describes.
event_type	string	Which trigger produced it — rule_upload, component_upload, component_capture, or resync.
state	string	processing while the run is live; done on success; failed on a terminal failure.
stage	string | null	The named step inside the run (e.g. extract during rule ingestion). Worker-defined and free to change.
progress	object | null	{ done, total } when the run knows its total, otherwise null. Rule ingestion reports one unit per board.
result	object | null	Populated on state: "done" — e.g. the landed rule version and board count.
error	string | null	Populated on state: "failed".

The document carries a TTL. A status for a long-finished run eventually expires and starts returning 404; that is expiry, not failure.

Authentication

Authentication is performed using JSON Web Tokens (JWT) issued by Amazon Cognito. The caller must additionally hold access to the project.

Error Handling

Description	Status Code	Status Name
Missing authentication credentials	401	Unauthorized
Insufficient permissions	403	Forbidden
Event status not found — unknown event_run_id, or TTL-expired	404	Not Found
Upstream read failure (wf2des-api unreachable or erroring)	500	Internal Server Error

A 404 immediately after triggering is normal and transient: the status document is written by the worker when it picks the message up, so a poll that races the SQS delivery finds nothing yet. Clients should treat an early 404 as "not started" and keep polling.

Processing Flow

1. Extract organization ID, project ID and event_run_id from path parameters.
2. Verify the user has access to the project.
3. Proxy the read to the internal wf2des-api data plane (X-AI-Service-Token), scoped to the organization and project.
4. Return the status document verbatim, or 404 when absent.

The backend does not interpret or reshape the document — it is worker-owned, and new stages can appear without a backend change.