Skip to main content

Re-run an evaluation

When executions fail (a transient target error, a timeout, a flaky connection), re-run them instead of launching a fresh evaluation. Spectral gives you three ways to do it, depending on how much you want to re-run:

ModeEndpointUse it when
One executionPOST …/executions/{executionId}/rerunA single conversation failed and you want just that one to run again.
Failed executionsPOST …/evaluations/{evaluationId}/rerun-failedSeveral conversations in an evaluation failed and you want to retry only those.
The whole evaluationPOST …/evaluations/{evaluationId}/rerunYou want a clean run of the entire evaluation, optionally regenerating its scenarios.

The first two re-run in place: they retry work inside the existing evaluation, which re-opens (its status returns to building) and re-finalizes when the reruns complete. The third clones: it produces a new evaluation and leaves the original untouched.

Every mode returns a job. Poll it to completion exactly as you did when launching the evaluation; see Async jobs.

warning

Forensic evaluations are not rerunnable: they judge transcripts you supplied, so there is nothing to run again.

Rerun one execution​

Re-run a single failed execution within its existing evaluation:

Request
curl -X POST \
     https://spectral.principled.app/api/v1/targets/9f8c2.../executions/a1b2c.../rerun \
     -H "Authorization: Bearer ak_****"

The response returns the re-queued execution, the re-opened evaluation, and the job to poll:

Response
{
  "execution": {
    "id": "a1b2c...",
    "evaluation_id": "7c4d9...",
    "status": "queued",
    "mode": "ADVERSARIAL"
  },
  "evaluation": { "id": "7c4d9...", "status": "building" },
  "job": {
    "id": "job_re1a2...",
    "status": "queued",
    "kind": "create_run",
    "resource": { "type": "evaluation", "id": "7c4d9..." },
    "created_at": "2026-06-22T13:00:00Z"
  }
}

Rerun the failed executions​

Re-run every failed execution in an evaluation in one call:

Request
curl -X POST \
     https://spectral.principled.app/api/v1/targets/9f8c2.../evaluations/7c4d9.../rerun-failed \
     -H "Authorization: Bearer ak_****"

reran_count tells you how many executions were re-queued:

Response
{
  "evaluation": { "id": "7c4d9...", "status": "building" },
  "reran_count": 2,
  "job": {
    "id": "job_rf9b3...",
    "status": "queued",
    "kind": "create_run",
    "resource": { "type": "evaluation", "id": "7c4d9..." },
    "created_at": "2026-06-22T13:05:00Z"
  }
}

If the evaluation has no failed executions, reran_count is 0 and job is null: there is nothing to poll.

Rerun the whole evaluation​

Re-run the entire evaluation as a new run. This leaves the original evaluation and its results in place and returns a new evaluation:

Request
curl -X POST \
     https://spectral.principled.app/api/v1/targets/9f8c2.../evaluations/7c4d9.../rerun \
     -H "Authorization: Bearer ak_****" \
     -H "Content-Type: application/json" \
     -d '{ "snapshots": "reuse" }'

The snapshots field controls what the new run tests against:

ValueBehavior
reuseRe-run the same tasks, personas, and principles the original used. Use this to check whether a fix changed the outcome on identical scenarios.
refreshRe-fetch the entities' current state from the target before running. Use this after the target's content has changed and you want updated evaluations.
Response
{
  "evaluation": { "id": "b7f10...", "status": "queued" },
  "job": {
    "id": "job_cl4c7...",
    "status": "queued",
    "kind": "create_run",
    "resource": { "type": "evaluation", "id": "b7f10..." },
    "created_at": "2026-06-22T13:10:00Z"
  }
}

Keep the job.id, poll it to completion, then read the new evaluation's aggregates as you would for any launched evaluation.