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?page=1&limit=25

Request parameters

Response format

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

1
{
2
  "data": [...],      // Your requested items
3
  "pagination": {     // Metadata about the current page
4
    "page": 1,
5
    "limit": 10,
6
    "has_next": true
7
  }
8
}

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:

1
{
2
  "data": [
3
    {
4
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
5
      "created_at": "2024-01-15T09:30:00Z",
6
      "status": "queued",
7
      "query": "Impact of renewable energy adoption on global carbon emissions",
8
      "reasoning_loops_consumed": 2,
9
      "running_time": 45,
10
      "results": [
11
        {
12
          "id": "1e4d5f7a-8b3c-4d2a-9f7e-123456789abc",
13
          "title": "Renewable Energy and Carbon Emissions: A Comprehensive Review",
14
          "url": "https://www.sciencedirect.com/science/article/pii/S1364032120301234",
15
          "citation_index": 1
16
        }
17
      ]
18
    }
19
  ],
20
  "pagination": {
21
    "limit": 10,
22
    "page": 1,
23
    "has_next": true,
24
    "total": 25
25
  }
26
}

Error handling

Common errors

Example error response

1
{
2
  "error": {
3
    "code": "INVALID_PAGINATION",
4
    "message": "Invalid pagination parameters: page must be >= 1",
5
    "details": {
6
      "page": 0,
7
      "limit": 10
8
    }
9
  }
10
}