# Reports API

The Reports API discovers available report definitions, runs them asynchronously, and downloads structured results or exports.

## Authorization

Every report declares its required Eos Roles and supported parameters. Role and field restrictions are evaluated again when the run executes, not only when it is created. A client may discover only definitions it is authorized to use.

## List and get report definitions

- `GET /v1/reports` — `listReports`
- `GET /v1/reports/{report_id}` — `getReport`

```json
{
  "object": "report_definition",
  "id": "rpt_project_margin",
  "name": "Project margin",
  "description": "Revenue, cost, and margin by project.",
  "required_roles": ["manager", "finance"],
  "parameters_schema": {
    "type": "object",
    "properties": {
      "from": {"type": "string", "format": "date"},
      "to": {"type": "string", "format": "date"}
    },
    "required": ["from", "to"]
  },
  "formats": ["json", "csv"]
}
```

## Run a report

`POST /v1/reports/{report_id}/runs`

Operation ID: `createReportRun`. Required header: `Idempotency-Key`.

```json
{
  "parameters": {"from": "2026-07-01", "to": "2026-07-31"},
  "format": "json"
}
```

Returns `202 Accepted` and a report-run resource with `queued`, `running`, `succeeded`, or `failed` status.

## Get status and results

- `GET /v1/reports/{report_id}/runs/{run_id}` — `getReportRun`
- `GET /v1/reports/{report_id}/runs/{run_id}/results` — `getReportResults`
- `POST /v1/reports/{report_id}/runs/{run_id}/download` — `createReportDownload`

JSON results are cursor-paginated. Download URLs are short-lived. Results expire at the `expires_at` timestamp returned with the run; clients should store any permitted long-term copy in their own controlled system.

## Data consistency

The run response includes `data_as_of`, timezone, and the report-definition version. Long reports may represent a snapshot rather than live data. A webhook can signal completion.

## Common errors

`REPORT_NOT_FOUND`, `REPORT_ROLE_REQUIRED`, `INVALID_REPORT_PARAMETERS`, `REPORT_RUN_NOT_FOUND`, `REPORT_RUN_EXPIRED`, `REPORT_FAILED`, and `EXPORT_FORMAT_NOT_SUPPORTED`.

Next: [Approvals API](approvals.html).