ReferenceHTTP API
Runs
Query Parameters
agent_id?string
Filter by agent id
status?string
Filter by run status
Value in
- "warming"
- "running"
- "completed"
- "failed"
- "canceled"
kind?string
Filter by run kind
Value in
- "chat_session"
- "live_call"
- "workflow"
- "job"
- "other"
external_id?string
Filter by customer correlation id
limit?integer
Maximum runs to return, capped at 100
Range
0 <= valueResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/runs"{ "runs": [ { "agent_id": "string", "blocked_count": 0, "created_at": "string", "ended_at": "string", "environment": "string", "environment_id": "string", "escalated_count": 0, "external_id": "string", "id": "string", "kind": "chat_session", "metadata": null, "p95_latency_ms": 0, "rewritten_count": 0, "started_at": "string", "status": "warming", "trace_count": 0, "updated_at": "string", "workspace_id": "string" } ]}Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/v1/runs" \ -H "Content-Type: application/json" \ -d '{ "agent_id": "string", "kind": "chat_session" }'{ "agent_id": "string", "blocked_count": 0, "created_at": "string", "ended_at": "string", "environment": "string", "environment_id": "string", "escalated_count": 0, "external_id": "string", "id": "string", "kind": "chat_session", "metadata": null, "p95_latency_ms": 0, "rewritten_count": 0, "started_at": "string", "status": "warming", "trace_count": 0, "updated_at": "string", "workspace_id": "string"}curl -X GET "https://example.com/v1/runs/string"{ "budget_decision": null, "events": [ { "created_at": "string", "id": "string", "input_summary": "string", "kind": "user_turn", "label": "string", "metadata": null, "occurred_at": "string", "output_summary": "string", "run_id": "string", "sequence": 0, "workspace_id": "string" } ], "guardrail_usage": [ { "completion_tokens": 0, "error_code": "string", "estimated_cost_usd_nanos": "string", "fallback_used": true, "judge": "string", "latency_ms": 0, "model": "string", "phase": "string", "prompt_tokens": 0, "provider": "string", "status": "string" } ], "provider_usage": null, "run": { "agent_id": "string", "blocked_count": 0, "created_at": "string", "ended_at": "string", "environment": "string", "environment_id": "string", "escalated_count": 0, "external_id": "string", "id": "string", "kind": "chat_session", "metadata": null, "p95_latency_ms": 0, "rewritten_count": 0, "started_at": "string", "status": "warming", "trace_count": 0, "updated_at": "string", "workspace_id": "string" }, "traces": [ { "created_at": "string", "decision": "string", "domain": "string", "elapsed_ms": 0, "environment": "string", "environment_id": "string", "latest_review_outcome": null, "latest_reviewed_at": "string", "payload": null, "run_event_id": "string", "run_id": "string", "session_id": "string", "trace_id": "string" } ]}Path Parameters
id*string
Run id
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/v1/runs/string" \ -H "Content-Type: application/json" \ -d '{}'{ "agent_id": "string", "blocked_count": 0, "created_at": "string", "ended_at": "string", "environment": "string", "environment_id": "string", "escalated_count": 0, "external_id": "string", "id": "string", "kind": "chat_session", "metadata": null, "p95_latency_ms": 0, "rewritten_count": 0, "started_at": "string", "status": "warming", "trace_count": 0, "updated_at": "string", "workspace_id": "string"}Path Parameters
id*string
Run id
Query Parameters
limit?integer
Maximum events to return, capped at 200
Range
0 <= valueResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/runs/string/events"{ "events": [ { "created_at": "string", "id": "string", "input_summary": "string", "kind": "user_turn", "label": "string", "metadata": null, "occurred_at": "string", "output_summary": "string", "run_id": "string", "sequence": 0, "workspace_id": "string" } ]}Path Parameters
id*string
Run id
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/runs/string/events" \ -H "Content-Type: application/json" \ -d '{ "kind": "user_turn" }'{ "created_at": "string", "id": "string", "input_summary": "string", "kind": "user_turn", "label": "string", "metadata": null, "occurred_at": "string", "output_summary": "string", "run_id": "string", "sequence": 0, "workspace_id": "string"}Path Parameters
id*string
Run id
Query Parameters
limit?integer
Maximum traces to return, capped at 100
Range
0 <= valueResponse Body
application/json
application/json
application/json
curl -X GET "https://example.com/v1/runs/string/traces"{ "traces": [ { "created_at": "string", "decision": "string", "domain": "string", "elapsed_ms": 0, "environment": "string", "environment_id": "string", "latest_review_outcome": null, "latest_reviewed_at": "string", "payload": null, "run_event_id": "string", "run_id": "string", "session_id": "string", "trace_id": "string" } ]}