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:
- Choose a report type and read the parameters it takes.
- Create the report. It usually comes back as
PENDING, because reports are built in the background. - Poll the report until it is
COMPLETED, then download the file fromdownloadUrl.
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.comAuthentication
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_TOKENSee 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:
curl https://api2.sesamy.com/management/report-types \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"{
"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:
| Field | Type | Description |
|---|---|---|
name | string | The key to send the value under |
type | string | STRING, NUMBER, BOOLEAN, DATE (a YYYY-MM-DD string), or STRING_ARRAY (an array of strings) |
isRequired | boolean | Whether the report needs a value |
options | array or null | The values the parameter accepts, each with a value to send and a label to show. null when any value is fine |
default | any or null | What 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:
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" }
}'| Field | Type | Description |
|---|---|---|
typeId | string | The id of a report type |
parameters | object | Values 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 isPENDINGorPROCESSING. TheLocationheader is where to poll it.200 OK: the same report was already generated, and it isCOMPLETED.
{
"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.
curl https://api2.sesamy.com/management/reports/9b2c6f0e4d1a8b7c3e5f2a1d0c9b8a7e \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"| Status | Meaning |
|---|---|
PENDING | Waiting for a worker |
PROCESSING | Being generated |
COMPLETED | Ready: download the file from downloadUrl |
FAILED | Generation 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:
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:
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
- Authentication: get a Management API token
- API keys: how keys and their token URLs work
- Management API reference: every endpoint and field
- Rate limits: how often you can call the API
- Error handling: what the error responses mean