---
title: Reports
description: Retrieve generated reports and download their files.
---

# Reports

Retrieve generated reports and download their files.

## [GET /reports](/api-reference/reports#tag/reports/GET/reports)

List reports

List platform-generated report runs for a given report key, newest first.

Only report runs created within the last 30 days are returned.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Query parameters

- `reportKey` (`string`, required) — The key identifying the report to list runs for.
- `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return.
- `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor.

### Responses

#### 200

A list of report runs.

Type: `object`

- `items` (`array of ReportRun`, required)
  - `reportRunId` (`string`, required, uuid, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The unique identifier for this report run.
  - `reportKey` (`string`, required, example subscriber_base_and_revenue) — Identifies which report was generated.
  - `status` (`enum<string>`, required, one of QUEUED, RUNNING, SUCCEEDED, FAILED) — The current stage of a report run in its lifecycle.
  - `downloadUrl` (`string | null`, required, uri, example https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=...) — A time-limited link to download the generated file. Present only once the report has succeeded; null while it is still generating or if it failed.
  - `createdAt` (`string`, required, date-time) — When the report run was requested.
  - `completedAt` (`string | null`, required, date-time) — When the report run finished generating. Null while it is still in progress.
- `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page.
  - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results.

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl 'https://apiv2.example.com/api/v2/reports?reportKey=REPORT_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

## [GET /reports/{reportRunId}](/api-reference/reports#tag/reports/GET/reports/{reportRunId})

Get report

Retrieve a generated report by its identifier. Once the report has finished generating, the response includes a time-limited link to download the file directly.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

- `reportRunId` (`string`, required, uuid) — The identifier of the report run.

### Responses

#### 200

A report run object.

Type: [ReportRun](/api-reference/models.md#models/ReportRun)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/reports/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
```