Client reference

Install trajectory-sdk and import Client from trajectory.

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`.

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. 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.

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.

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

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())

Get started

Build and improve

Production learning

Reference

Configuration

Resources

Training and evaluation

Raw response

​Configuration

​Resources

​Training and evaluation

​Pagination

​Raw response

Configuration

Resources

Training and evaluation

Pagination

Raw response