Runs
Runs
Runs are the public execution unit. Internally the MVP maps them onto the existing turn executor, but the external contract is run.
Create a run
curl https://api.agentplatform.cloud/v1/sessions/sess_123/runs \
-H "Authorization: Bearer $AP_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"input": [
{
"role": "user",
"content": [{ "type": "input_text", "text": "Summarize open Linear issues." }]
}
]
}'By default, AP queues the run and returns 202 Accepted with the current run state.
Use a run every time your app wants new model output inside an existing session.
Wait for the final result
Set wait: true when your backend wants a single response payload.
{
"input": [
{
"role": "user",
"content": [{ "type": "input_text", "text": "Summarize open Linear issues." }]
}
],
"wait": true
}Stream immediately from run creation
Set stream: true to receive SSE directly from POST /v1/sessions/{id}/runs.
{
"input": [
{
"role": "user",
"content": [{ "type": "input_text", "text": "Summarize open Linear issues." }]
}
],
"stream": true
}Poll a run
GET /v1/runs/{id} returns terminal output, tool call summaries, and failure state.
Example terminal response:
{
"id": "run_123",
"object": "run",
"session_id": "sess_123",
"status": "completed",
"source": "api",
"created_at": "2026-03-14T20:01:00Z",
"updated_at": "2026-03-14T20:01:04Z",
"output": [
{
"type": "message",
"role": "assistant",
"content": [{ "type": "output_text", "text": "There are 4 open Linear issues." }]
}
]
}Cancel a run
POST /v1/runs/{id}/cancel marks queued or running work as cancelled and appends a run.cancelled event.
Use cancellation when the user has clearly abandoned the request or your backend no longer needs the answer. The durable event log still preserves what happened up to that point.