Run an agent
Starts new work or continues prior work.
Send session_id to continue prior work. Omit it to create a session.
Each request creates a new run inside that session.
The default request waits for a terminal result. Set background: true
to return an accepted run immediately. Set stream: true to receive
Server-Sent Events. background and stream cannot both be true.
SimpleServe can return 202 when work continues after the request wait
ends. Retrieve the Run from the location response header.
SimpleServe authorizes max_cost_usd when present. When it is absent, SimpleServe
authorizes the agent's published maximum. A smaller limit is accepted
when it covers the agent's published minimum.
Authorization
bearerAuth Send a SimpleServe API key as Authorization: Bearer <key>.
In: header
Header Parameters
Prevents duplicate work and charges when a request is retried. Reusing
a key with a different request returns 409 idempotency_conflict.
8 <= length <= 255Resume a Run event stream after this durable event number.
0 <= valueRequest Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/runs" \ -H "Idempotency-Key: 01JXYZ1234567890ABCDEF" \ -H "Content-Type: application/json" \ -d '{ "agent": "acme/construction-researcher", "input": "Find hotel projects over $25M breaking ground in Miami.", "max_cost_usd": 3 }'{ "id": "run_01JXYZ1234567890", "object": "run", "agent": "acme/construction-researcher", "status": "completed", "output_text": "I found 14 matching projects. The CSV contains the complete result.", "output": [ { "type": "text", "text": "I found 14 matching projects. The CSV contains the complete result.", "annotations": [] }, { "type": "file", "file_id": "file_01JXYZ1234567890", "filename": "projects.csv", "media_type": "text/csv", "size_bytes": 18422 }, { "type": "data", "data": { "matches": 14, "market": "Miami" } }, { "type": "tool_use", "id": "tool_01JXYZ1234567890", "name": "search_projects", "input": { "market": "Miami" } }, { "type": "tool_result", "tool_use_id": "tool_01JXYZ1234567890", "output": { "matches": 14 }, "is_error": false } ], "usage": { "rate_card_id": "rc_2026_08", "meters": [ { "id": "invocations", "quantity": 1, "cost_usd": 1 }, { "id": "returned_records", "quantity": 14, "cost_usd": 0.14 } ] }, "cost_usd": 1.2255, "max_cost_usd": 3, "session_id": "ses_01JXYZ1234567890", "stop_reason": null, "error": null, "created_at": "2026-08-29T18:30:00Z", "started_at": "2026-08-29T18:30:00Z", "completed_at": "2026-08-29T18:30:08Z", "metadata": {}}