Status & Streaming
Poll execution status or subscribe to real-time SSE events for component executions.
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.zafeguard.com/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.zafeguard.com/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;
}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 |