Reference

Overview

This topic provides detailed information about the Agent API and its access methods.

Endpoints

Method	Path	Endpoint
`POST`	`/v1/agent/runs`	Start a run
`GET`	`/v1/agent/runs`	List runs
`GET`	`/v1/agent/runs/{id}`	Retrieve a run
`POST`	`/v1/agent/runs/{id}/cancel`	Cancel a run

Over REST, authenticate with the x-api-key header against https://api.seltz.ai. The SDKs speak gRPC to grpc.seltz.ai; pass your API key to the client constructor, which sends it on every call. Each endpoint has an interactive request/response playground: Start a run, List runs, Retrieve a run, and Cancel a run.

SDK methods

create, get, cancel, and the waiters all return the bare AgentRun envelope: the per-RPC response messages carry nothing else. list returns the page (runs plus the next cursor).

Python	TypeScript	Returns
`create`	`create`	The new run, in `pending` state
`get`	`get`	The run
`list`	`list`	`runs`, `next`
`cancel`	`cancel`	The run’s current envelope
`wait`	`wait`	The run, once it reaches a terminal state
`create_and_wait`	`createAndWait`	`create` then `wait` in one call

wait / createAndWait and manual polling via get are the only ways to observe completion. There is no webhook or streaming option for Agent, unlike Monitor.

Request

Field	Type	Required	Description
`query`	string	Yes	The natural-language question. The model honors instructions inside it rather than tokenizing them.
`output_schema`	object	No	OpenAI-style `response_format` object (`{"type": "text" \| "json_object" \| "json_schema", ...}`). Adds `output.structured` and its `grounding`. Create validates only the wrapper shape.

REST rejects an unknown field in the body; the SDKs’ request types have no room for one to begin with.

Run envelope

create, get, cancel, and each entry list returns all share this one AgentRun shape, unchanged across REST, gRPC, and the SDKs:

Field	Set when
`id`	Always.
`object`	Always `"agent.run"`.
`status`	Always. `pending`, `running`, `completed`, `failed`, or `cancelled`.
`stop_reason`	Once the run reaches a terminal state. Never set before.
`created_at`	Always.
`started_at`	Once a worker picks the run up.
`completed_at`	Once the run reaches a terminal state.
`request`	Always. Echo of the accepted request (`query`, `output_schema`).
`output`	Always present as an object; its fields are unset until the run completes.

Output

Field	Set when
`text`	The run reached a terminal state with usable output. Cited Markdown; inline `[n]` markers index into `sources`.
`structured`	The request carried an `output_schema` of type `json_object` or `json_schema`, and the run produced usable output. JSON-encoded.
`sources`	The run consulted at least one page. Each entry has `id` (starting at 1) and `url`.
`grounding`	`structured` is set. One entry per groundable field, keyed by dot-notation `field` path, each with `citations` pointing into `sources` by `source_id`.

Run status and stop reason

status is the coarse outcome; stop_reason appears only once a run reaches a terminal state, and only these pairs are legal:

`status`	`stop_reason`	Meaning
`completed`	`finished`	The agent decided it was done.
`completed`	`budget_reached`	Budget ran out, but the output so far is usable.
`completed`	`timeout`	The wall-clock limit hit, but the output so far is usable.
`failed`	`budget_reached`	Budget ran out with nothing usable.
`failed`	`timeout`	The wall-clock limit hit with nothing usable.
`failed`	`invalid_output`	The request carried an `output_schema`, and the run could produce no JSON output at all. A missing `additionalProperties: false` on a `strict: true` schema is a common cause; see Structured output.
`failed`	`internal_error`	A fault on Seltz’s side, including retrieval outages. Retry.
`cancelled`	`cancelled`	Stopped on request. `output` stays unset.

Enum spelling

Each surface spells the same enum value differently.

Where	Spelling
REST / JSON	`"pending"`, `"running"`, `"completed"`, `"failed"`, `"cancelled"` (lowercase)
TypeScript SDK	`AgentRunStatus.PENDING`, `.RUNNING`, `.COMPLETED`, `.FAILED`, `.CANCELLED`
Python SDK	`AgentRunStatus.AGENT_RUN_STATUS_PENDING`, `..._RUNNING`, `..._COMPLETED`, `..._FAILED`, `..._CANCELLED`

stop_reason follows the same pattern: REST/JSON is lowercase ("finished", "budget_reached", …), TypeScript is AgentRunStopReason.FINISHED, and Python is AgentRunStopReason.AGENT_RUN_STOP_REASON_FINISHED.

run.status prints as a raw integer in Python unless compared against the named constant. See Poll for completion.

Pagination

list takes limit (1–100, default 20) and after, the previous page’s next. next is unset on the last page; there is no has_more field on this listing.

Errors

A rejected request is a non-200 with the same {"error": {"code": ..., "message": ...}} envelope every other Seltz endpoint uses. code is the stable field to branch on; message is prose and can change.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "`query` must be non-empty"
  }
}

Status	Code	When
400	`INVALID_REQUEST`	Malformed body, unknown field, empty `query`, or a rejected `output_schema` (create); malformed or unknown query parameter (list).
401	`UNAUTHENTICATED`	Invalid, expired, revoked, or missing API key.
402	`INSUFFICIENT_CREDITS`	Insufficient budget to start the run.
404	`NOT_FOUND`	No such run in this org, or (on `list`) the `after` cursor does not resolve to one.

Over gRPC the same failures arrive as status codes (INVALID_ARGUMENT, UNAUTHENTICATED, NOT_FOUND, …) rather than as this body.

A failed run is not a rejection. The call itself succeeds, and the failure arrives as status: "failed" with stop_reason explaining why. See Handle errors.

Timing

Runs typically finish in well under a minute for a simple question. A harder one can take several minutes, and up to around an hour in the worst case. There is no fixed SLA on run duration; budget_reached and timeout exist precisely because a run does not run forever.

Getting Started

Web Tools

Data

Tutorials

Integrations

SDKs

Overview

Endpoints

SDK methods

Request

Run envelope

Output

Run status and stop reason

Enum spelling

Errors

Timing

​Overview

​Endpoints

​SDK methods

​Request

​Run envelope

​Output

​Run status and stop reason

​Enum spelling

​Pagination

​Errors

​Timing

Overview

Endpoints

SDK methods

Request

Run envelope

Output

Run status and stop reason

Enum spelling

Pagination

Errors

Timing