Skip to main content
Runs require capabilities.deliverables.enabled: true in the agent’s config. Autonomous mode only — for turn-based chat, use Messaging instead.

​
List Runs

GET /api/v1/managed-agents/agents/{agentId}/runs
​
limit
number
default:"25"
Number of runs to return (1–100).
​
runs
Run[]

​
Create Run

POST /api/v1/managed-agents/agents/{agentId}/runs
​
task
string
required
The task you want the agent to complete, in natural language.
​
sessionId
string
Run inside an existing session. If omitted, a new session is created.
​
metadata
object
curl -X POST https://suite.sundaypyjamas.com/api/v1/managed-agents/agents/3fae1c2e-.../runs \
  -H "Authorization: Bearer spj_ai_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "task": "Summarize the attached Q2 sales report and list top 3 risks." }'

{
  "runId": "run_8a21...",
  "sessionId": "sess_44bc...",
  "created_at": "2026-07-08T10:05:00Z"
}
Returns 400 with "Deliverables are disabled for this agent" if the agent’s config doesn’t enable deliverables. Returns 400 with "Integration mentions must use the platform webhook" if metadata.source is a recognized integration.

​
Get Run

GET /api/v1/managed-agents/agents/{agentId}/runs/{runId}
​
run
object
Run object — see List Runs
​
events
object[]
​
artifacts
object[]
curl https://suite.sundaypyjamas.com/api/v1/managed-agents/agents/3fae1c2e-.../runs/run_8a21... \
  -H "Authorization: Bearer spj_ai_your_api_key_here"

​
Polling vs. Streaming

For long-running tasks, poll GET .../runs/{runId} every few seconds until status is completed or failed, then read artifacts. To cancel a run in progress, see Cancel Run.