Skip to content

Generating Reports ​

Learn how to generate reports through the Management API, wait for them to finish, and download the file.

Overview ​

The Management API generates the same reports as the Reports page in the Sesamy portal: transactions, subscribers, churn, payouts, and more. Each report is a file, usually CSV, built from your data for the parameters you choose.

Generating a report takes three steps:

  1. Choose a report type and read the parameters it takes.
  2. Create the report. It usually comes back as PENDING, because reports are built in the background.
  3. Poll the report until it is COMPLETED, then download the file from downloadUrl.

Creating a report is safe to repeat

A report is identified by its type and parameters. Creating the same report twice returns the same report, so you can retry a request that timed out without generating it twice. A report that FAILED is run again when you create it again.

Base URL ​

https://api2.sesamy.com

Authentication ​

Every endpoint needs a Management API token with the reports:read scope. Request the token from https://token.sesamy.com/oauth/token with the client credentials flow, and send it as a bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

See Authentication for how to obtain a token.

API keys

An API key does not use the shared token URL: request its token from the tokenUrl returned when you created the key. The API key presets do not include reports:read yet. Contact Sesamy to have it enabled for your client.

Creating a report needs only reports:read, not a write scope: a report is built from data you can already read, and creating one changes nothing else.

Choose a Report Type ​

GET /management/report-types lists the reports you can generate:

bash
curl https://api2.sesamy.com/management/report-types \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
json
{
  "items": [
    {
      "id": "transactions_report",
      "name": "Transactions",
      "description": "Every transaction in the date range, with its currency and taxes.",
      "category": "Finance",
      "parameters": [
        {
          "name": "dateFrom",
          "label": "From date",
          "description": "The start date of the report in format YYYY-MM-DD",
          "type": "DATE",
          "isRequired": true,
          "options": null,
          "default": null
        },
        {
          "name": "dateTo",
          "label": "To date",
          "description": "The end date of the report in format YYYY-MM-DD",
          "type": "DATE",
          "isRequired": true,
          "options": null,
          "default": null
        }
      ]
    }
  ],
  "nextCursor": null
}

Each parameter tells you how to send it:

FieldTypeDescription
namestringThe key to send the value under
typestringSTRING, NUMBER, BOOLEAN, DATE (a YYYY-MM-DD string), or STRING_ARRAY (an array of strings)
isRequiredbooleanWhether the report needs a value
optionsarray or nullThe values the parameter accepts, each with a value to send and a label to show. null when any value is fine
defaultany or nullWhat the report uses when you leave the parameter out

GET /management/report-types/{id} returns one type with its documentation, where written: what the report answers, what one row of the file stands for, and what each column means.

Create a Report ​

POST /management/reports takes the type and the parameter values:

bash
curl -X POST https://api2.sesamy.com/management/reports \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "typeId": "transactions_report",
    "parameters": { "dateFrom": "2026-01-01", "dateTo": "2026-01-31" }
  }'
FieldTypeDescription
typeIdstringThe id of a report type
parametersobjectValues by parameter name. (Optional) Leave it out for a report that takes none

The response depends on whether the report is ready:

  • 202 Accepted: the report is PENDING or PROCESSING. The Location header is where to poll it.
  • 200 OK: the same report was already generated, and it is COMPLETED.
json
{
  "id": "9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e",
  "typeId": "transactions_report",
  "name": "Transactions",
  "status": "PENDING",
  "parameters": { "dateFrom": "2026-01-01", "dateTo": "2026-01-31" },
  "downloadUrl": null,
  "downloadUrlExpiresAt": null,
  "createdAt": "2026-02-01T07:58:12.000Z",
  "updatedAt": "2026-02-01T07:58:12.000Z"
}

A parameter the type does not take, a missing required one, or a value of the wrong type is refused with 400, and no report is created.

Wait for the Report ​

Poll GET /management/reports/{id} until status is COMPLETED. How long that takes depends on the report and on its date range.

bash
curl https://api2.sesamy.com/management/reports/9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
StatusMeaning
PENDINGWaiting for a worker
PROCESSINGBeing generated
COMPLETEDReady: download the file from downloadUrl
FAILEDGeneration failed. Create the report again to run it again

Polling interval

Poll every 10 to 30 seconds. Polling faster does not make the report finish sooner, and counts against your rate limits.

Download the File ​

A COMPLETED report has a downloadUrl. It is a temporary link that works without your token, so you can hand it to a browser or a download tool:

bash
curl -o transactions.csv "DOWNLOAD_URL"

The link expires

downloadUrl stops working at downloadUrlExpiresAt, about an hour after you read the report. Read the report again for a fresh link. Don't store the link; store the report id.

List Reports ​

GET /management/reports lists the reports you have generated, most recently updated first. Filter on a type with typeId:

bash
curl "https://api2.sesamy.com/management/reports?typeId=transactions_report" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response is { "items": [...], "nextCursor": null }. Every report is returned at once, so nextCursor is always null.

Next Steps ​

Released under the MIT License.