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": "f2f6e5db-2c7d-4f56-bb0c-5a6b6a7a9b10",
5
      "created_at": "2025-09-14T12:00:00Z",
6
      "status": "queued",
7
      "query": "Is lithium supply a bottleneck for EV adoption?",
8
      "results": []
9
    },
10
    {
11
      "id": "11111111-2222-3333-4444-555555555555",
12
      "created_at": "2025-09-13T18:21:37Z",
13
      "status": "completed",
14
      "query": "Summarise key findings from these docs",
15
      "results": [
16
        {
17
          "id": "string",
18
          "score": 0.92,
19
          "title": "IEA Global EV Outlook 2025",
20
          "url": "https://www.iea.org/reports/global-ev-outlook-2025",
21
          "citation_index": 1
22
        }
23
      ],
24
      "content": "Final synthesis text…"
25
    }
26
  ],
27
  "pagination": {
28
    "limit": 10,
29
    "page": 1,
30
    "has_next": true
31
  }
32
}

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
}