> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolvingmachines.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# trials
> Read, download, and act on single trials.
`trials()` returns the trials client. A trial id is global: no method needs the job id.
## get
```ts theme={null}
get(trialId: string): Promise
```
One trial in full. Its `job_id` points back to the job.
```ts theme={null}
const trial = await trials().get("d1a10c4e-…");
```
```python theme={null}
async def get(trial_id: str) -> Trial
```
One trial in full. Its `job_id` points back to the job.
```python theme={null}
trial = await trials().get("d1a10c4e-…")
```
## trace, traceEvents
```ts theme={null}
trace(
trialId: string,
options?: { cursor?: string; limit?: number; type?: string; grep?: string; tail?: number },
): Promise
traceEvents(
trialId: string,
options?: TraceOptions,
): AsyncIterableIterator
```
One page of the parsed trace, or every available event; `traceEvents` drains what is stored and stops. `type` (an exact type), `grep` (a case-insensitive regex over type and content, a plain string being a substring) and `tail` (the last N matches, 1 to 10000) filter on the server and compose with the cursor.
A cursor is a `seq`: to resume later, pass the last event's `seq` as a string. `limit` defaults to 200, at most 1000, and event 0 is the instruction.
```ts theme={null}
for await (const event of trials().traceEvents(
trial.id,
{ grep: "permission denied" },
)) {
console.log(event.seq, event.type);
}
```
```python theme={null}
async def trace(
trial_id: str,
*,
cursor=None,
limit=None,
type=None,
grep=None,
tail=None,
) -> TraceEventPage
async def trace_events(
trial_id: str,
*,
cursor=None,
limit=None,
type=None,
grep=None,
tail=None,
)
```
One page of the parsed trace, or every available event; `trace_events` drains what is stored and stops. `type` (an exact type), `grep` (a case-insensitive regex over type and content, a plain string being a substring) and `tail` (the last N matches, 1 to 10000) filter on the server and compose with the cursor.
A cursor is a `seq`: to resume later, pass the last event's `seq` as a string. `limit` defaults to 200, at most 1000, and event 0 is the instruction.
```python theme={null}
async for event in trials().trace_events(
trial.id,
grep="permission denied",
):
print(event.seq, event.type)
```
## artifact
```ts theme={null}
artifact(
trialId: string,
stream: "verifier" | "trace-stdout" | "trace-stderr" | "trace-atif" | "trajectory",
): Promise
artifact(
trialId: string,
stream: "agent-home",
): Promise | null>
```
One raw artifact, the same names `evolve trial download --stream` takes. Null means the trial never stored it.
```ts theme={null}
const log = await trials().artifact(trial.id, "verifier");
```
```python theme={null}
async def artifact(
trial_id: str,
stream: Literal['trace-parsed', 'verifier', 'trace-stdout', 'trace-stderr', 'trace-atif', 'trajectory', 'agent-home'],
) -> Optional[Union[str, Dict[str, str]]]
```
One raw artifact, the same names `evolve trial download --stream` takes. None means the trial never stored it. `trace-parsed` is refused here; use `trace()`.
```python theme={null}
log = await trials().artifact(trial.id, "verifier")
```
## files, file
```ts theme={null}
files(
trialId: string,
options?: { limit?: number; cursor?: string },
): Promise
file(
trialId: string,
path: string,
range?: { start?: number; end?: number; suffix?: number },
): Promise
```
Every file the platform stored for the trial, as `{ path, size_bytes }` rows sorted by path (`limit` default 200, at most 1000), and the raw bytes of one of them. A range reads a slice; `suffix` reads the last N bytes. A very large file must be read by range. There is no CLI verb for either.
```ts theme={null}
const tail = await trials().file(
trial.id,
"verifier/test-stdout.txt",
{ suffix: 4096 },
);
```
```python theme={null}
async def files(
trial_id: str,
*,
cursor: Optional[str] = None,
limit: Optional[int] = None,
) -> TrialFilePage
async def file(
trial_id: str,
path: str,
*,
start: Optional[int] = None,
end: Optional[int] = None,
suffix: Optional[int] = None,
) -> bytes
```
Every file the platform stored for the trial, as `path` and `size_bytes` rows sorted by path (`limit` default 200, at most 1000), and the raw bytes of one of them. A range reads a slice; `suffix` reads the last N bytes. A very large file must be read by range. There is no CLI verb for either.
```python theme={null}
tail = await trials().file(
trial.id,
"verifier/test-stdout.txt",
suffix=4096,
)
```
## regrade, retry, stop
```ts theme={null}
regrade(trialId: string): Promise
retry(
trialId: string,
options?: StartJobOptions,
): Promise
stop(trialIds: string[]): Promise
```
Re-run only the verifier, run the trial again, or stop in-flight trials. A regrade and a retry each return a new one-trial job; `regrade` is refused with `regrade_source_ineligible` for a shared-mode trial, `retry` with `trial_not_settled` for a live one.
`stop` takes at most 100 ids, trials and analyses mixed, and reports each in exactly one of `stopped`, `stopped_analyses`, `already_terminal` or `not_found`. Stopped trials rejoin the run on a `resume` of their job.
```ts theme={null}
const again = await trials().retry(trial.id);
```
```python theme={null}
async def regrade(trial_id: str) -> Job
async def retry(
trial_id: str,
*,
idempotency_key: Optional[str] = None,
) -> Job
async def stop(trial_ids: List[str]) -> StopResponse
```
Re-run only the verifier, run the trial again, or stop in-flight trials. A regrade and a retry each return a new one-trial job; `regrade` is refused with `regrade_source_ineligible` for a shared-mode trial, `retry` with `trial_not_settled` for a live one.
`stop` takes at most 100 ids, trials and analyses mixed, and reports each in exactly one of `stopped`, `stopped_analyses`, `already_terminal` or `not_found`. Stopped trials rejoin the run on a `resume` of their job.
```python theme={null}
again = await trials().retry(trial.id)
```