> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seltz.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Reference
> Reference information for the Seltz Agent API
## 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](/api-reference/agent/start-run), [List runs](/api-reference/agent/list-runs),
[Retrieve a run](/api-reference/agent/get-run), and
[Cancel a run](/api-reference/agent/cancel-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](/monitor/guides/webhooks).
## 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](/agent/guides/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](/agent/guides/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.
```json theme={null}
{
"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](/agent/guides/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.