trials - Evolve

trials() returns the trials client. A trial id is global: no method needs the job id.

get

TypeScript
Python

get(trialId: string): Promise<Trial>

One trial in full. Its job_id points back to the job.

const trial = await trials().get("d1a10c4e-…");

async def get(trial_id: str) -> Trial

One trial in full. Its job_id points back to the job.

trial = await trials().get("d1a10c4e-…")

trace, traceEvents

TypeScript
Python

trace(
  trialId: string,
  options?: { cursor?: string; limit?: number; type?: string; grep?: string; tail?: number },
): Promise<TraceEventPage>
traceEvents(
  trialId: string,
  options?: TraceOptions,
): AsyncIterableIterator<TraceEvent>

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.

for await (const event of trials().traceEvents(
  trial.id,
  { grep: "permission denied" },
)) {
  console.log(event.seq, event.type);
}

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.

async for event in trials().trace_events(
    trial.id,
    grep="permission denied",
):
    print(event.seq, event.type)

artifact

TypeScript
Python

artifact(
  trialId: string,
  stream: "verifier" | "trace-stdout" | "trace-stderr" | "trace-atif" | "trajectory",
): Promise<string | null>
artifact(
  trialId: string,
  stream: "agent-home",
): Promise<Record<string, string> | null>

One raw artifact, the same names evolve trial download --stream takes. Null means the trial never stored it.

const log = await trials().artifact(trial.id, "verifier");

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

log = await trials().artifact(trial.id, "verifier")

files, file

TypeScript
Python

files(
  trialId: string,
  options?: { limit?: number; cursor?: string },
): Promise<TrialFilePage>
file(
  trialId: string,
  path: string,
  range?: { start?: number; end?: number; suffix?: number },
): Promise<Buffer>

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.

const tail = await trials().file(
  trial.id,
  "verifier/test-stdout.txt",
  { suffix: 4096 },
);

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.

tail = await trials().file(
    trial.id,
    "verifier/test-stdout.txt",
    suffix=4096,
)

regrade, retry, stop

TypeScript
Python

regrade(trialId: string): Promise<Job>
retry(
  trialId: string,
  options?: StartJobOptions,
): Promise<Job>
stop(trialIds: string[]): Promise<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.

const again = await trials().retry(trial.id);

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

again = await trials().retry(trial.id)

​get

​trace, traceEvents

​artifact

​files, file

​regrade, retry, stop

get

trace, traceEvents

artifact

files, file

regrade, retry, stop