Status & Streaming

Two ways to track a running execution: poll for the current state on demand, or stream live events until the execution reaches a terminal status.

---

Get execution status

GET /v1/sdk/components/executions/:executionId

Poll for the current status of an execution at any time.

curl https://api.whiterabbit.app/v1/sdk/components/executions/3f7a1b2c-... \
  -H "X-Api-Key: ws_..." \
  -H "X-Sdk-Timestamp: <timestamp>" \
  -H "X-Sdk-Signature: <signature>"

Response — same execution record shape as Execute Component.

Status	Meaning
CREATED	Queued, not yet started
EXECUTING	Currently running
COMPLETED	Finished — output is populated
FAILED	Errored — error is populated

---

Stream execution status

SSE /v1/sdk/components/executions/:executionId/stream

Subscribe to a real-time Server-Sent Events stream. The connection emits status update events as the execution progresses and closes automatically once a terminal status (COMPLETED or FAILED) is reached.

Node.js example

const response = await fetch(
  `https://api.whiterabbit.app/v1/sdk/components/executions/${id}/stream`,
  { headers: { 'X-Api-Key': 'ws_...' } },
);

const reader = response.body!.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  for (const line of decoder.decode(value).split('\n')) {
    if (!line.startsWith('data: ')) continue;
    const data = line.slice(6).trim();
    if (!data || data === ':ping') continue;
    const event = JSON.parse(data);
    console.log(event.status, event.output);
  }
}

Event shape

interface ExecutionStreamEvent {
  id: string;
  status: 'CREATED' | 'EXECUTING' | 'COMPLETED' | 'FAILED';
  output: unknown | null;  // populated on COMPLETED
  error: unknown | null;   // populated on FAILED
  timestamp: string;
}

tip

The stream sends :ping comments every 15 seconds to keep the connection alive through proxies and load balancers. Ignore lines that equal :ping.

---

Choosing the right approach

Approach	Best for
waitForMs on execute	Short operations (< 15s) — inline result in the same request
Poll GET	Simple integrations, serverless functions, or when you don't need real-time
SSE stream	UI dashboards, long-running operations, real-time progress feedback
Webhook callbackUrl	Server-to-server async delivery — your endpoint receives the result