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

> ## Agent Instructions
> Evolve has two products behind one API key. Edith answers questions about an agent trajectory over HTTP: `POST https://api.evolvingmachines.ai/v1/decisions`. Evaluations run coding agents on tasks in cloud sandboxes, through the `evolve` CLI, the Python and TypeScript SDKs, or HTTP.
> A person creates the key at https://dashboard.evolvingmachines.ai/api-keys. Read it from `EVOLVE_API_KEY`; never ask for it in chat or write it to a file.
> Install the CLI with `npm install -g @evolvingmachines/evolve`, then confirm the connection with `evolve auth status`.
> The CLI carries the manual for its own version. `evolve skills get evals` prints the index and `evolve skills get evals <page>` prints one page, for example `evolve skills get evals cli-reference/run`. When the installed CLI is older than this site, follow the installed manual.
> Commands take `--help` for their options and `--json` for machine-readable output. Evaluations spend credits: start with one task and set `--max-trial-spend`.

# Trials HTTP API

> Read a trial's result and trace, download its files, and retry or regrade it.

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](https://docs.evolvingmachines.ai/api-reference/index.md#connect). Set `TRIAL_ID` from `GET /api/jobs/{jobId}/trials`:

```bash theme={"dark"}
curl -sS "$API/api/trials/$TRIAL_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"
```

Success returns `200 Trial`. See [trial fields](https://docs.evolvingmachines.ai/sdk-reference/types.md#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](https://docs.evolvingmachines.ai/sdk-reference/methods/trials.md) 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 |

```bash theme={"dark"}
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](#filesystem-and-logs) 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.

```bash theme={"dark"}
curl -sS "$API/api/trials/$TRIAL_ID/trace?stream=verifier" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"
```

No stored log is a normal `200` response:

```json theme={"dark"}
{
  "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.

```bash theme={"dark"}
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

```bash theme={"dark"}
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](https://docs.evolvingmachines.ai/api-reference/jobs.md#change-execution) and [idempotency](https://docs.evolvingmachines.ai/api-reference/index.md#idempotent-job-submissions).

## Stop trials and analyses

Save selected ids in `stop.json`:

```json stop.json theme={"dark"}
{
  "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.

```bash theme={"dark"}
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](https://docs.evolvingmachines.ai/sdk-reference/methods/trials.md#stop). 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:

```bash theme={"dark"}
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:

```bash theme={"dark"}
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.

```bash theme={"dark"}
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](https://docs.evolvingmachines.ai/sdk-reference/filesystem.md) and [returned filesystem objects](https://docs.evolvingmachines.ai/sdk-reference/types.md#filesystem-results) 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](https://docs.evolvingmachines.ai/sdk-reference/error-codes.md#filesystems-and-sessions).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.