> This page is for version 2025-11-27 (default).
> For other versions, use one of these documentation indexes:
> - 2025-11-27 (default): https://docs.caesar.xyz/2025-11-27/llms.txt
> - 2025-08-08: https://docs.caesar.xyz/2025-08-08/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.caesar.xyz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.caesar.xyz/_mcp/server.

# Pagination

The Caesar API uses **page-based pagination** to handle large result sets efficiently. All list endpoints follow a consistent pagination pattern that makes it easy to retrieve results page by page.

## How it works

When requesting data from list endpoints, you can control the amount of data returned using two simple parameters:

* **`page`**: Which page of results to retrieve (starts at 1)
* **`limit`**: How many items per page (1-200, default is 10)

## Supported endpoints

Pagination is available on the following endpoints:

**`GET /research`**

```bash GET /research
GET /research?page=1&limit=25
```

**`GET /research/files`**

```bash GET /research/files
GET /research/files?page=2&limit=50
```

## Request parameters

**`page`** `integer` — default: 1

The page number to retrieve (1-based indexing).

* **Default**: 1
* **Minimum**: 1
* **Example**: `page=3` retrieves the third page of results

---

**`limit`** `integer` — default: 10

The number of items to return per page.

* **Default**: 10
* **Range**: 1–200
* **Example**: `limit=25` returns 25 items per page

---

> **Note**
>
> **Tip:** Start with the default values and adjust based on your needs. Larger page sizes mean fewer API calls but larger response payloads.

## Response format

All paginated responses return your data wrapped in a consistent structure:

```json
{
  "data": [...],      // Your requested items
  "pagination": {     // Metadata about the current page
    "page": 1,
    "limit": 10,
    "has_next": true
  }
}
```

### Understanding the response

#### The `data` field

Contains an array of the items for the current page. If you request a page beyond the available data, this returns an empty array.

#### The `pagination` field

Provides context about where you are in the result set:

| Field      | Type    | Description                      |
| ---------- | ------- | -------------------------------- |
| `page`     | integer | Current page number (1-based)    |
| `limit`    | integer | Number of items per page         |
| `has_next` | boolean | Whether more pages are available |

### Response (200)

```json
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "created_at": "2024-01-15T09:30:00Z",
      "status": "queued",
      "query": "Impact of renewable energy adoption on global carbon emissions",
      "reasoning_loops_consumed": 2,
      "running_time": 45,
      "results": [
        {
          "id": "1e4d5f7a-8b3c-4d2a-9f7e-123456789abc",
          "title": "Renewable Energy and Carbon Emissions: A Comprehensive Review",
          "url": "https://www.sciencedirect.com/science/article/pii/S1364032120301234",
          "citation_index": 1
        }
      ],
      "content": null,
      "transformed_content": null
    }
  ],
  "pagination": {
    "limit": 10,
    "page": 1,
    "has_next": true,
    "total": 25
  }
}
```

## Error handling

### Common errors

| Error         | Status | Cause                        | Solution                           |
| ------------- | ------ | ---------------------------- | ---------------------------------- |
| Invalid page  | 400    | `page < 1`                   | Use page ≥ 1                       |
| Invalid limit | 400    | `limit < 1` or `limit > 200` | Use limit between 1-200            |
| Invalid type  | 400    | Non-integer values           | Ensure page and limit are integers |

### Example error response

```json
{
  "error": {
    "code": "INVALID_PAGINATION",
    "message": "Invalid pagination parameters: page must be >= 1",
    "details": {
      "page": 0,
      "limit": 10
    }
  }
}
```