---
title: "List Reports"
method: GET
path: "/api/v1/custom-reports"
tags: ["Custom Reports", "Public API"]
---

# List Reports

`GET /api/v1/custom-reports`

Returns a paginated list of saved custom reports available in the account. Each report entry contains an `id` (integer) and a `name` (string). Pass a report's `id` to "Get Report by ID" to execute it and retrieve its data.

Results default to page 1 with 500 records per page (maximum 1000). Out-of-range page numbers are clamped to the nearest valid page rather than returning an error. Invalid or zero values for `page` and `page_size` fall back to their defaults.

The `pagination` object includes `total_records`, `current_page`, `total_pages`, and nullable `next_page`/`prev_page` links. When there is no next or previous page the corresponding value is `null`.

OAuth Scopes: report

## Query parameters

- `page` integer
- `page_size` integer

## Response `200`

Returns an object containing a `reports` array of report objects and a `pagination` object with page navigation metadata.

- ReportsResponse
  - `reports` Report[]
    - `id` integer
    - `name` string
  - `pagination` Pagination
    - `total_records` integer
    - `current_page` integer
    - `total_pages` integer
    - `next_page` string, nullable
    - `prev_page` string, nullable

## Other responses

- `403` — The caller is not authorized to access reports, or the required feature toggle is not enabled for this account.
- `500` — An unexpected error occurred while retrieving the list of reports.

---

[API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)