> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trajectory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Client reference

> Configure the Python client and page through results.

Install `trajectory-sdk` and import `Client` from `trajectory`.

```python theme={null}
from trajectory import Client

with Client() as client:
    page = client.agents.list(limit=20)
    for agent in page.items:
        print(agent.name, agent.description)
```

## Configuration

| Option | Behavior |
| - | - |
| `api_key` | Defaults to `TRAJECTORY_API_KEY`. |
| `base_url` | Defaults to `TRAJECTORY_BASE_URL`, then `https://api.trajectory.ai`. |
| `timeout` | Seconds, an `httpx2.Timeout`, or `None`. |
| `max_retries` | Retries after the first attempt. Defaults to `2`. |
| `http_client` | Your own `httpx2.Client`. |

```python theme={null}
from trajectory import Client

client = Client()
page = client.with_options(timeout=30, max_retries=0).benchmarks.list(limit=10)
print(page.model_dump())
```

## Resources

| Resource | Use |
| - | - |
| `client.agents` | Agents that own specs (benchmarks), runs, and deployments. |
| `client.benchmarks` | Specs, tasks, and readiness. |
| `client.diagnostics` | Task and spec diagnostics. |
| `client.evals` | Evaluations. |
| `client.training` | Training runs and checkpoints. |
| `client.deployments` | Deployments. |
| `client.model_slugs` | Each agent's production model slug. |
| `client.chat.completions` | Model calls. |
| `client.responses` | Model calls in the Responses format. |
| `client.inference` | Models your organization can call. |
| `client.trajectories` | Rewards, events, and completion. |
| `client.artifacts` | Artifact downloads by ID. |
| `client.datasets` | Trajectory datasets. |
| `client.telemetry` | Application events. |
| `client.billing` | Run costs over the last 30 days. |
| `client.organizations` | The current organization. |
| `client.secrets` | Named runtime secrets. |

`trajectory.lib` provides two forms of the same spec upload workflow:

| Helper | Returns when | Result |
| - | - | - |
| `push(...)` | Registration and any requested image builds finish. | Spec result with `bench_id`. |
| `start_push(...)` | Files are uploaded and processing is accepted. | Operation you can wait on or reconnect to later. |

`push()` calls `start_push()` and waits with `operation.result()` internally. Both accept
the same arguments. `start_push()` is a regular Python function; background processing
happens on the server. See the [spec guide](https://docs.trajectory.ai/guides/spec.md).

To edit tasks within an existing spec version, use `client.benchmarks.tasks.append(...)`
followed by `client.benchmarks.tasks.commit(...)` with that version's spec ID.

## Training and evaluation

Both resources accept `create(agent_name=..., benchmark_name=..., base_model_slug=..., options=...)`
to select the latest spec version under that agent. Pass `bench_id` instead of the name
pair to select a specific version. Finish a baseline/checkpoint comparison before publishing
another version under the same name.

Use `parent_checkpoint_id` to resume training or evaluate a checkpoint. Request
`options` dictionaries follow the shared `RunOptionsParam` type; run responses expose
typed `RunOptions` values. Omitted, null, and empty options preserve defaults.

```python theme={null}
from trajectory.types.run_options_param import RunOptionsParam

options: RunOptionsParam = {"reasoning_effort": "off"}
run = client.evals.create(
    agent_name="YOUR_AGENT_NAME",
    benchmark_name="YOUR_BENCHMARK_NAME",
    base_model_slug="Qwen/Qwen3.5-4B",
    options=options,
)
result = client.evals.runs.retrieve(run.eval_run_id)
print(result.base_model_slug, result.options.reasoning_effort)
```

Use `client.training.list_options(...)` or `client.evals.list_options(...)` with
`bench_id` and an optional `base_model_slug` to discover supported settings for that
mode. Each model has `base_model_slug` and an `options` map with types, bounds,
descriptions, and fixed or computed defaults. Training and evaluation may have
different bounds for the same setting.

## Pagination

`.items` is the current page. Iterating the page fetches the rest.

```python theme={null}
from trajectory import Client

client = Client()
for agent in client.agents.list(limit=20):
    print(agent.name, agent.description)
```

`.has_next_page()` and `.get_next_page()` request the next page yourself.

## Raw response

```python theme={null}
from trajectory import Client

client = Client()
response = client.benchmarks.with_raw_response.list(limit=10)
print(response.headers.get("x-request-id"))
page = response.parse()
print(page.model_dump())
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.