# List reports

Returns a paginated list of reports available to the current API key, newest first. The response includes only report types the API key has access to. Results can briefly lag behind recent changes. To get the current state of a report, use get report.

Endpoint: POST /reports/list
Version: 2.0.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer asec_xxx

## Request fields (application/json):

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. Omitted when no pages remain.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `items` (array)
    List of reports for the current page.

  - `items.id` (string, required)
    Unique report identifier.
    Example: rprt_01K8F3ZQ8X9YBCDEFGHJKMNPQR

  - `items.report_type` (string, required)
    Report type.
The list of enum values may be extended without notice.
    Enum: "INVOICES", "SUBSCRIPTIONS", "TAX_TRANSACTIONAL", "INVOICE_PAYMENTS", "TAX_SUMMARY"

  - `items.status` (string, required)
    Current report status.
The list of enum values may be extended without notice.
    Enum: "PROCESSING", "SUCCEEDED", "FAILED", "EXPIRED"

  - `items.created_at` (string, required)
    Date and time when the report was created.
    Example: 2024-01-01T00:00:00.000000Z

  - `items.updated_at` (string, required)
    Date and time when the report was last updated.
    Example: 2024-01-01T00:10:00.000000Z

  - `items.parameters` (object, required)
    Parameters the report was created with.
    Example: {"channel_ids":["chn_01JYWX6Z5A8P32B6NVH1G9876A"],"date_from":"2024-01-01T00:00:00.000000Z","date_to":"2024-02-01T00:00:00.000000Z"}

  - `items.parameters.channel_ids` (array)
    Channels the report is limited to. Absent when the report covers the entire account.
    Example: ["chn_01JYWX6Z5A8P32B6NVH1G9876A"]

  - `items.parameters.date_from` (string, required)
    Start date and time for the report data range.
    Example: 2024-01-01T00:00:00.000000Z

  - `items.parameters.date_to` (string, required)
    End date and time for the report data range.
    Example: 2024-02-01T00:00:00.000000Z

  - `pagination` (object)
    Pagination details.

  - `pagination.page_size` (integer, required)
    Number of items returned in this response.
    Example: 20

  - `pagination.next_page_token` (string)
    Token to retrieve the next page of results. Omitted when no pages remain.
    Example: eyJMYXN0SUQiOiIxYTYyYjQ0Ni01ZDM0LTRiYTQtOGRlZS02NTM5NTU0NjY2MTQifQ==

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "VALIDATION"

  - `message` (string, required)
    Message describing the error.
    Example: One or more fields failed validation due to constraints

  - `context` (object, required)
    Additional context about the validation error, including specific constraints.
    Example: {"constraints":{"email":{"type":"TYPE","message":"The 'email' field must be a valid email address"},"age":{"type":"MIN","message":"The 'age' field must be a number greater than or equal to 18"}}}

  - `context.constraints` (object, required)
    Failed constraints keyed by the field name.

## Response 401:

  - `401` (unknown)
    Unauthenticated

## Response 401 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "UNAUTHENTICATED"

  - `message` (string, required)
    Message describing the error.
    Example: Credentials are invalid or missing

## Response 403:

  - `403` (unknown)
    Unauthorized

## Response 403 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "PERMISSION_DENIED"

  - `message` (string, required)
    Message describing the error.
    Example: Permission denied

## Response 429:

  - `429` (unknown)
    Too many requests

## Response 429 fields (application/json):

  - `code` (string, required)
    Code identifying the error type.
    Enum: "RATE_LIMIT"

  - `message` (string, required)
    Message describing the error.
    Example: Rate limit exhausted

  - `context` (object)
    Additional context about the error.

  - `context.next_try_at` (string)
    Timestamp indicating when to retry the request.
    Example: 2024-12-31T23:59:59.000000Z

