Eos Developers
Design target — not live yet. This documentation defines the contract Eos will implement. Existing internal application APIs are not part of this contract.

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
{
  "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.

{
  "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.