Executions and approvals API
Start, inspect, stream, recover, export, and approve Agent Studio executions through the REST API.
Use these session-authenticated endpoints to run skill versions, inspect execution history and live events, recover failed or paused work, and resolve human approval requests. All JSON paths are relative to your Agent Studio origin.
X-Organization-Id. Starting an organization execution requires membership and execution permission. See API authentication, errors, and limits for shared errors and retry guidance.Execution statuses
Filters and results use PENDING, RUNNING, PAUSED_FOR_APPROVAL, COMPLETED, FAILED, CANCELLED, and STEP_LIMIT_EXCEEDED. Recovery operations have distinct semantics: retry continues from a failed step without repeating completed safe steps, while replay creates a new execution from the historical skill version and input.
List executions
/api/executionsOrganization context; takes precedence.
Free-text search.
One execution status.
Filter by skill name.
Filter by skill version.
Filter by model provider.
Inclusive ISO date lower bound.
Inclusive ISO date upper bound.
`startedAt`, `durationMs`, or `status`. Default: `startedAt`.
`asc` or `desc`. Default: `desc`.
Positive result limit. Organization queries default to 100.
Organization context when the header is absent.
curl --request GET \ --url https://studio.example.com/api/executions?search=Support%20triage&status=COMPLETED&skillName=Support%20triage&skillVersionId=version_example&provider=openai&from=2026-01-01T00%3A00%3A00.000Z&to=2026-01-31T23%3A59%3A59.999Z&sortBy=startedAt&sortOrder=desc&limit=25&organizationId=org_example \ --header 'X-Organization-Id: org_example'
{ "success": true, "data": [{ "id": "exec_example", "status": "COMPLETED" }] }Organization members with audit-log visibility can see all organization executions; other members see their own. The personal query applies all listed filters through execution history.
Start an execution
/api/executionsOptional organization context.
Skill version to run.
Input object validated by the skill version.
Organization context when the header is absent.
curl --request POST \
--url https://studio.example.com/api/executions \
--header 'Content-Type: application/json' \
--data '{
"skillVersionId": "<string>",
"inputData": {},
"organizationId": "<string>"
}'{ "success": true, "data": { "id": "exec_example", "status": "PENDING" } }curl -X POST 'https://studio.example.com/api/executions' \
-H 'Content-Type: application/json' \
--data '{
"skillVersionId": "version_example",
"inputData": {"ticketId": "TICKET-1042", "priority": "normal"}
}'Use the returned execution ID with the detail or stream operations instead of polling the list.
Read an execution
/api/executions/:idExecution ID.
curl --request GET \ --url https://studio.example.com/api/executions/:id
{ "success": true, "data": { "id": "exec_example", "status": "RUNNING" } }/api/executions/:id/detailExecution ID owned by the current user.
curl --request GET \ --url https://studio.example.com/api/executions/:id/detail
{ "success": true, "data": { "id": "exec_example", "steps": [], "timeline": [] } }The general resource route can authorize an organization reader. The detail route uses the history service for the signed-in user's execution history.
Stream execution events
/api/executions/:id/streamOwned execution ID. Preview IDs are rejected.
curl --request GET \ --url https://studio.example.com/api/executions/:id/stream
event: node:start
data: {"type":"node:start","executionId":"exec_example","nodeId":"classify"}The stream first converts persisted steps into node:start and node:end events. A terminal execution also receives a final execution:status event and then closes. Active executions continue from an in-process event bus and send a heartbeat comment every 15 seconds. In a multi-instance deployment, persisted replay fills prior history, but the live tail is best-effort on the serving instance.
Metrics and export
/api/executions/metricscurl --request GET \ --url https://studio.example.com/api/executions/metrics
{ "success": true, "data": { "totalExecutions": 42 } }/api/executions/:id/exportExecution ID.
curl --request GET \ --url https://studio.example.com/api/executions/:id/export
{ "success": true, "data": { "executionId": "exec_example" } }Cancel, retry, and replay
/api/executions/:id/cancelExecution ID.
curl --request POST \ --url https://studio.example.com/api/executions/:id/cancel
{ "success": true, "data": { "id": "exec_example", "status": "CANCELLED" } }/api/executions/:id/retryFailed or stopped execution ID.
curl --request POST \ --url https://studio.example.com/api/executions/:id/retry
{ "success": true, "data": { "id": "exec_example", "status": "RUNNING" } }/api/executions/:id/replayHistorical execution ID.
curl --request POST \ --url https://studio.example.com/api/executions/:id/replay
{ "success": true, "data": { "id": "exec_replay", "replayedFromExecutionId": "exec_example" } }Replay never modifies the historical execution. It reuses that run's skill version and input and links the new execution through replayedFromExecutionId.
List approvals
/api/approvalsOrganization context. Only owners and admins can list all organization approvals.
curl --request GET \ --url https://studio.example.com/api/approvals \ --header 'X-Organization-Id: org_example'
{ "success": true, "data": [{ "id": "approval_example", "executionId": "exec_example", "status": "PENDING", "history": [] }] }Personal listing expires stale requests before returning pending and historical approvals. The response includes each request's timeline; there is no separate pending-list endpoint.
Respond to an approval
/api/approvalsApproval request ID.
`true` to approve or `false` to reject.
Single-use key supplied by the approval request.
Reason for rejection.
Optional structured approval response.
curl --request POST \
--url https://studio.example.com/api/approvals \
--header 'Content-Type: application/json' \
--data '{
"approvalId": "approval_example",
"approved": true,
"idempotencyKey": "idempotency_example",
"rejectionReason": "The requested change needs revision.",
"formData": "\"comment\":\"Approved after review\""
}'{ "success": true, "data": { "id": "approval_example", "status": "APPROVED" } }Approving the request records the decision but does not by itself resume the execution. Call the resume operation with the same approval ID and idempotency key.
/api/executions/:id/resumePaused execution ID.
Approved request belonging to this execution and user.
Key that matches the approval request.
curl --request POST \
--url https://studio.example.com/api/executions/:id/resume \
--header 'Content-Type: application/json' \
--data '{
"approvalId": "approval_example",
"idempotencyKey": "idempotency_example"
}'{ "success": true, "data": { "id": "exec_example", "status": "RUNNING" } }Cancel a pending approval
/api/approvals/:id/cancelApproval request ID.
Key supplied by the approval request.
curl --request POST \
--url https://studio.example.com/api/approvals/:id/cancel \
--header 'Content-Type: application/json' \
--data '{
"idempotencyKey": "idempotency_example"
}'{ "success": true, "data": { "status": "CANCELLED" } }