Run evaluations over HTTP

Run Codex on one DeepSWE task with Evolve’s HTTP API. These examples use curl directly; the CLI and SDKs call the same service. See the HTTP API reference for supported resource routes.

Connect

You need curl 7.76 or newer and a Full access key from the dashboard’s API keys page. Replace your-api-key below. Writes require full access; a read-only key can inspect existing jobs. Your account also needs available credits to run evaluations. If submission returns HTTP 402 with insufficient_credits, add credits in the dashboard and retry.

export EVOLVE_API_KEY="your-api-key"
API="https://dashboard.evolvingmachines.ai"

curl --fail-with-body -i -sS "$API/api/auth/status" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

Success returns HTTP 200 with your identity and key metadata. The -i flag shows response headers, including the HTTP status. See account setup if authentication fails. GET /api/meta needs no key. It lists the current harnesses, models, limits, and error codes.

Start one evaluation

Save this as job.json. It selects one task from deepswe@1.1 and runs Codex with GPT-6 Luna:

job.json

{
  "datasets": [
    {
      "name": "deepswe",
      "version": "1.1",
      "task_names": ["anko-default-function-arguments"]
    }
  ],
  "agents": [
    {
      "name": "codex",
      "model_name": "gpt-6-luna"
    }
  ],
  "max_trial_spend_usd": 1,
  "retry": {
    "max_retries": 0
  }
}

Submit the file from the same directory:

curl --fail-with-body -i -sS "$API/api/jobs" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @job.json

Success returns HTTP 202 and the accepted job. Copy its id into JOB_ID:

JOB_ID="paste-job-id-here"

The job runs after the response returns. Closing the HTTP connection does not cancel it. The $1 cap applies to model spend for this trial attempt. A call already in progress can finish above it. Setting max_retries to 0 disables configured infrastructure retries; provider capacity waits can still occur. The JSON fields match the SDK job inputs. Add org to create the job in a team. Attach stored secrets through the request’s secret references.

For retry-safe submission, send an Idempotency-Key header on the first request and each retry. Keep the same key and request body for that intended job. A replay returns HTTP 200 with idempotent_replay: true; reusing the key for a different request returns 409. A new intended run needs a new key.

Follow the result

Read status
Read trials
Stream progress

curl --fail-with-body -i -sS "$API/api/jobs/$JOB_ID" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

Repeat until status is COMPLETED, CANCELLED, or FAILED.

curl --fail-with-body -i -sS "$API/api/jobs/$JOB_ID/trials" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

Read the trial records in items, including each trial’s id, status, and reward.

curl --fail-with-body -i -N -sS "$API/api/jobs/$JOB_ID/events" \
  -H "Authorization: Bearer $EVOLVE_API_KEY"

This returns server-sent progress events. A terminal job event marks completion. curl does not reconnect automatically. To resume, reopen the stream with Last-Event-ID set to the last event’s id. The SDK watchers handle reconnection for you.

A completed job can contain failed trials. Inspect the trial’s status and reward; a missing reward is not zero. Use the trial API reference to read its trace, logs, and files.

Page through collections

Job and trial lists return items, nextCursor, and hasMore. If the trials response above has a non-null nextCursor, copy it into NEXT_CURSOR and request the next page:

NEXT_CURSOR="paste-nextCursor-here"
curl --fail-with-body -i -sS --get \
  "$API/api/jobs/$JOB_ID/trials" \
  -H "Authorization: Bearer $EVOLVE_API_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Keep the same filters. Treat the cursor as an opaque string and stop when nextCursor is null.

Handle an error

An API refusal returns a non-success HTTP status and an error object. These examples use --fail-with-body, so HTTP errors produce a nonzero exit status while keeping the response body. The -i flag also shows the HTTP status and response headers.

Field	Use
`code`	Choose how your client handles the failure
`message`	Explain the problem to the caller
`param`, `details`	Locate invalid input or read failure context, when present
`request_id`	Identify the request when reporting a problem
`retryAfterSec`	Requested delay, when present; also sent as `Retry-After`

The response also includes X-Request-Id. See error handling for common codes and the difference between retrying an HTTP request and retrying a trial.

Operations beyond the SDK methods

Need	Reference
List or revoke API keys	Key management
Manage team names, roles, and invitations	Team management
Filter or sort the dataset catalog	Dataset filters

Continue with the HTTP API reference for the supported job, trial, dataset, and account operations.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Run evaluations over HTTP

Connect

Start one evaluation

Follow the result

Page through collections

Handle an error

Operations beyond the SDK methods