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

# Analyses HTTP API

> Start trace analysis for a job, list analysis runs, and download their reports.

Ask an Evolve analyzer to review completed trial traces against a rubric. Start the analysis through its job, then read each trial's `analysis` or list the analysis runs.

Examples reuse [connection setup](https://docs.evolvingmachines.ai/api-reference/index.md#connect). Set `JOB_ID` to a terminal job's id:

```bash theme={"dark"}
curl -sS "$API/api/jobs/$JOB_ID/analyze" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{}'
```

Success returns `202 Job` with analysis work queued. The source trials retain their evaluation results. Read [analysis and check result fields](https://docs.evolvingmachines.ai/sdk-reference/types.md#analysis-and-check-results) for summaries, criterion outcomes, failure information, and cost.

## Routes

| Method and path | Input | Success |
| - | - | - |
| `POST /api/jobs/{jobId}/analyze` | Optional JSON configuration below | `202 Job` |
| `GET /api/analyses` | Optional `job`, `status`, `scope`, `limit`, `cursor` | `200 AnalysisPage` |
| `GET /api/analyses/defaults` | Optional `agent` | `200 AnalyzeDefaults` |
| `GET /api/analyses/{analysisId}/download` | Analysis id | `200`, `.tar.gz` archive |

`job` is a job UUID. `status` accepts `queued`, `running`, `completed`, or `failed`, repeated for multiple values. `scope` is `my` (default), `shared`, or `org`. Collections follow [catalog pagination](https://docs.evolvingmachines.ai/api-reference/index.md#pagination).

## Analysis configuration

Every field is optional. `{}` selects the current defaults; read them before choosing overrides:

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

The response gives `agent`, `model_name`, `rubric`, `prompt`, `reasoning_effort`, and `sandbox_provider`. Add `?agent=codex` to resolve defaults for that analyzer agent.

| JSON field | Meaning and constraints |
| - | - |
| `agent` | Analyzer harness advertised in `/api/meta` under `analyze.agents` |
| `model_name` | Model on that agent's roster; omitted uses its default |
| `reasoning_effort` | A supported effort for that model; omitted uses its default |
| `sandbox_provider` | Supported provider; omitted uses the analysis default when queued |
| `rubric` | Object with a nonempty `criteria` array; each criterion has `name`, `description`, and `guidance` |
| `prompt` | Nonempty template text replacing the default prompt |
| `n_concurrent` | Integer 1–150, also bounded by the organization's analysis concurrency quota |
| `trial_ids` | Nonempty list of unique trial ids belonging to this job; manual analysis only, refused in `JobCreate.analyze` |
| `passing` | Boolean, default `false`; select scored trials whose primary reward is exactly 1 |
| `failing` | Boolean, default `false`; select other analyzable trials |
| `n_trials` | Positive integer cap after trial selection and reward filtering |

`passing` and `failing` cannot both be true. Cancelled trials are excluded. Selection applies `trial_ids` first, then the reward filter, then `n_trials`. A `trial_ids` entry from another job refuses the request.

An omitted `n_concurrent` leaves the organization quota as the limit. See [analysis configuration](https://docs.evolvingmachines.ai/sdk-reference/analyses.md#configuration) for prompt tokens, rubric rules, and the difference between omission and a pinned override.

An analysis that finishes without a valid result is retried at most once. A budget timeout fails without that retry. Repeating this POST starts a new analysis wave only after the earlier wave settles. Earlier analyses remain stored.

## Read results and files

List runs for the job:

```bash theme={"dark"}
curl -sS --get "$API/api/analyses" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  --data-urlencode "job=$JOB_ID"
```

Set `ANALYSIS_ID` to an id from the response. Download a settled run:

```bash theme={"dark"}
curl --fail-with-body -sS \
  "$API/api/analyses/$ANALYSIS_ID/download" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -o analysis.tar.gz
```

The archive uses Harbor's analysis wrapper-trial layout. Its validated `artifacts/analysis.json` exists when analysis completed successfully.

The analyzer's sandbox uses the [filesystem and log routes](https://docs.evolvingmachines.ai/api-reference/trials.md#filesystem-and-logs) with `/api/analyses/{analysisId}` as the resource prefix. This includes file browsing, search, changes, watching, archives, logs, and processes. The [analysis SDK methods](https://docs.evolvingmachines.ai/sdk-reference/methods/analyses.md) also provide result and transcript conveniences.

To stop active analysis work, use `POST /api/trials/stop` with analysis ids in `trial_ids`; see [stopping trials and analyses](https://docs.evolvingmachines.ai/api-reference/trials.md#stop-trials-and-analyses).

## Errors

Starting analysis requires a terminal job. `409 job_not_terminal`, `analysis_already_running`, or `no_analyzable_trials` explains why no wave started. Invalid configuration returns `400 invalid_input` or `invalid_rubric`.

Downloading an unfinished analysis returns `409 analysis_not_terminal`. A settled run can return the same code while its results are still being finalized; retry later. Unknown or inaccessible ids return `404 analysis_not_found`. See [analysis error codes](https://docs.evolvingmachines.ai/sdk-reference/error-codes.md#analysis-and-task-checks).


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