> ## Documentation Index
> Fetch the complete documentation index at: https://docs.klayrai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

> Generate and retrieve AI-powered performance reports for your Meta Ads campaigns

# Reports

The Reports API lets you generate structured performance reports and retrieve them in JSON, PDF, or Markdown format. Reports combine campaign metrics with AI-generated analysis and recommendations.

***

## List reports

<api method="GET" path="/v1/reports" />

Retrieve a paginated list of generated reports.

### Query parameters

| Parameter    | Type      | Required | Default | Description                                                      |
| ------------ | --------- | -------- | ------- | ---------------------------------------------------------------- |
| `campaignId` | `string`  | No       | —       | Filter by campaign ID                                            |
| `accountId`  | `string`  | No       | —       | Filter by ad account ID                                          |
| `status`     | `string`  | No       | —       | Filter by status: `pending`, `generating`, `completed`, `failed` |
| `format`     | `string`  | No       | —       | Filter by format: `json`, `pdf`, `markdown`                      |
| `from`       | `string`  | No       | —       | Start date for report creation (ISO 8601)                        |
| `to`         | `string`  | No       | —       | End date for report creation (ISO 8601)                          |
| `page`       | `integer` | No       | `1`     | Page number                                                      |
| `page_size`  | `integer` | No       | `20`    | Results per page (max 100)                                       |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.klayrai.com/v1/reports?status=completed&page=1&page_size=10" \
    -H "x-api-key: klyr_live_abc123def456ghi789" \
    -H "klayrai-version: 2026-03-01"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    status: "completed",
    page: "1",
    page_size: "10",
  });

  const response = await fetch(
    `https://api.klayrai.com/v1/reports?${params}`,
    {
      headers: {
        "x-api-key": "klyr_live_abc123def456ghi789",
        "klayrai-version": "2026-03-01",
      },
    }
  );

  const data = await response.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": [
    {
      "id": "rpt_4m8n2k6p",
      "title": "Weekly Performance Report - Summer Sale 2026",
      "campaignIds": ["camp_abc123", "camp_def456"],
      "accountId": "act_001",
      "status": "completed",
      "format": "pdf",
      "dateRange": {
        "from": "2026-03-03",
        "to": "2026-03-10"
      },
      "summary": {
        "totalSpend": 3400.50,
        "totalConversions": 231,
        "avgCpa": 14.72,
        "avgRoas": 3.2,
        "overallRiskLevel": "MEDIUM"
      },
      "downloadUrl": "https://api.klayrai.com/v1/reports/rpt_4m8n2k6p/download",
      "expiresAt": "2026-03-17T14:00:00Z",
      "createdAt": "2026-03-10T14:00:00Z",
      "completedAt": "2026-03-10T14:00:12Z"
    }
  ],
  "pagination": {
    "total": 8,
    "page": 1,
    "page_size": 10,
    "hasMore": false
  }
}
```

***

## Generate a report

<api method="POST" path="/v1/reports" />

Trigger the generation of a new performance report. Reports are generated asynchronously and typically take 10-20 seconds.

### Request body

| Parameter    | Type     | Required | Description                       |
| ------------ | -------- | -------- | --------------------------------- |
| `account_id` | `string` | Yes      | The Meta ad account ID            |
| `title`      | `string` | Yes      | Report title                      |
| `date_start` | `string` | Yes      | Start date in `YYYY-MM-DD` format |
| `date_end`   | `string` | Yes      | End date in `YYYY-MM-DD` format   |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.klayrai.com/v1/reports" \
    -H "x-api-key: klyr_live_abc123def456ghi789" \
    -H "klayrai-version: 2026-03-01" \
    -H "Content-Type: application/json" \
    -d '{
      "account_id": "act_123456789",
      "title": "Weekly Performance Report - Summer Sale 2026",
      "date_start": "2026-03-03",
      "date_end": "2026-03-10"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.klayrai.com/v1/reports",
    {
      method: "POST",
      headers: {
        "x-api-key": "klyr_live_abc123def456ghi789",
        "klayrai-version": "2026-03-01",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        account_id: "act_123456789",
        title: "Weekly Performance Report - Summer Sale 2026",
        date_start: "2026-03-03",
        date_end: "2026-03-10",
      }),
    }
  );

  const data = await response.json();
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": {
    "id": "rpt_7j3k9m1n",
    "title": "Weekly Performance Report - Summer Sale 2026",
    "accountId": "act_123456789",
    "status": "generating",
    "dateRange": {
      "from": "2026-03-03",
      "to": "2026-03-10"
    },
    "createdAt": "2026-03-10T15:00:00Z",
    "estimatedCompletionSeconds": 15
  }
}
```

<Note>
  Poll `GET /v1/reports` to check for completion. The `downloadUrl` field will be populated once the report status is `completed`.
</Note>

***

## Download a report

The `downloadUrl` returned on completed reports is a signed URL valid for 7 days. Send a GET request to download the file directly:

```bash theme={null}
curl -o report.pdf "https://api.klayrai.com/v1/reports/rpt_4m8n2k6p/download" \
  -H "x-api-key: klyr_live_abc123def456ghi789"
```

***

## Error codes

| Status | Code                        | Description                          |
| ------ | --------------------------- | ------------------------------------ |
| `400`  | `invalid_request`           | Missing or invalid parameters        |
| `400`  | `too_many_campaigns`        | More than 20 campaign IDs provided   |
| `401`  | `authentication_error`      | Invalid or missing API key           |
| `403`  | `plan_insufficient`         | API access requires the Agency plan  |
| `403`  | `white_label_not_available` | White-label requires the Agency plan |
| `404`  | `not_found`                 | One or more campaign IDs not found   |
| `429`  | `rate_limit_error`          | Rate limit exceeded                  |
| `500`  | `api_error`                 | Internal server error                |