> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lucitra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

# Reports

Every completed validation run produces a report with scores across four dimensions, detailed findings in JSON, and optional annotated images highlighting detected issues.

## Scoring

Reports score your dataset from 0 to 100 on each dimension, plus an overall composite score.

<CardGroup cols={5}>
  <Card title="Overall" icon="star">
    Weighted composite of all dimension scores.
  </Card>

  <Card title="Coverage" icon="grid">
    Scenario and class coverage completeness.
  </Card>

  <Card title="Physics" icon="atom">
    Physical plausibility of the synthetic data.
  </Card>

  <Card title="Distribution" icon="chart-bar">
    Class balance and spatial distribution quality.
  </Card>

  <Card title="Sim-to-Real" icon="arrows-left-right">
    Domain gap relative to real-world reference data.
  </Card>
</CardGroup>

## Get a Report

Retrieve the full report for a completed validation run.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lucitra.io/v1/reports/rpt_8abc1234" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.lucitra.io/v1/reports/rpt_8abc1234",
      headers={"Authorization": "Bearer luci_your_api_key"},
  )
  report = resp.json()
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "id": "rpt_8abc1234",
    "run_id": "run_3fa85f64",
    "dataset_id": "ds_7kx9m2",
    "project_id": "proj_abc123",
    "overall_score": 82,
    "coverage_score": 91,
    "physics_score": 78,
    "distribution_score": 85,
    "sim_to_real_score": 74,
    "report_json": {
      "coverage": { "missing_classes": ["bicycle"], "edge_case_gaps": ["heavy_snow"] },
      "physics": { "violations": [{ "scene_id": "scene_042", "type": "intersection", "severity": "high" }] },
      "distribution": { "skewed_classes": ["pedestrian"], "gini_coefficient": 0.31 },
      "sim_to_real": { "fid_score": 42.7, "top_gaps": ["texture_quality", "shadow_direction"] }
    },
    "artifacts_path": "gs://lucitra-reports/proj_abc123/rpt_8abc1234/",
    "annotated_images": ["scene_042_physics", "scene_118_coverage"],
    "created_at": "2026-03-06T12:15:00Z"
  }
  ```

  <ResponseField name="id" type="string" required>
    Unique report identifier.
  </ResponseField>

  <ResponseField name="run_id" type="string" required>
    The validation run that produced this report.
  </ResponseField>

  <ResponseField name="dataset_id" type="string" required>
    The dataset that was validated.
  </ResponseField>

  <ResponseField name="project_id" type="string" required>
    The project this report belongs to.
  </ResponseField>

  <ResponseField name="overall_score" type="integer" required>
    Composite score from 0 to 100.
  </ResponseField>

  <ResponseField name="coverage_score" type="integer" required>
    Coverage dimension score from 0 to 100.
  </ResponseField>

  <ResponseField name="physics_score" type="integer" required>
    Physics plausibility score from 0 to 100.
  </ResponseField>

  <ResponseField name="distribution_score" type="integer" required>
    Distribution quality score from 0 to 100.
  </ResponseField>

  <ResponseField name="sim_to_real_score" type="integer">
    Sim-to-real gap score from 0 to 100. Null if no reference dataset was provided.
  </ResponseField>

  <ResponseField name="report_json" type="object" required>
    Detailed findings for each validation dimension.
  </ResponseField>

  <ResponseField name="artifacts_path" type="string" required>
    GCS path where report artifacts are stored.
  </ResponseField>

  <ResponseField name="annotated_images" type="array" required>
    List of image keys available for download via the images endpoint.
  </ResponseField>

  <ResponseField name="created_at" type="string" required>
    ISO 8601 timestamp of report generation.
  </ResponseField>
</Accordion>

## Export as PDF

Download a formatted PDF version of the report suitable for sharing with stakeholders or attaching to compliance documentation.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lucitra.io/v1/reports/rpt_8abc1234/pdf" \
    -H "Authorization: Bearer luci_your_api_key" \
    -o report.pdf
  ```

  ```python Python theme={null}
  resp = requests.get(
      "https://api.lucitra.io/v1/reports/rpt_8abc1234/pdf",
      headers={"Authorization": "Bearer luci_your_api_key"},
  )

  with open("report.pdf", "wb") as f:
      f.write(resp.content)
  ```
</CodeGroup>

<Note>
  The PDF endpoint returns a binary stream with `Content-Type: application/pdf`. Use the `-o` flag in cURL or write the response content as bytes in your client.
</Note>

## Annotated Images

Retrieve annotated images that highlight specific issues found during validation. The endpoint returns a **307 redirect** to a time-limited signed GCS URL.

<CodeGroup>
  ```bash cURL theme={null}
  curl -L "https://api.lucitra.io/v1/reports/rpt_8abc1234/images/scene_042_physics" \
    -H "Authorization: Bearer luci_your_api_key" \
    -o annotated_scene_042.png
  ```

  ```python Python theme={null}
  resp = requests.get(
      "https://api.lucitra.io/v1/reports/rpt_8abc1234/images/scene_042_physics",
      headers={"Authorization": "Bearer luci_your_api_key"},
      allow_redirects=True,
  )

  with open("annotated_scene_042.png", "wb") as f:
      f.write(resp.content)
  ```
</CodeGroup>

<Tip>
  The `annotated_images` array in the report response lists all available image keys. Use these keys in the URL path to download each image.
</Tip>

## Score Trends

Track how validation scores change over time across multiple runs within a project. Use this to monitor data quality regressions or improvements across retraining cycles.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lucitra.io/v1/projects/proj_abc123/trends?metric=overall&since=2026-01-01&until=2026-03-06" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```python Python theme={null}
  resp = requests.get(
      "https://api.lucitra.io/v1/projects/proj_abc123/trends",
      headers={"Authorization": "Bearer luci_your_api_key"},
      params={
          "metric": "overall",
          "since": "2026-01-01",
          "until": "2026-03-06",
      },
  )
  trends = resp.json()
  ```
</CodeGroup>

<ParamField query="metric" type="string" required>
  The score dimension to query. One of `overall`, `coverage`, `physics`, `distribution`, or `sim_to_real`.
</ParamField>

<ParamField query="since" type="string" required>
  Start date in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="until" type="string" required>
  End date in `YYYY-MM-DD` format.
</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "data_points": [
      { "date": "2026-01-15", "score": 68, "run_id": "run_aaa111" },
      { "date": "2026-02-01", "score": 74, "run_id": "run_bbb222" },
      { "date": "2026-02-20", "score": 79, "run_id": "run_ccc333" },
      { "date": "2026-03-05", "score": 82, "run_id": "run_3fa85f64" }
    ]
  }
  ```

  <ResponseField name="data_points" type="array" required>
    Ordered list of score data points within the requested time range.
  </ResponseField>

  <ResponseField name="data_points[].date" type="string" required>
    Date of the validation run.
  </ResponseField>

  <ResponseField name="data_points[].score" type="integer" required>
    Score value for the requested metric (0-100).
  </ResponseField>

  <ResponseField name="data_points[].run_id" type="string" required>
    The validation run that produced this data point.
  </ResponseField>
</Accordion>

<Info>
  Trends are available for all five metrics: `overall`, `coverage`, `physics`, `distribution`, and `sim_to_real`. Query each separately or build a multi-metric dashboard by making parallel requests.
</Info>