Trials HTTP API

Inspect an Evolve trial using its globally addressable id. Read the parent job’s trial list to obtain that id; trial routes do not require the job id. Examples reuse connection setup. Set TRIAL_ID from GET /api/jobs/{jobId}/trials:

curl -sS "$API/api/trials/$TRIAL_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

Success returns 200 Trial. See trial fields for status, rewards, exceptions, costs, and analysis. A missing or unavailable measurement can be null; do not replace it with zero.

Result routes

Method and path	Input	Success
`GET /api/trials/{trialId}`	Trial id	`200 Trial`
`GET /api/trials/{trialId}/download`	Trial id	`200`, `.tar.gz` archive
`GET /api/trials/{trialId}/trace`	Trace options below	`200`, trace page or selected artifact
`GET /api/trials/{trialId}/files`	Optional `limit`, `cursor`	`200 TrialFilePage`
`GET /api/trials/{trialId}/files/{filePath}`	Saved file path; optional `Range` header	`200` bytes, or `206` partial bytes
`POST /api/trials/{trialId}/retry`	No body; optional `Idempotency-Key` header	`202 Job`; replay `200`
`POST /api/trials/{trialId}/regrade`	No body	`202 Job`
`POST /api/trials/stop`	JSON with `trial_ids`	`200 StopResponse`

Saved files are the trial’s recorded outputs. Filesystem routes below inspect sandbox paths instead. See trial methods for result types and method equivalents.

Trace events and artifacts

Without stream, /trace returns parsed events. Its optional query fields are:

Field	Meaning
`cursor`	Continue from the previous page’s `nextCursor`
`limit`	Integer 1–1000; default 200
`type`	Exact event type, at most 100 characters
`grep`	Case-insensitive POSIX pattern, at most 512 characters
`tail`	Last 1–10000 matching events; combines with other filters and pagination

curl -sS --get "$API/api/trials/$TRIAL_ID/trace" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  --data-urlencode 'grep=error' \
  --data-urlencode 'limit=20'

Events are returned oldest first within the filtered selection. A null next cursor means caught up. Keep filters unchanged while paging. For stored artifacts, use stream:

`stream` value	Default response	Optional format
`trace-parsed`	Parsed event page	None
`verifier`	`{ log: string or null }`	`format=log`
`trace-stdout`, `trace-stderr`	`{ log: string or null }`	`format=log`
`trace-atif`	`{ log: string or null }`, with trajectory JSON encoded as text	`format=log`
`agent-home`	`{ files: object or null }`, mapping paths to text	`format=tgz` for the complete byte archive
`filesystem`	Sandbox filesystem archive	Use filesystem routes to choose live or captured files

Do not combine parsed-event filters with raw-artifact selectors. trajectory is reserved and currently returns not found; use trace-atif for the normalized trajectory.

curl -sS "$API/api/trials/$TRIAL_ID/trace?stream=verifier" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

No stored log is a normal 200 response:

{
  "log": null
}

Even with format=log, an absent log returns that JSON shape. A log withheld because it belongs to a retired retry attempt also includes reason. Agent-home text omits binary files; use format=tgz for their bytes.

Saved files and downloads

GET /files defaults to 200 entries, maximum 1000. Read a returned path through /files/{filePath}; URL-encode path segments. File reads accept a single HTTP byte range such as Range: bytes=0-1023; the end is inclusive.

curl --fail-with-body -sS "$API/api/trials/$TRIAL_ID/download" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -o trial.tar.gz

The download is the trial’s recorded Harbor folder. A still-running trial is refused rather than presented as a finished record.

Retry and regrade

curl -sS -X POST "$API/api/trials/$TRIAL_ID/retry" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

Retry requires a settled trial; the parent job can still be running. Regrade requires stored verifier inputs. Both return a new linked job and retain the source results. Uploaded trials cannot be retried or regraded. See job execution rules and idempotency.

Stop trials and analyses

Save selected ids in stop.json:

stop.json

{
  "trial_ids": ["YOUR_TRIAL_OR_ANALYSIS_ID"]
}

Replace the placeholder with an actual UUID. Supply 1–100 ids; trial and trace-analysis ids may be mixed.

curl -sS "$API/api/trials/stop" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @stop.json

Stopping is creator-only; team read access does not grant permission to stop another person’s run. The response reports stopped, stopped_analyses, already_terminal, and not_found. An unavailable id, including a readable run you do not own, appears in not_found. See the stop result. This route does not accept task-check ids.

Filesystem and logs

The following route suffixes apply to three resource prefixes:

Run	Prefix
Trial	`/api/trials/{trialId}`
Trace analysis	`/api/analyses/{analysisId}`
Task check	`/api/checks/{checkId}/tasks/{taskCheckId}`

Set RUN to a resolved prefix. For this trial:

RUN="$API/api/trials/$TRIAL_ID"

curl -sS "$RUN/filesystem" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

The FilesystemStatus response tells you the state and work_dir. Use that work directory or a path returned by a listing.

Method and suffix	Input	Success
`GET /filesystem`	None	`200 FilesystemStatus`
`GET /filesystem/files`	Optional `path`, `source`, `cursor`, `limit`	`200 FilesystemListing`
`GET /filesystem/files/{path}`	File path; optional `source` and `Range` header	`200` or `206` bytes
`GET /filesystem/search`	Required `q`; optional `path`, `regex`, `source`, `limit`	`200 FilesystemSearchResult`
`POST /filesystem/watch`	Required JSON `paths` array	`200 FilesystemWatchResult`
`GET /filesystem/events`	Optional `after` or `Last-Event-ID` header	`200 text/event-stream`
`GET /filesystem/changes`	Optional `source`, `phase`, `cursor`, `limit`	`200 FilesystemChanges`
`GET /filesystem/archive`	Optional `path`, `source`	`200` archive bytes
`GET /logs`	Required `stream`; optional `cursor`, `limit`	`200 SandboxLogLines`
`GET /logs/events`	Optional `Last-Event-ID` header	`200 text/event-stream`
`GET /procs`	None	`200 SandboxProcs`

Filesystem inputs

Field	Rules
`path`	Absolute sandbox path; defaults to `/` for listings, search, and archives
`source`	`live` or `capture`; omitted prefers live, then a saved capture
`cursor`	Continue the returned `next_cursor` for listings and changes
`limit`	Maximum 1000; list/changes default 500, search default 200
`q`	Required search text
`regex`	Boolean, default `false`
`phase`	`setup`, `agent`, `verifier`, or `all` (default)
`paths`	Watch request only; up to eight absolute folder paths, replacing the current set

Set WORK_DIR from the status response:

curl -sS --get "$RUN/filesystem/files" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  --data-urlencode "path=$WORK_DIR"

A capture can list unchanged image files whose bytes were not retained. Check captured before expecting to read every entry. Explicitly requesting an unavailable source returns 409 filesystem_state; reading an unretained file returns not_captured. A capture is not a full disk image.

Logs and events

stream accepts agent, verifier, system, setup, or metrics. Log pages default to 1000 lines, maximum 1000; continue with the returned next_cursor. System logs require system_log: true at job creation. Empty log results may include a reason.

curl -sS "$RUN/logs?stream=agent" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

For events, replace /logs?stream=agent with /logs/events and use curl -N. Retain the last event id and send Last-Event-ID on reconnection. Filesystem events also accept after. These streams do not reconnect by themselves. The filesystem reference and returned filesystem objects describe status, capture completeness, log pages, and process fields.

Errors

Unknown or inaccessible trials return 404 trial_not_found. Bad filters or ranges are refused. 409 concurrent_update means an artifact changed during the read; read it again. 413 on agent-home JSON means use its tgz format. Filesystem reads can return filesystem_state, not_captured, feature_unsupported, or provider_unreachable; inspect the code and details before retrying. See filesystem errors.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods