Operations
Teads Ad Manager Reporting API endpoints, statuses, and errors.
All operations use the base URL and Authorization header described in
Getting started. Rate limits: 1
call / 30 seconds on the two run endpoints, 1 call / 5 seconds on
every other endpoint, applied per seat. See Quotas and limits
for full details on rate limits and the rolling 24-hour run quota.
Endpoint map
| Method | Path | Role |
|---|---|---|
POST | /api/reports/run | Run a one-time report |
GET | /api/reports/status/:uid | Run status and download uri |
GET | /api/reports/mine | List saved reports |
GET | /api/reports/:id | Saved report details |
GET | /api/reports/:id/files | All generated files |
GET | /api/reports/:id/latest-file | Latest generated file |
POST | /api/reports/:id/run | Run a saved report |
GET | /api/reports/quotas | Rolling 24-hour used / total |
:id is the numeric TAM report id. :uid is the UUID returned by a run.
Run a one-time report
POST /api/reports/run
| Field | Type | Description |
|---|---|---|
filters | object | Report filters. date (start, end, optional timezone) is required. |
dimensions | string[] | Dimension API names. At least one. |
metrics | string[] | Metric API names. At least one. |
format | string | csv (default) or xlsx. |
callbackUrl | URL | Optional. TAM POSTs { "reportUid": "", "uri": "http://..." } on finish. |
Success 200 returns a run object. Errors:
| Status | Meaning |
|---|---|
401 | Missing authorization header, or no valid token found |
400 | Invalid JSON, or required parameters missing (need a dimension and a metric) |
429 | User reached the API quota (CURRENT_QUOTAS / TOTAL) |
Get status of a run
GET /api/reports/status/:uid
Success 200 is the run object plus uri when status is finished.
Errors: 401 missing or invalid token.
Poll about every 10 seconds. The official Python example times out after 6 hours.
Run a saved report
POST /api/reports/:id/run
No JSON body. Success 200 returns a run object. Errors: 401, 403
(cannot access the report), 429 (quota).
Then poll status and download from uri.
List saved reports
GET /api/reports/mine
Optional query page (0-indexed) when results are paginated.
| Field | Type | Description |
|---|---|---|
content | object[] | Saved reports |
content.id | number | Report id |
content.idProfile | number | Profile that created the report |
content.idEntityOwner | number | Organization id |
content.name | string | Report name |
content.json | object | Stored settings |
content.json.filters | object | Filters |
content.json.dimensions | string[] | Dimensions |
content.json.metrics | string[] | Metrics |
page.currentPage | number | Current page |
page.size | number | Results per page |
page.totalElements | number | Total results across pages |
page.totalPages | number | Total pages |
Errors: 401.
Get saved report details
GET /api/reports/:id
Same report fields as a content[] item (id, idProfile,
idEntityOwner, name, json). Errors: 401, 403.
List files for a saved report
GET /api/reports/:id/files
| Field | Type | Description |
|---|---|---|
response | object[] | Generated files |
url | URL | Public download URL |
LastModified | ISO 8601 | When the file was generated |
Size | number | File size |
name | string | File name |
Errors: 401, 403.
Get latest file for a saved report
GET /api/reports/:id/latest-file
Same file fields (url, LastModified, Size, name) for the most recent
file. Use this for scheduled reports. Errors: 401, 403.
Get quotas
GET /api/reports/quotas
| Field | Type | Description |
|---|---|---|
used | number | Reports that ran in the past 24 hours |
total | number | Reports allowed per 24-hour period (default 75) |
next_available_slot | epoch millis | When the next run is allowed; current time if the quota is not yet reached |
Errors: 401.
Run object
Returned by both run endpoints and by status.
| Field | Type | Description |
|---|---|---|
id | UUID | Run id |
start | ISO 8601 | When the request was registered |
lastStatusUpdate | ISO 8601 | Last internal status update |
status | string | queued, processing, error, or finished |
valid | boolean | Whether the request format and content are valid |
uri | URL | Download URL; only when status is finished |
reportProgress | object | Progress counters |
reportProgress.stepMax | number | Steps to finish |
reportProgress.step | number | Current step |
reportProgress.progressMax | number | Max progress for the step |
reportProgress.progress | number | Current progress in the step |
The one-time-report article mentions a url field on finished. The status
endpoint and Python example use uri. Saved-report file endpoints use
url.
Status lifecycle
queued → processing → finished
↘ errorqueued: accepted; waiting for capacity.processing: computing.error: failed; inspectmessage.finished: ready. Download fromuri(status) orurl(saved-report files).