Runs

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/&#123;agentId&#125;/runs

number

default:"25"

Number of runs to return (1–100).

Run[]

Show Run object

string

pending · running · completed · failed

string

The task description submitted for this run

string

string | null

Create Run

POST /api/v1/managed-agents/agents/&#123;agentId&#125;/runs

string

required

The task you want the agent to complete, in natural language.

string

Run inside an existing session. If omitted, a new session is created.

object

Show metadata

string

Originating integration platform. Do not set this for known integrations (e.g. slack, pumble) — those must trigger runs via their platform webhook, not this endpoint directly.

string

Thread/channel container ID

string

Idempotency/dedup key

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/&#123;agentId&#125;/runs/&#123;runId&#125;

object

Run object — see List Runs

object[]

Show event

string

object

string

object[]

Show artifact

string

number

string

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.

Chat

Agents

RAG

Artifacts

Image

Vector Store

Apps

Storage

Integrations

Insights

Platform Tools

List Runs

Create Run

Get Run

Polling vs. Streaming

​List Runs

​Create Run

​Get Run

​Polling vs. Streaming

List Runs

Create Run

Get Run

Polling vs. Streaming