Trials methods

Use trials() to create client. IDs name existing records. The trial guide shows the full inspection workflow. Examples reuse the SDK setup. Use IDs returned by the relevant list or create call. Run Python snippets inside the async function shown in the Python guide.

Read	Act
get, trace, traceEvents	retry, regrade, stop
files, file, artifact, download, filesystem

get

Read one attempt by its globally unique id. Returns Trial, including job_id and the untruncated exception message.

Signature

get(trialId: string): Promise<Trial>;

async def get(trial_id: str) -> Trial: ...

import { trials } from "@evolvingmachines/evolve";

const client = trials();
const trial = await client.get(trialId);

from evolve import trials

client = trials()
trial = await client.get(trial_id)

See trial fields for rewards, usage, retries, timing, and provenance.

trace

Read one page of parsed events. Returns TraceEventPage.

Signature

trace(
  trialId: string,
  options?: TraceOptions
): Promise<TraceEventPage>;

async def trace(
    trial_id: str,
    *,
    cursor: Optional[str] = None,
    limit: Optional[int] = None,
    type: Optional[str] = None,
    grep: Optional[str] = None,
    tail: Optional[int] = None,
) -> TraceEventPage: ...

const page = await client.trace(trialId, {
  tail: 20
});

page = await client.trace(
    trial_id,
    tail=20,
)

Option	Meaning / default
`cursor`	Events strictly after this sequence number, passed as a string
`limit`	Events per page: default 200, maximum 1,000
`type`	Exact event type
`grep`	Case-insensitive POSIX regular expression over type and content
`tail`	Last N matching events, still returned oldest first

The page has items, nextCursor, hasMore / Python next_cursor, has_more. An event has seq: number, type: string, and data: object. A null next cursor means caught up. To poll again later, retain the last event’s seq.

traceEvents

Python: trace_events. Iterate currently available parsed events across pages. It finishes when caught up; it is not a live subscription.

Signature

traceEvents(
  trialId: string,
  options?: TraceOptions
): AsyncIterableIterator<TraceEvent>;

async def trace_events(
    trial_id: str,
    *,
    cursor: Optional[str] = None,
    limit: Optional[int] = None,
    type: Optional[str] = None,
    grep: Optional[str] = None,
    tail: Optional[int] = None,
) -> AsyncIterator[TraceEvent]: ...

for await (const event of client.traceEvents(trialId)) {
  console.log(event.seq, event.type);
}

async for event in client.trace_events(trial_id):
    print(event.seq, event.type)

Accepts the same cursor, limit, type, grep, and tail options as trace. Returns an async iterator of TraceEvent.

files

List the stored trial tree by relative path. Returns one TrialFilePage, sorted by path.

Signature

files(
  trialId: string,
  options?: ListTrialFilesOptions
): Promise<TrialFilePage>;

async def files(
    trial_id: str,
    *,
    cursor: Optional[str] = None,
    limit: Optional[int] = None,
) -> TrialFilePage: ...

const page = await client.files(trialId, {
  limit: 20
});

page = await client.files(
    trial_id,
    limit=20,
)

Optional limit defaults to 200 (maximum 1,000); cursor continues the page. Each item contains path: string and size_bytes: number. An empty tree is a normal result.

file

Read one path returned by files. Returns exact bytes: TypeScript Buffer, Python bytes.

Signature

file(
  trialId: string,
  path: string,
  range?: TrialFileRange
): Promise<Buffer>;

async def file(
    trial_id: str,
    path: str,
    *,
    start: Optional[int] = None,
    end: Optional[int] = None,
    suffix: Optional[int] = None,
) -> bytes: ...

const bytes = await client.file(
  trialId,
  "agent/stderr.log",
  {
    suffix: 4096
  }
);

data = await client.file(
    trial_id,
    'agent/stderr.log',
    suffix=4096,
)

Optional byte range: start plus inclusive end, start through EOF, or suffix for the last N bytes. Do not combine suffix with start or end. TypeScript passes the range as the third object; Python uses keyword arguments. A missing path is a typed 404.

artifact

Read a named stored artifact. Returns text, a path-to-text map, or null when nothing is served. Request a reason to distinguish unavailable output from output withheld after a retry.

Signature

artifact(
  trialId: string,
  stream: Exclude<
    TrialArtifactStream,
    "trace-parsed" | "agent-home" | "filesystem"
  >
): Promise<string | null>;
artifact(
  trialId: string,
  stream: Exclude<
    TrialArtifactStream,
    "trace-parsed" | "agent-home" | "filesystem"
  >,
  options: { withReason: true }
): Promise<TrialArtifactLog>;
artifact(
  trialId: string,
  stream: "agent-home"
): Promise<Record<string, string> | null>;

async def artifact(
    trial_id: str,
    stream: Literal[
        'trace-parsed',
        'verifier',
        'trace-stdout',
        'trace-stderr',
        'trace-atif',
        'trajectory',
        'agent-home',
        'filesystem',
    ],
    *,
    with_reason: bool = False,
) -> Optional[Union[str, Dict[str, str], TrialArtifactLog]]: ...

const trajectory = await client.artifact(
  trialId,
  "trace-atif"
);

trajectory = await client.artifact(
    trial_id,
    'trace-atif',
)

Selector	Result
`verifier`, `trace-stdout`, `trace-stderr`	`string \| null` / `str \| None`
`trace-atif`	ATIF v1.7 document as JSON text, or null
`agent-home`	Map of sandbox paths to UTF-8 file text, or null
`trajectory`	Reserved native-session selector; currently returns not-found

Null / None means nothing is served: output may be absent, purged, or withheld because it belongs to an earlier retry attempt. For log selectors, pass { withReason: true } in TypeScript or with_reason=True in Python to return TrialArtifactLog:

const output = await client.artifact(trialId, "verifier", {
  withReason: true,
});
console.log(output.log, output.reason);

output = await client.artifact(
    trial_id,
    "verifier",
    with_reason=True,
)
print(output.log, output.reason)

TrialArtifactLog contains log: string | null and optional reason: string. Python returns a dataclass with log and reason, both nullable. A supplied reason explains why output from an earlier attempt was withheld. This option does not apply to agent-home; TypeScript exposes no such overload and Python raises ValueError. Use trace for trace-parsed, and filesystem(id).archive() for filesystem. Python’s annotation lists these selectors, but artifact rejects both locally. Non-text home files are omitted from the text map and recorded in /agent-home.json; the job archive preserves their bytes.

download

Download one settled trial’s folder as a .tar.gz. Its job can still be running.

Signature

download(trialId: string): Promise<Buffer>;
download(
  trialId: string,
  options: { to: string }
): Promise<string>;
download(
  trialId: string,
  options: { stream: true }
): Promise<ReadableStream<Uint8Array>>;
download(
  trialId: string,
  options?: DownloadJobOptions
): Promise<Buffer | string | ReadableStream<Uint8Array>>;

async def download(
    trial_id: str,
    *,
    to: Optional[str] = None,
) -> bytes | str: ...

const path = await client.download(trialId, {
  to: "./results"
});

path = await client.download(
    trial_id,
    to='./results',
)

The archive extracts to the trial’s folder, <task>__<7 characters>/, with the same files as this trial’s folder in a job download. Job-level files are not included. Cost and token figures can still change for about 30 minutes after the trial ends, and analysis.json appears once an analysis of the trial completes. Omit options for Buffer / bytes; use to for a saved file path. TypeScript also accepts { stream: true }, a raw stream whose integrity the caller verifies. Python has no stream option. A trial that has not settled, including one still due an automatic retry or still being finished by its worker, returns trial_not_settled; wait, then retry. A regrade outcome has no trial folder and returns feature_unsupported; details.source_trial_id names the trial to download instead.

filesystem

Get a RunFilesystem client for this attempt. No request is made until you call a method on it.

Signature

filesystem(trialId: string): RunFilesystem;

def filesystem(trial_id: str) -> 'RunFilesystem': ...

const fs = client.filesystem(trialId);
const status = await fs.status();

fs = client.filesystem(trial_id)
status = await fs.status()

See every filesystem method, including live files, captured files, sandbox logs, and processes.

retry

Run one settled attempt again in a new linked job. Returns Job; the source job may still be running.

Signature

retry(
  trialId: string,
  options?: StartJobOptions
): Promise<Job>;

async def retry(
    trial_id: str,
    *,
    idempotency_key: Optional[str] = None,
) -> Job: ...

const job = await client.retry(trialId, {
  idempotencyKey: requestId
});

job = await client.retry(
    trial_id,
    idempotency_key=request_id,
)

Optional idempotencyKey / idempotency_key makes a repeated request return the same accepted job. This is the one-trial form of jobs().retry. Imported attempts cannot retry.

regrade

Run only the verifier again against eligible recorded inputs. Returns a new one-trial Job.

Signature

regrade(trialId: string): Promise<Job>;

async def regrade(trial_id: str) -> Job: ...

const job = await client.regrade(trialId);

job = await client.regrade(trial_id)

The attempt must be settled and have retained inputs from separate verification. Shared-mode or pre-persistence trials are refused with regrade_source_ineligible; imported jobs are refused.

stop

Stop selected in-flight trials or trace analyses owned by the caller. Returns StopResponse. Pass 1–100 non-empty IDs in one call. The list can contain trial IDs, analysis IDs, or both.

Signature

stop(trialIds: string[]): Promise<StopResponse>;

async def stop(trial_ids: List[str]) -> StopResponse: ...

const result = await client.stop([trialId, analysisId]);

result = await client.stop(
    [trial_id, analysis_id],
)

Returned field	Type / meaning
`stopped`	`Trial[]`: attempts settled by this request
`stopped_analyses`	`TrialAnalysis[]`: analyses settled as failed, phase `stopped`
`already_terminal`	`string[]`: untouched settled ids
`not_found`	`string[]`: missing ids or ids owned by someone else

This does not cancel the whole job. Repeating the request is safe: terminal work stays unchanged.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Trials methods

get

trace

traceEvents

files

file

artifact

download

filesystem

retry

regrade

stop