Skip to content

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.

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"
}
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

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.