# GET /api/v1/reports

> List reports

- **Tag:** reports
- **Operation ID:** `list_reports_api_v1_reports_get`

## Description

Retrieve all reports for a business with pagination.

## Authentication

Bearer token in `Authorization` header.
Required header: `x-business-id: <business uuid>`.

## Parameters

- `client_visible_only` (query, boolean, optional)
- `cursor` (query, string, optional) — Cursor for pagination
- `limit` (query, integer, optional) — Pagination limit
- `direction` (query, string, optional) — Pagination direction: 'next' or 'prev'
- `include_total_count` (query, boolean, optional) — Whether to include total count (expensive - avoid if possible)
- `sort_by` (query, string, optional) — Column name to sort by (e.g. 'created_at', 'amount', 'name'). When changing sort, reset cursor to None.
- `descending` (query, boolean, optional) — Sort direction: true for descending (newest/largest first), false for ascending

## Responses

### 200 — Successful Response

Schema: `ReportsListResponse`

- `items` (array · ReportResponse · required) → `ReportResponse` — List of items
  - `id` (string · required) — Unique identifier for this generated report. Use this ID to retrieve the report details or delete it. Example: '019ab37c-rpt1-7000-8000-000000000001'.
  - `business_id` (string · required) — UUID of the business this report belongs to. Reports are scoped to a single business and cannot be accessed by other businesses.
  - `report_name` (string · required) — The report type that was generated. Matches the report_name from the original request. Example: 'profit_and_loss', 'master_transactions', 'ar_report'.
  - `created_at` (string · date-time · required) — Timestamp when the report was generated (ISO 8601 format). Example: '2026-01-15T14:00:00Z'.
  - `downloaded_at` (string · date-time · required) — Timestamp of the most recent download of this report. Updated each time the report is accessed. Useful for tracking report usage.
  - `s3_bucket` (string · required) — Name of the S3 bucket where the report file is stored. Format: 'dayzero-{environment}-reports'. Example: 'dayzero-prod-reports'.
  - `s3_key` (string · required) — S3 object key (path) for the report file within the bucket. Format: 'reports/{business_id}/{report_type}_{dates}.xlsx'. Example: 'reports/019ab37c-bus1/master_transactions_2026-01-01_2026-12-31.xlsx'.
  - `generation_params` (object) — Dictionary of all parameters used to generate this report. Includes resolved dates (even when using tax_year/tax_quarter), filters, and any additional parameters. Useful for understanding report scope and audit purposes. Example: {'start_date': '2026-01-01', 'end_date': '2026-12-31', 'ledger_id': null}.
  - `download_url` (string · required) — Same-origin proxy URL for downloading the report file. Streams through the backend to avoid CORS and presigned-URL expiration issues. Requires Authorization and x-business-id headers.
  - `generated_by_name` (string) — Display name of the user who generated this report, e.g. 'Sarah Chen'. Extracted from generation_params.
- `total` (integer) — Total number of items (null when not calculated for performance)
- `limit` (integer) — Pagination limit
- `next_cursor` (string) — Cursor for next page
- `prev_cursor` (string) — Cursor for previous page
- `has_next` (boolean · required) — Whether there are more items
- `has_prev` (boolean · required) — Whether there are previous items

### 401 — Unauthorized - Authentication required

### 403 — Forbidden - Insufficient permissions

### 422 — Validation Error

Schema: `HTTPValidationError`

- `detail` (array · ValidationError) → `ValidationError`
  - `loc` (array · string | integer · required)
  - `msg` (string · required)
  - `type` (string · required)
  - `input` (object)
  - `ctx` (object)

## Code samples

### cURL

```bash
curl -X GET 'https://api.ondayzero.com/api/v1/reports' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID'
```

### JavaScript

```javascript
const response = await fetch('https://api.ondayzero.com/api/v1/reports', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer dz_your_token',
    'x-business-id': 'YOUR_BUSINESS_ID',
  },
});
const data = await response.json();
```

### Python

```python
import httpx

headers = {
    "Authorization": "Bearer dz_your_token",
    "x-business-id": "YOUR_BUSINESS_ID",
}

response = httpx.get("https://api.ondayzero.com/api/v1/reports", headers=headers)
data = response.json()
```

## See also

- HTML version: https://www.ondayzero.com/docs/reference/reports/list-reports
- OpenAPI slice: https://www.ondayzero.com/docs/reference/reports/list-reports/openapi.json
- Other endpoints in **reports**: https://www.ondayzero.com/docs/reference/reports