Get an agent run
Returns the run's status plus the append-only event log rows after the `since` sequence number. Poll this to stream a run's progress.
GET
/v1/agent-runs/{id}
Returns the run's status plus the append-only event log rows after
the `since` sequence number. Poll this to stream a run's progress.
Authentication
API Key (header: Authorization)
Path Parameters
id
string
required
path
Run ID
Query Parameters
since
integer
optional
query
Return events with seq greater than this (default 0)
Responses
200
OK
application/jsoncode
integer
data
object
events
object[]
Array of:
createdAt
string
level
string
message
string
metadata
object
seq
integer
type
string
state
object
assistantText
string
detail
string
finishedAt
string
phase
string
runId
string
savedWorkflowIds
string[]
SavedWorkflowIDs are the workflow ids the run ACTUALLY saved/edited
(workflow-builder's wf-save ledger, reported on agent_done; success only).
Mirrored verbatim from the worker so Caddie can refresh the canvas.
Array of:
servedPath
string
ServedPath is the worker-relative path a serve-capable agent's output is
served at (e.g. "/artifacts/<runId>/"); ServedURL is the absolute,
browser-openable URL the API composes from it (worker base + path) so a
client can surface the built app's link. Both empty for non-serving runs.
servedUrl
string
startedAt
string
turns
integer
usage
object
callCount
integer
completionTokens
integer
costUsd
number
model
string
promptTokens
integer
message
string
requestId
string
curl -X GET 'https://api.example.com/v1/agent-runs/string' \ -H 'Authorization: Bearer YOUR_API_TOKEN'const response = await fetch('https://api.example.com/v1/agent-runs/string', { method: 'GET', headers: { "Authorization": "Bearer YOUR_API_TOKEN" }});const data = await response.json();console.log(data);import requestsheaders = { 'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.get('https://api.example.com/v1/agent-runs/string', headers=headers)print(response.json())package mainimport ( "fmt" "io" "net/http")func main() { req, _ := http.NewRequest("GET", "https://api.example.com/v1/agent-runs/string", nil) req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() result, _ := io.ReadAll(resp.Body) fmt.Println(string(result))}
200
Response
{ "code": 200, "data": { "events": [ { "createdAt": "<string>", "level": "<string>", "message": "<string>", "metadata": "<object>", "seq": 123, "type": "<string>" } ], "state": { "assistantText": "<string>", "detail": "<string>", "finishedAt": "<string>", "phase": "<string>", "runId": "<string>", "savedWorkflowIds": [ "<string>" ], "servedPath": "<string>", "servedUrl": "<string>", "startedAt": "<string>", "turns": 123, "usage": { "callCount": 123, "completionTokens": 123, "costUsd": 123, "model": "<string>", "promptTokens": 123 } } }, "message": "success", "requestId": "abc-123"}API Playground
Try this endpoint
GET
/v1/agent-runs/{id}