Analyses HTTP API

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. Set JOB_ID to a terminal job’s id:

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

Analysis configuration

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

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 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:

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:

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 with /api/analyses/{analysisId} as the resource prefix. This includes file browsing, search, changes, watching, archives, logs, and processes. The analysis SDK methods 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.

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.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Analyses HTTP API

Routes

Analysis configuration

Read results and files

Errors