Skip to main content

Create and export a report

A report is a shareable summary of an evaluation's findings, curated from a set of executions. Create one from an evaluation or from a specific set of executions, then download it as a PDF.

Create a report​

POST to the target's reports sub-path. The body's type selects where the report draws its executions from:

Roll up every succeeded execution in an evaluation. Pass its evaluation_id:

Request
curl -X POST https://spectral.principled.app/api/v1/targets/9f8c2.../reports \
     -H "Authorization: Bearer ak_****" \
     -H "Content-Type: application/json" \
     -d '{
       "type": "from_evaluation",
       "evaluation_id": "7c4d9...",
       "name": "Q2 refund-policy audit"
     }'

A 201 returns the new report together with the job that builds it:

Response
{
  "report": {
    "id": "r3p0rt...",
    "name": "Q2 refund-policy audit",
    "status": "queued",
    "target_name": "Support Assistant",
    "execution_ids": [],
    "created_at": "2026-06-23T09:00:00Z",
    "updated_at": "2026-06-23T09:00:00Z"
  },
  "job": {
    "id": "job_rep5c...",
    "status": "queued",
    "kind": "build_report",
    "resource": { "type": "report", "id": "r3p0rt..." },
    "created_at": "2026-06-23T09:00:00Z"
  }
}

The report exists, but its status is queued: it is assembled in the background. Poll the job with GET /api/v1/jobs/{job_id} until it succeeds (see Async jobs); the report's status is then succeeded and it is ready to export.

tip

To combine executions from more than one source in a single report, use "type": "based_on" with a list of sources. See the API reference for the full shape.

Download a PDF​

POST to the report's pdf sub-path. The body selects which sections to include; the response is the PDF itself (application/pdf), so write it straight to a file:

Request
curl -X POST \
     https://spectral.principled.app/api/v1/targets/9f8c2.../reports/r3p0rt.../pdf \
     -H "Authorization: Bearer ak_****" \
     -H "Content-Type: application/json" \
     -d '{
       "include_executions": true,
       "include_tasks": true,
       "include_principles": true,
       "include_personas": false
     }' \
     --output support-assistant-report.pdf
FieldSection
include_executionsThe individual graded conversations.
include_tasksThe scenarios that were run.
include_principlesThe principles the conversations were judged against.
include_personasThe personas that drove the conversations.

Each flag defaults to false, so pass the sections you want. The findings summary is always included.

Rename or re-describe a report​

Send a PATCH with the fields you want to change. Both name and description are optional; omit a field to leave it as is:

Request
curl -X PATCH \
     https://spectral.principled.app/api/v1/targets/9f8c2.../reports/r3p0rt... \
     -H "Authorization: Bearer ak_****" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Q2 refund-policy audit" }'

The response is the updated report:

Response
{
  "id": "r3p0rt...",
  "name": "Q2 refund-policy audit",
  "description": null,
  "status": "succeeded",
  "target_name": "Support Assistant",
  "execution_ids": ["a1b2c...", "e5f6g..."],
  "created_at": "2026-06-23T09:00:00Z",
  "updated_at": "2026-06-23T10:15:00Z"
}