Runs

List Runs

GET/v1/runs/

Retrieve Run

GET/v1/runs/{run_id}

ModelsExpand Collapse

Job object { id, agent_id, background, 15 more }

Representation of offline jobs, used for tracking status of data loading tasks (involving parsing and embedding files).

id: optional string

The human-friendly ID of the Job

agent_id: optional string

The agent associated with this job/run.

background: optional boolean

Whether the job was created in background mode.

callback_error: optional string

Optional error message from attempting to POST the callback endpoint.

callback_sent_at: optional string

Timestamp when the callback was last attempted.

formatdate-time

callback_status_code: optional number

HTTP status code returned by the callback endpoint.

callback_url: optional string

If set, POST to this URL when the job completes.

completed_at: optional string

The unix timestamp of when the job was completed.

formatdate-time

created_at: optional string

The unix timestamp of when the job was created.

formatdate-time

created_by_id: optional string

The id of the user that made this object.

job_type: optional JobType

The type of the job.

One of the following:

"job"

"run"

"batch"

last_updated_by_id: optional string

The id of the user that made this object.

metadata: optional map[unknown]

The metadata of the job.

status: optional JobStatus

The status of the job.

One of the following:

"created"

"running"

"completed"

"failed"

"pending"

"cancelled"

"expired"

stop_reason: optional StopReasonType

The reason why the job was stopped.

One of the following:

"end_turn"

"error"

"llm_api_error"

"invalid_llm_response"

"invalid_tool_call"

"max_steps"

"max_tokens_exceeded"

"no_tool_call"

"tool_rule"

"cancelled"

"insufficient_credits"

"requires_approval"

"context_window_overflow_in_system_prompt"

total_duration_ns: optional number

Total run duration in nanoseconds

ttft_ns: optional number

Time to first token for a run in nanoseconds

updated_at: optional string

The timestamp when the object was last updated.

formatdate-time

StopReasonType = "end_turn" or "error" or "llm_api_error" or 10 more

One of the following:

"end_turn"

"error"

"llm_api_error"

"invalid_llm_response"

"invalid_tool_call"

"max_steps"

"max_tokens_exceeded"

"no_tool_call"

"tool_rule"

"cancelled"

"insufficient_credits"

"requires_approval"

"context_window_overflow_in_system_prompt"

RunsMessages

List Messages For Run

GET/v1/runs/{run_id}/messages

Retrieve Stream For Run

POST/v1/runs/{run_id}/stream

ModelsExpand Collapse

MessageStreamResponse = unknown

RunsUsage

Retrieve Usage For Run

GET/v1/runs/{run_id}/usage

ModelsExpand Collapse

UsageRetrieveResponse object { completion_tokens, completion_tokens_details, prompt_tokens, 2 more }

completion_tokens: optional number

completion_tokens_details: optional object { reasoning_tokens }

reasoning_tokens: optional number

prompt_tokens: optional number

prompt_tokens_details: optional object { cache_creation_tokens, cache_read_tokens, cached_tokens }

cache_creation_tokens: optional number

cache_read_tokens: optional number

cached_tokens: optional number

total_tokens: optional number

RunsSteps

List Steps For Run

GET/v1/runs/{run_id}/steps

RunsTrace

Retrieve Trace For Run

GET/v1/runs/{run_id}/trace

ModelsExpand Collapse

TraceRetrieveResponse = array of map[unknown]