Runs
A run is a concrete attempt to carry out work. It belongs to a workspace and captures the inputs, selected definitions and their revisions, and limits for that attempt. A team goal can delegate to several playbook runs.
Start an attempt
Section titled “Start an attempt”Request and revision
Section titled “Request and revision”Studio starts a team execution at POST /api/persona-playground/pages/:pageId/spaces/:spaceId/executions. This request starts an existing goal after checking the selected team and its revision. Use the same idempotency key for the same start request. Allocate a new key when intentionally starting a new attempt.
{ "goalId": "goal-meetings", "expectedTeamRevision": 7, "reviewPlan": true, "inputs": { "from": "2026-11-16T09:00:00Z", "until": "2026-11-16T17:00:00Z" }, "idempotencyKey": "meeting-review-2026-11-16"}Execution states
Section titled “Execution states”| State or group | What the client can show |
|---|---|
pending, planning, running, finalizing |
Progress for the current attempt |
waiting_input, waiting_approval, waiting_external |
The specific decision, data, or provider result the run needs |
cancelling, cancelled |
Stop requested or confirmed |
completed, failed, uncertain |
Confirmed result, failure, or an outcome requiring reconciliation |
Inspect or recover an attempt
Section titled “Inspect or recover an attempt”Use GET …/executions/:executionId for current state and GET …/executions/:executionId/events for its activity. Track the attempt ID across reconnection and re-read after a replay gap. Use POST …/executions/:executionId/cancel when a person requests cancellation. If the provider may already have acted, keep the attempt and reconcile it against evidence. Retry only when the runtime can establish that the effect is safe to retry.
See goals, live sync, and execution receipts.