API Reference

View as Markdown

View as Markdown

Copy Markdown

---

Open in Claude

Open in ChatGPT

Runs

List Runs

client.runs.list(RunListParams { active, after, agent_id, 9 more } query?, RequestOptionsoptions?): ArrayPage<Run { id, agent_id, background, 13 more } >

get/v1/runs/

Retrieve Run

client.runs.retrieve(stringrunID, RequestOptionsoptions?): Run { id, agent_id, background, 13 more }

get/v1/runs/{run_id}

ModelsExpand Collapse

Job { id, agent_id, background, 15 more }

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

id?: string

The human-friendly ID of the Job

agent_id?: string | null

The agent associated with this job/run.

background?: boolean | null

Whether the job was created in background mode.

callback_error?: string | null

Optional error message from attempting to POST the callback endpoint.

callback_sent_at?: string | null

Timestamp when the callback was last attempted.

formatdate-time

callback_status_code?: number | null

HTTP status code returned by the callback endpoint.

callback_url?: string | null

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

completed_at?: string | null

The unix timestamp of when the job was completed.

formatdate-time

created_at?: string

The unix timestamp of when the job was created.

formatdate-time

created_by_id?: string | null

The id of the user that made this object.

job_type?: JobType

The type of the job.

Accepts one of the following:

"job"

"run"

"batch"

last_updated_by_id?: string | null

The id of the user that made this object.

metadata?: Record<string, unknown> | null

The metadata of the job.

status?: JobStatus

The status of the job.

Accepts one of the following:

"created"

"running"

"completed"

"failed"

"pending"

"cancelled"

"expired"

stop_reason?: StopReasonType | null

The reason why the job was stopped.

Accepts one of the following:

"end_turn"

"error"

"llm_api_error"

"invalid_llm_response"

"invalid_tool_call"

"max_steps"

"no_tool_call"

"tool_rule"

"cancelled"

"requires_approval"

total_duration_ns?: number | null

Total run duration in nanoseconds

ttft_ns?: number | null

Time to first token for a run in nanoseconds

updated_at?: string | null

The timestamp when the object was last updated.

formatdate-time

StopReasonType = "end_turn" | "error" | "llm_api_error" | 7 more

Accepts one of the following:

"end_turn"

"error"

"llm_api_error"

"invalid_llm_response"

"invalid_tool_call"

"max_steps"

"no_tool_call"

"tool_rule"

"cancelled"

"requires_approval"

RunsMessages

List Run Messages

client.runs.messages.list(stringrunID, MessageListParams { after, before, limit, 2 more } query?, RequestOptionsoptions?): ArrayPage<LettaMessageUnion>

get/v1/runs/{run_id}/messages

Retrieve Stream

client.runs.messages.stream(stringrunID, MessageStreamParams { batch_size, include_pings, poll_interval, starting_after } body?, RequestOptionsoptions?): MessageStreamResponse | Stream<LettaStreamingResponse>

post/v1/runs/{run_id}/stream

RunsUsage

Retrieve Run Usage

client.runs.usage.retrieve(stringrunID, RequestOptionsoptions?): UsageRetrieveResponse { completion_tokens, completion_tokens_details, prompt_tokens, 2 more }

get/v1/runs/{run_id}/usage

RunsSteps

List Run Steps

client.runs.steps.list(stringrunID, StepListParams { after, before, limit, 2 more } query?, RequestOptionsoptions?): ArrayPage<Step { id, agent_id, completion_tokens, 21 more } >

get/v1/runs/{run_id}/steps