Fetching report data

Reporting access is scoped to your API key, not just your company. A key only sees reports that were granted to it when the key was created or edited, and it only sees report runs that it created. Another key in the same company with a different report selection sees a different report list; another key's run ID returns 404 (not 403).

The examples below reflect API version 2026-08-01 and later. Send one of those versions in the Easol-API-Version header, or ensure your API key is pinned to one — see Versioning.

Which reports your key can access

When an API key is created or updated in Easol admin (Settings → Developer Tools), the key form includes a checklist of published reports. Only checked reports are linked to the key and appear in GET /reports. There is no self-serve API to change this allowlist — update the key in admin, or ask someone with API access management permission to do it.

The Easol reporting API works in an asynchronous way where you first make a POST to create a ReportRun, in this post you can specify any filtering you want to apply to the output. You then can fetch the result of this run in a separate request as CSV or JSON.

Creating a report run

The first step in creating a ReportRun is finding the id of the Easol report you want to fetch the data for. You can do this by using the /reports endpoint

curl --request GET \
  --url https://api.myeasol.com/reports \
  --header 'Authorization: Bearer <token>'

This will respond with a list of all the reports available to you. The list is not paginated — every report your key can access is returned in one response (has_more is always false).

{
  "object": "list",
  "url": "/reports",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "id": "rpt_mR2nL5pW",
      "object": "report",
      "columns": {
        "object": "list",
        "url": null,
        "has_more": false,
        "next_cursor": null,
        "data": [
          {
            "id": "rptcol_9fKbV3aQ",
            "object": "report_column",
            "name": "ID",
            "type": "id"
          },
          {
            "id": "rptcol_2cLmN7xR",
            "object": "report_column",
            "name": "Booking reference",
            "type": "string"
          }
        ]
      },
      "filters": {
        "object": "list",
        "url": null,
        "has_more": false,
        "next_cursor": null,
        "data": []
      },
      "name": "Sales"
    }
  ]
}

In this output you can see the id for any corresponding report, these will match the reports you can see in the Easol backend.

Once you have the report id you're ready to create a report run. To do this you can use the /reports/{report_id}/runs endpoint. There's a number of parameters you can send to this endpoint for filtering your data:

For example, if we wanted to fetch sales data since 2024-08-06 that matches the term "Joe" we might make a request like:

curl --request POST \
  --url https://api.myeasol.com/reports/rpt_mR2nL5pW/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "search_query": "Joe",
  "interval_start": "2024-08-06T13:00:00Z"
}'

This will respond with a ReportRun object like:

{
  "id": "rptrun_8kLmN2pQ",
  "object": "report_run",
  "column_ids": [],
  "export_format": "csv",
  "filters": null,
  "interval_end": null,
  "interval_start": "2024-08-06T13:00:00+0000",
  "last_updated_since": null,
  "report": "rpt_mR2nL5pW",
  "result": null,
  "search_query": "Joe",
  "state": "pending"
}

Now we have this we can move onto fetching the result of that run.

Fetching the result of a report run

Now that we have a report run created we can use its id to check on the state of the report run and then fetch its data. Using the /reports/runs/{id} endpoint we can check on the state of a report. The state is one of pending, succeeded, or failed. Poll this endpoint until the state is no longer pending. When the run has succeeded, a result URL is available on the ReportRun; if it failed, there is no result to download.

{
  "id": "rptrun_8kLmN2pQ",
  "object": "report_run",
  "column_ids": [],
  "export_format": "csv",
  "filters": null,
  "interval_end": null,
  "interval_start": "2024-08-06T13:00:00+0000",
  "last_updated_since": null,
  "report": "rpt_mR2nL5pW",
  "result": "https://api.myeasol.com/reports/files/rptrun_8kLmN2pQ",
  "search_query": "Joe",
  "state": "succeeded"
}

That result property references a /reports/files/{id} endpoint which we can now use to fetch the results of our report.

curl --request GET \
  --url https://api.myeasol.com/reports/files/rptrun_8kLmN2pQ \
  --header 'Authorization: Bearer <token>'

The response body is the export file. CSV runs return application/csv; JSON runs return application/json. Set export_format when creating the run to choose the format (defaults to csv) — the format is fixed when the run is created, so an Accept header on the download does not change what you get.