=========== 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. .. contents:: Endpoints :local: :depth: 1 ---- Create Report ------------- .. code-block:: text 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** .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - 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** .. list-table:: :header-rows: 1 :widths: 25 10 65 * - 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** .. code-block:: bash 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" } }' .. code-block:: python 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`` .. code-block:: json { "report_id": "e1f2a3b4-c5d6-7890-1234-ef5678901234", "job_id": "f2a3b4c5-d6e7-8901-2345-f67890123456", "status": "queued" } Report Kinds ^^^^^^^^^^^^ .. list-table:: :header-rows: 1 :widths: 20 20 60 * - 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: .. list-table:: :header-rows: 1 :widths: 30 15 55 * - 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 ------------ .. code-block:: text GET /api/reports **Query Parameters** .. list-table:: :header-rows: 1 :widths: 20 10 10 60 * - 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** .. code-block:: bash curl "$BASE_URL/api/reports?project_id=d4e5f6a7-b8c9-0123-def4-567890123456&kind=experiment" \ -H "Authorization: Bearer YOUR_API_KEY" **Response** ``200 OK`` .. code-block:: json { "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 ----------------- .. code-block:: text GET /api/reports/{report_id} Return the report metadata and associated job ID. **Example** .. code-block:: bash curl "$BASE_URL/api/reports/e1f2a3b4-c5d6-7890-1234-ef5678901234" \ -H "Authorization: Bearer YOUR_API_KEY" **Response** ``200 OK`` .. code-block:: json { "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 ------------------ .. code-block:: text 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** .. code-block:: bash # 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 --------------- .. code-block:: text 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** .. code-block:: bash curl -o report.pdf \ "$BASE_URL/api/reports/e1f2a3b4-c5d6-7890-1234-ef5678901234/download" \ -H "Authorization: Bearer YOUR_API_KEY" .. code-block:: python 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``. ---- .. seealso:: - :doc:`experiments` -- Experiment reports with model comparisons. - :doc:`deployments` -- Deployment performance reports. - :doc:`privacy` -- Privacy session reports.