---
title: "Get Report by ID"
method: GET
path: "/api/v1/custom-reports/{reportId}"
tags: ["Custom Reports", "Public API"]
---

# Get Report by ID

`GET /api/v1/custom-reports/{reportId}`

Executes a saved custom report and returns its data using the report's configured fields and filters. The `data` array contains employee record objects whose keys are determined by the fields selected when the report was created — each object is a flat key-value map where keys are field names (e.g. `firstName`, `status`, `hireDate`) and values are strings or `null`. The `aggregations` array is empty unless the report's underlying dataset configuration includes aggregation rules. Use "List Reports" to discover available report IDs.

Response shape: Each element of `data` is a flat key-value object — field values are top-level keys (e.g. `row["firstName"]`). This differs from `get-data-from-dataset-v2`, where field values are nested under a `fields` key (e.g. `row["fields"]["firstName"]`).

There is no schema-only response from this endpoint.

The `pagination.total_records` value is the number of rows produced by the saved report after applying the report's configured filters, not necessarily the total number of employees in the account. Validate output before using in automated pipelines.

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

OAuth Scopes: report

## Path parameters

- `reportId` integer, required

## Query parameters

- `page` integer
- `page_size` integer

## Response `200`

Paginated report data with dynamic employee fields based on the report's configuration.

- EmployeeResponse
  - `data` DatasetEmployee[]
  - `aggregations` object[]
    - `field` string
    - `aggregationType` string
    - `groups` object
    - `all` integer
  - `pagination` Pagination
    - `total_records` integer
    - `current_page` integer
    - `total_pages` integer
    - `next_page` string, nullable
    - `prev_page` string, nullable

## Other responses

- `400` — Invalid or missing argument(s). Returned when the request fails validation or contains a type error.
- `403` — Access denied. The caller does not have permission to view this report.
- `404` — Report not found. No saved custom report exists with the given ID.
- `500` — An unexpected error occurred while retrieving the report.

---

[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)