Skip to main content

Query your executions

An execution is a single graded conversation an evaluation produces.

note

Executions are scoped to a target, not to an evaluation. While this may sound counterintuitive, it enables a larger set of querying capabilities: query by status, task, persona, principle, etc., and, of course, by evaluation.

List the executions for an evaluation

Call GET /api/v1/targets/{targetId}/executions and pass the evaluation_id you got back when you launched the evaluation:

Request
curl "https://spectral.principled.app/api/v1/targets/9f8c2.../executions?evaluation_id=7c4d9...&limit=20" \
     -H "Authorization: Bearer ak_****"

The response is a paginated list of executions. Each carries the status, the task and persona that drove the conversation, and the per-turn outcomes:

Response
{
  "data": [
    {
      "id": "a1b2c...",
      "evaluation_id": "7c4d9...",
      "status": "succeeded",
      "task": { "id": "1f2e3...", "name": "Ask how long the refund window is" },
      "persona": { "id": "d4e5f...", "name": "Frustrated repeat customer" },
      "created_at": "2026-06-22T12:01:10Z",
      "started_at": "2026-06-22T12:01:12Z",
      "ended_at": "2026-06-22T12:03:48Z",
      "outcomes": [
        { "type": "factuality", "turn": 3, "decision": false, "severity": 4 }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "eyJjI..."
}
FieldDescription
idThe execution id. Pass it to the detail endpoint below.
statusOne of queued, running, succeeded, or failed.
task / personaThe scenario and persona that drove the conversation (id and name), or null.
outcomesPer-turn results. Each has a type (such as factuality or compliance), the turn it applies to, and, where relevant, a decision and a severity from 1 (low) to 5 (critical).
created_at / started_at / ended_atLifecycle timestamps; the last two are null until the conversation runs.
warning

This list endpoint omits the conversation transcript and the full report of each execution.

Narrow the list with filters

Pass the filters you need as query parameters to get just the executions you care about.

ParameterDescription
evaluation_idOnly executions from this evaluation.
statusOnly executions in this state (queued, running, succeeded, failed).
task_idOnly executions that ran this task.
persona_idOnly executions driven by this persona.
principle_idOnly executions judged against this principle.
created_after / created_beforeTime-box the results. RFC 3339 timestamps; created_after is inclusive, created_before is exclusive.

Read a single execution in full

To see the transcript and the findings, fetch one execution by id with GET /api/v1/targets/{targetId}/executions/{executionId}:

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

The detail response includes everything from the list, plus the conversation and the graded report:

Response
{
  "id": "a1b2c...",
  "evaluation_id": "7c4d9...",
  "status": "succeeded",
  "task": { "id": "1f2e3...", "name": "Ask how long the refund window is" },
  "persona": { "id": "d4e5f...", "name": "Frustrated repeat customer" },
  "created_at": "2026-06-22T12:01:10Z",
  "started_at": "2026-06-22T12:01:12Z",
  "ended_at": "2026-06-22T12:03:48Z",
  "outcomes": [
    { "type": "factuality", "turn": 3, "decision": false, "severity": 4 }
  ],
  "messages": [
    { "role": "user", "content": "How long do I have to return a parcel for a refund?" },
    { "role": "assistant", "content": "No problem — you can request a refund any time within 60 days of delivery." },
    { "role": "user", "content": "Great, mine was delivered 45 days ago, so I'm still covered?" },
    { "role": "assistant", "content": "Yes, 45 days is well within the window. I'll start the refund now." }
  ],
  "report": {
    "turns": 4,
    "severity_counts": { "4": 1 },
    "classifications": [
      {
        "type": "factuality",
        "turn": 3,
        "decision": false,
        "severity": 4,
        "explanation": "The assistant stated the refund window is 60 days. The knowledge base specifies 30 days, so the 45-day case is not eligible."
      }
    ]
  },
  "principles": []
}
FieldDescription
messagesThe full transcript. Each message has a role (user, assistant, or system) and content.
report.turnsHow many turns the conversation ran.
report.severity_countsFindings in this conversation, keyed by severity level 1–5.
report.classificationsThe per-turn judgments. Each carries the type, the turn, a boolean decision (false means the turn failed), a severity, and an explanation. Compliance classifications also include per-principle assessments.
principlesThe principles this execution was judged against, when the evaluation used any.