API Reference
Runs API
API endpoints for managing agent runs and traces.
List Runs
GET /agents/{agent_id}/runsResponse: 200
{
"runs": [
{
"id": "run-1",
"agent_id": "agent-id",
"status": "completed",
"trigger": "manual",
"overall_score": 0.78,
"created_at": "2026-03-30T10:00:00Z",
"completed_at": "2026-03-30T10:01:30Z"
}
]
}Create Run
POST /agents/{agent_id}/runsRequest Body:
{
"trigger": "manual"
}| Field | Type | Required | Description |
|---|---|---|---|
trigger | string | Yes | "manual", "automatic", or "test" |
run_id | string | No | Custom UUID (auto-generated if omitted) |
Response: 201 - AgentRunResponse
Get Run
GET /agents/{agent_id}/runs/{run_id}Response: 200 - AgentRunResponse
Complete Run
POST /agents/{agent_id}/runs/{run_id}/completeMark a run as completed. Triggers automatic evaluation if cooldown allows.
Response: 200 - AgentRunResponse (status → completed)
Get Run Spans
GET /agents/{agent_id}/runs/{run_id}/spansGet trace spans for a run.
Response: 200
{
"spans": [
{
"node_name": "generate_strategy",
"span_kind": "LLM",
"input_text": "Create a content strategy for...",
"output_text": "Here's a comprehensive strategy...",
"model": "claude-sonnet-4-5-20250514",
"latency_ms": 2340,
"token_count": 1250
}
],
"total": 3
}Upload Spans
POST /agents/{agent_id}/runs/{run_id}/spansUpload trace spans directly (for external agents not using the trace decorator).
Request Body:
{
"spans": [
{
"node_name": "process_request",
"span_kind": "LLM",
"input_text": "...",
"output_text": "...",
"latency_ms": 1500
}
]
}Response: 201 - {"uploaded": 1, "span_ids": [...]}
Rate limit: 60 requests/minute. Run must be in running status.
Enqueue Run (Kate-Hosted)
POST /agents/{agent_id}/runs/enqueueFor Kate-hosted agents. Enqueues a run for execution.
Request Body:
{
"trigger": "manual",
"user_input": "Generate a content strategy for AI in healthcare"
}Response: 202
{
"run_id": "run-id",
"job_id": "job-id",
"status": "queued"
}SDK Equivalent
runs = await client.runs.list(agent_id="...")
run = await client.runs.create(agent_id="...", trigger="manual")
run = await client.runs.get(agent_id="...", run_id="...")
run = await client.runs.complete(agent_id="...", run_id="...")
spans = await client.runs.spans(agent_id="...", run_id="...")