Reports API

Reports are generated asynchronously as background jobs. They produce HTML or PDF documents summarizing experiments, models, projects, deployments, or SynthGen runs. Reports can optionally include AI-generated insights.

---

Create Report

POST /api/reports

Create a report and enqueue a report_generate background job. The report starts in queued status and transitions to succeeded once the artifact is ready.

Request Body

Field	Type	Required	Description
project_id	string	Yes	UUID of the project.
kind	string	Yes	Report type: experiment, model, project, deployment, or synthgen.
entity_id	string	Yes	UUID of the entity to report on (the experiment, model, deployment, etc.).
options	object	No	Report customization (see below).

Options

Key	Type	Description
llm_insights	boolean	Include AI-generated commentary and recommendations. Default: false.
title	string	Custom title for the report.
comments	string	Free-form text added as a comments section.
include_metrics	boolean	Include performance metrics table. Default: true.
include_charts	boolean	Include visualizations (ROC curve, variable importance). Default: true.
include_hyperparameters	boolean	Include model hyperparameters. Default: true.
include_data_summary	boolean	Include dataset statistics. Default: true.

Example

curl -X POST "$BASE_URL/api/reports" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "d4e5f6a7-b8c9-0123-def4-567890123456",
    "kind": "experiment",
    "entity_id": "b8c9d0e1-f2a3-4567-8901-bcdef1234567",
    "options": {
      "llm_insights": true,
      "title": "Fraud Detection Model Report",
      "comments": "Q4 quarterly review"
    }
  }'

import requests
import time

# Create report
resp = requests.post(f"{BASE_URL}/api/reports", headers={
    "Authorization": "Bearer YOUR_API_KEY",
}, json={
    "project_id": "d4e5f6a7-b8c9-0123-def4-567890123456",
    "kind": "experiment",
    "entity_id": "b8c9d0e1-f2a3-4567-8901-bcdef1234567",
    "options": {"llm_insights": True},
})
report_id = resp.json()["report_id"]

# Poll until ready
while True:
    r = requests.get(f"{BASE_URL}/api/reports/{report_id}", headers={
        "Authorization": "Bearer YOUR_API_KEY",
    })
    status = r.json()["report"]["status"]
    if status in ("succeeded", "failed"):
        break
    time.sleep(5)

# Download the report
if status == "succeeded":
    dl = requests.get(f"{BASE_URL}/api/reports/{report_id}/download", headers={
        "Authorization": "Bearer YOUR_API_KEY",
    })
    with open("report.pdf", "wb") as f:
        f.write(dl.content)

Response 201 Created

{
  "report_id": "e1f2a3b4-c5d6-7890-1234-ef5678901234",
  "job_id": "f2a3b4c5-d6e7-8901-2345-f67890123456",
  "status": "queued"
}

Report Kinds

Kind	Entity	Description
experiment	Experiment ID	AutoML training summary: leaderboard, metrics, feature importance, model comparison charts.
model	Model ID	Individual model analysis: hyperparameters, performance metrics, feature importance, learning curves.
project	Project ID	Project overview: all experiments, datasets, models, and deployment status.
synthgen	SynthGen Job ID	Synthetic data quality: distribution comparison, correlation preservation, privacy metrics.
deployment	Deployment ID	Deployment health: prediction volume, latency, drift metrics, error rates.

Note

Privacy PDF reports are generated with GET /api/privacy/sessions/{session_id}/report (Privacy API), not via POST /api/reports.

Report Options

Options vary by report kind. Common options:

Option	Type	Description
llm_insights	boolean	Enable AI-powered recommendations using LLM analysis. Requires OPENAI_API_KEY configured on the server. Default false.
include_leaderboard	boolean	Include model leaderboard table (experiment reports).
include_feature_importance	boolean	Include feature importance charts (experiment/model reports).
include_confusion_matrix	boolean	Include confusion matrix (classification reports).
include_roc_curve	boolean	Include ROC curve chart (classification reports).
include_learning_curves	boolean	Include learning curve charts (model reports).

---

List Reports

GET /api/reports

Query Parameters

Parameter	Type	Default	Description
project_id	string	–	Required. Filter by project.
kind	string	–	Filter by report type.
entity_id	string	–	Filter by entity.
limit	integer	50	Max items (1–500).
offset	integer	0	Pagination offset.

Example

curl "$BASE_URL/api/reports?project_id=d4e5f6a7-b8c9-0123-def4-567890123456&kind=experiment" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "items": [
    {
      "id": "e1f2a3b4-c5d6-7890-1234-ef5678901234",
      "project_id": "d4e5f6a7-b8c9-0123-def4-567890123456",
      "kind": "experiment",
      "entity_id": "b8c9d0e1-f2a3-4567-8901-bcdef1234567",
      "status": "succeeded",
      "summary": {},
      "artifact_id": "a3b4c5d6-e7f8-9012-3456-789012345678",
      "created_at": "2026-02-28T15:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

---

Get Report Detail

GET /api/reports/{report_id}

Return the report metadata and associated job ID.

Example

curl "$BASE_URL/api/reports/e1f2a3b4-c5d6-7890-1234-ef5678901234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200 OK

{
  "report": {
    "id": "e1f2a3b4-c5d6-7890-1234-ef5678901234",
    "project_id": "d4e5f6a7-b8c9-0123-def4-567890123456",
    "kind": "experiment",
    "entity_id": "b8c9d0e1-f2a3-4567-8901-bcdef1234567",
    "status": "succeeded",
    "summary": {},
    "artifact_id": "a3b4c5d6-e7f8-9012-3456-789012345678",
    "job_id": "f2a3b4c5-d6e7-8901-2345-f67890123456"
  }
}

---

View Report Inline

GET /api/reports/{report_id}/view

View the report inline in the browser. Returns the rendered HTML or PDF with an inline Content-Disposition header. Suitable for embedding in an iframe.

Returns 409 Conflict if the report is still processing.

Example

# Open in browser
curl "$BASE_URL/api/reports/e1f2a3b4-c5d6-7890-1234-ef5678901234/view" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report_preview.html

Response 200 OK

Returns text/html or application/pdf depending on the report format.

---

Download Report

GET /api/reports/{report_id}/download

Download the report as an attachment (PDF or HTML file).

Returns 409 Conflict if the report is still processing.

Example

curl -o report.pdf \
  "$BASE_URL/api/reports/e1f2a3b4-c5d6-7890-1234-ef5678901234/download" \
  -H "Authorization: Bearer YOUR_API_KEY"

resp = requests.get(
    f"{BASE_URL}/api/reports/e1f2a3b4-c5d6-7890-1234-ef5678901234/download",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
with open("report.pdf", "wb") as f:
    f.write(resp.content)

Response 200 OK

Binary file download with Content-Disposition: attachment.

---

See also

• Experiments API – Experiment reports with model comparisons.

• Deployments API – Deployment performance reports.

• Privacy Suite API – Privacy session reports.