Skip to content

Commit 7ae4ce0

Browse files
TheodoreSpeaksTheodoreSpeaks
committed
docs(api): document GET /workflows/[id]/executions/[executionId]
Adds the WorkflowExecutionStatus schema and the getWorkflowExecution operation to the OpenAPI spec, including completed/paused/failed response examples and the includeOutput + selectedOutputs query params. Registers the page in the Workflows section of the API reference.
1 parent c2d0eba commit 7ae4ce0

2 files changed

Lines changed: 295 additions & 1 deletion

File tree

‎apps/docs/content/docs/en/api-reference/(generated)/workflows/meta.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
11
{
2-
"pages": ["executeWorkflow", "cancelExecution", "listWorkflows", "getWorkflow", "getJobStatus"]
2+
"pages": [
3+
"executeWorkflow",
4+
"getWorkflowExecution",
5+
"cancelExecution",
6+
"listWorkflows",
7+
"getWorkflow",
8+
"getJobStatus"
9+
]
310
}

‎apps/docs/openapi.json‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,158 @@
169169
}
170170
}
171171
},
172+
"/api/workflows/{id}/executions/{executionId}": {
173+
"get": {
174+
"operationId": "getWorkflowExecution",
175+
"summary": "Get Execution Status",
176+
"description": "Get the normalized lifecycle status of a workflow execution. Unlike `/api/jobs/{jobId}` (which only tracks async-launched jobs and marks `completed` on the first suspend) or `/api/v1/logs/executions/{executionId}` (which dumps the full state snapshot), this endpoint returns a lightweight, fixed-shape status object that bridges `workflowExecutionLogs` and `pausedExecutions` \u2014 intended for polling clients that want to track a run through suspend/resume cycles.",
177+
"tags": ["Workflows"],
178+
"x-codeSamples": [
179+
{
180+
"id": "curl",
181+
"label": "cURL",
182+
"lang": "bash",
183+
"source": "curl \\\n \"https://www.sim.ai/api/workflows/{id}/executions/{executionId}\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
184+
},
185+
{
186+
"id": "curl-with-outputs",
187+
"label": "cURL (with block outputs)",
188+
"lang": "bash",
189+
"source": "curl \\\n \"https://www.sim.ai/api/workflows/{id}/executions/{executionId}?selectedOutputs=blockId,blockId.field&includeOutput=true\" \\\n -H \"X-API-Key: YOUR_API_KEY\""
190+
}
191+
],
192+
"parameters": [
193+
{
194+
"name": "id",
195+
"in": "path",
196+
"required": true,
197+
"description": "The unique identifier of the workflow.",
198+
"schema": {
199+
"type": "string",
200+
"example": "wf_1a2b3c4d5e"
201+
}
202+
},
203+
{
204+
"name": "executionId",
205+
"in": "path",
206+
"required": true,
207+
"description": "The unique identifier of the execution.",
208+
"schema": {
209+
"type": "string",
210+
"example": "exec_9f8e7d6c5b"
211+
}
212+
},
213+
{
214+
"name": "includeOutput",
215+
"in": "query",
216+
"required": false,
217+
"description": "When `true` and the execution has `status: completed`, include the workflow's final output in the response.",
218+
"schema": {
219+
"type": "string",
220+
"enum": ["true", "false"]
221+
}
222+
},
223+
{
224+
"name": "selectedOutputs",
225+
"in": "query",
226+
"required": false,
227+
"description": "Comma-separated list of block-output selectors. Each selector is either a bare `blockId` (returns the full output) or a dot-path like `blockId.field` / `blockId.nested.path` (returns just that value). Selectors are returned in the `blockOutputs` map keyed by the selector string. Pulls from `executionData.traceSpans`; walks `children` recursively.",
228+
"schema": {
229+
"type": "string",
230+
"example": "c1b90bce-8a82-42a5-b6a5-5762846c2eaf,c1b90bce-8a82-42a5-b6a5-5762846c2eaf.waitDuration"
231+
}
232+
}
233+
],
234+
"responses": {
235+
"200": {
236+
"description": "Execution status returned.",
237+
"content": {
238+
"application/json": {
239+
"schema": {
240+
"$ref": "#/components/schemas/WorkflowExecutionStatus"
241+
},
242+
"examples": {
243+
"completed": {
244+
"summary": "Completed run",
245+
"value": {
246+
"executionId": "9254f1c9-5a11-4a12-91e3-8065293f3609",
247+
"workflowId": "81f661e1-d704-4861-b5c1-5bb3cf57e6a7",
248+
"status": "completed",
249+
"trigger": "api",
250+
"level": "info",
251+
"startedAt": "2026-05-15T19:43:12.189Z",
252+
"endedAt": "2026-05-15T19:45:45.224Z",
253+
"totalDurationMs": 153035,
254+
"paused": null,
255+
"cost": {
256+
"total": 0.005
257+
},
258+
"error": null,
259+
"finalOutput": null,
260+
"blockOutputs": null
261+
}
262+
},
263+
"paused": {
264+
"summary": "Currently paused run",
265+
"value": {
266+
"executionId": "772749f6-ee81-414c-a2c3-671549dd62b8",
267+
"workflowId": "81f661e1-d704-4861-b5c1-5bb3cf57e6a7",
268+
"status": "paused",
269+
"trigger": "manual",
270+
"level": "info",
271+
"startedAt": "2026-05-15T22:25:57.178Z",
272+
"endedAt": "2026-05-15T22:25:57.215Z",
273+
"totalDurationMs": 1,
274+
"paused": {
275+
"pausedAt": "2026-05-15T22:25:57.216Z",
276+
"resumeAt": "2026-05-16T18:25:57.200Z",
277+
"pauseKind": "time",
278+
"blockedOnBlockId": "c1b90bce-8a82-42a5-b6a5-5762846c2eaf",
279+
"pausedExecutionId": "438bf05b-bd3c-4011-b78e-b19c112eeb66",
280+
"pausePointCount": 1,
281+
"resumedCount": 0
282+
},
283+
"cost": {
284+
"total": 0.005
285+
},
286+
"error": null,
287+
"finalOutput": null,
288+
"blockOutputs": null
289+
}
290+
},
291+
"failed": {
292+
"summary": "Failed run",
293+
"value": {
294+
"executionId": "3ccfdeed-a63c-4e86-98e2-8bec723bca52",
295+
"workflowId": "81f661e1-d704-4861-b5c1-5bb3cf57e6a7",
296+
"status": "failed",
297+
"trigger": "api",
298+
"level": "error",
299+
"startedAt": "2026-05-15T22:24:50.991Z",
300+
"endedAt": "2026-05-15T22:24:50.999Z",
301+
"totalDurationMs": 2,
302+
"paused": null,
303+
"cost": {
304+
"total": 0.005
305+
},
306+
"error": "Wait 1: Wait time exceeds maximum of 5 minutes; enable async mode to wait up to 30 days",
307+
"finalOutput": null,
308+
"blockOutputs": null
309+
}
310+
}
311+
}
312+
}
313+
}
314+
},
315+
"401": {
316+
"$ref": "#/components/responses/Unauthorized"
317+
},
318+
"404": {
319+
"$ref": "#/components/responses/NotFound"
320+
}
321+
}
322+
}
323+
},
172324
"/api/workflows/{id}/executions/{executionId}/cancel": {
173325
"post": {
174326
"operationId": "cancelExecution",
@@ -5831,6 +5983,141 @@
58315983
}
58325984
}
58335985
},
5986+
"WorkflowExecutionStatus": {
5987+
"type": "object",
5988+
"description": "Normalized status of a workflow execution. Bridges workflowExecutionLogs and pausedExecutions so a single response covers the full lifecycle, including post-suspend resumes.",
5989+
"properties": {
5990+
"executionId": {
5991+
"type": "string",
5992+
"description": "The unique identifier of the execution.",
5993+
"example": "9254f1c9-5a11-4a12-91e3-8065293f3609"
5994+
},
5995+
"workflowId": {
5996+
"type": "string",
5997+
"description": "The unique identifier of the workflow.",
5998+
"example": "81f661e1-d704-4861-b5c1-5bb3cf57e6a7"
5999+
},
6000+
"status": {
6001+
"type": "string",
6002+
"enum": ["pending", "running", "paused", "completed", "failed", "cancelled"],
6003+
"description": "Current normalized lifecycle status. `paused` is set when a row exists in pausedExecutions with status `paused` or `partially_resumed`; otherwise the workflowExecutionLogs row's status field is used.",
6004+
"example": "completed"
6005+
},
6006+
"trigger": {
6007+
"type": "string",
6008+
"enum": ["api", "manual", "schedule", "webhook", "chat"],
6009+
"description": "What triggered the execution.",
6010+
"example": "api"
6011+
},
6012+
"level": {
6013+
"type": "string",
6014+
"enum": ["info", "warning", "error"],
6015+
"description": "Log level of the execution.",
6016+
"example": "info"
6017+
},
6018+
"startedAt": {
6019+
"type": "string",
6020+
"format": "date-time",
6021+
"description": "ISO 8601 timestamp when execution started.",
6022+
"example": "2026-05-15T19:43:12.189Z"
6023+
},
6024+
"endedAt": {
6025+
"type": "string",
6026+
"format": "date-time",
6027+
"nullable": true,
6028+
"description": "ISO 8601 timestamp when execution ended. Null while the run is in flight.",
6029+
"example": "2026-05-15T19:45:45.224Z"
6030+
},
6031+
"totalDurationMs": {
6032+
"type": "integer",
6033+
"nullable": true,
6034+
"description": "Total duration of the execution in milliseconds. Null while the run is in flight.",
6035+
"example": 153035
6036+
},
6037+
"paused": {
6038+
"type": "object",
6039+
"nullable": true,
6040+
"description": "Pause-state details. Present only when status is `paused`.",
6041+
"properties": {
6042+
"pausedAt": {
6043+
"type": "string",
6044+
"format": "date-time",
6045+
"description": "ISO 8601 timestamp when the workflow was paused.",
6046+
"example": "2026-05-15T22:25:57.216Z"
6047+
},
6048+
"resumeAt": {
6049+
"type": "string",
6050+
"format": "date-time",
6051+
"nullable": true,
6052+
"description": "Earliest scheduled resume time across active pause points. Null for human-only pauses.",
6053+
"example": "2026-05-16T18:25:57.200Z"
6054+
},
6055+
"pauseKind": {
6056+
"type": "string",
6057+
"enum": ["time", "human"],
6058+
"nullable": true,
6059+
"description": "What kind of pause the workflow is waiting on.",
6060+
"example": "time"
6061+
},
6062+
"blockedOnBlockId": {
6063+
"type": "string",
6064+
"nullable": true,
6065+
"description": "The block currently blocking resume.",
6066+
"example": "c1b90bce-8a82-42a5-b6a5-5762846c2eaf"
6067+
},
6068+
"pausedExecutionId": {
6069+
"type": "string",
6070+
"description": "ID of the paused-execution row, useful for cross-referencing with the human-in-the-loop endpoints.",
6071+
"example": "438bf05b-bd3c-4011-b78e-b19c112eeb66"
6072+
},
6073+
"pausePointCount": {
6074+
"type": "integer",
6075+
"description": "Total number of pause points recorded for this execution.",
6076+
"example": 1
6077+
},
6078+
"resumedCount": {
6079+
"type": "integer",
6080+
"description": "Number of pause points already resumed.",
6081+
"example": 0
6082+
}
6083+
}
6084+
},
6085+
"cost": {
6086+
"type": "object",
6087+
"nullable": true,
6088+
"description": "Cost summary. Detailed token / model breakdown lives on the /v1/logs detail endpoint.",
6089+
"properties": {
6090+
"total": {
6091+
"type": "number",
6092+
"description": "Total cost in USD.",
6093+
"example": 0.005
6094+
}
6095+
}
6096+
},
6097+
"error": {
6098+
"type": "string",
6099+
"nullable": true,
6100+
"description": "Error message. Present only when status is `failed`.",
6101+
"example": null
6102+
},
6103+
"finalOutput": {
6104+
"type": "object",
6105+
"nullable": true,
6106+
"description": "The workflow's final output. Returned only when ?includeOutput=true AND status is `completed`.",
6107+
"example": null
6108+
},
6109+
"blockOutputs": {
6110+
"type": "object",
6111+
"nullable": true,
6112+
"description": "Filtered per-block outputs keyed by the selector string. Returned only when ?selectedOutputs is set. A bare blockId returns the full block output; `blockId.field` or `blockId.nested.path` returns just that value.",
6113+
"additionalProperties": true,
6114+
"example": {
6115+
"c1b90bce-8a82-42a5-b6a5-5762846c2eaf.waitDuration": 60000,
6116+
"c1b90bce-8a82-42a5-b6a5-5762846c2eaf.status": "completed"
6117+
}
6118+
}
6119+
}
6120+
},
58346121
"AuditLogEntry": {
58356122
"type": "object",
58366123
"description": "An enterprise audit log entry recording an action taken in the workspace.",

0 commit comments

Comments
 (0)