# Reports

Source: https://www.ranked.ai/developers/api-reference/reports/list

`GET https://app.ranked.ai/api/v1/projects/{projectId}/reports`

> List or create shareable SEO report links

### GET - List reports

- `projectId` (path, string, required): Project UUID
- `limit` (query, number, default 50): Max reports to return
- `offset` (query, number, default 0): Number to skip

**Request**

```bash cURL
curl "https://app.ranked.ai/api/v1/projects/{projectId}/reports" \
  -H "Authorization: Bearer rk_live_your_api_key"
```

### POST - Create a report

Requires a **Read + Write** API key.

- `title` (body, string, required): Report title
- `date_range` (body, string, required): `7days`, `30days`, `90days`, or `custom`
- `custom_start_date` (body, string): Start date (ISO 8601). Required when `date_range` is `custom`.
- `custom_end_date` (body, string): End date (ISO 8601). Required when `date_range` is `custom`.
- `description` (body, string): Optional report description

**Request**

```bash Preset range
curl -X POST "https://app.ranked.ai/api/v1/projects/{projectId}/reports" \
  -H "Authorization: Bearer rk_live_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Monthly SEO Report",
    "date_range": "30days"
  }'
```

```bash Custom range
curl -X POST "https://app.ranked.ai/api/v1/projects/{projectId}/reports" \
  -H "Authorization: Bearer rk_live_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Q1 2026 Report",
    "date_range": "custom",
    "custom_start_date": "2026-01-01",
    "custom_end_date": "2026-03-31"
  }'
```