API Overview

Pagination

Understanding and working with pagination

We’ve added pagination to some of the routes which might return a lot of data:

  • GET /v1/entities (without ?entityId query param will return all entities belonging to the calling developer)
  • GET /v1/transactions will return all transactions for a given entity
  • GET /v1/transactions/counterparties will return all the counterparties in the transaction history of a given entity

These requests without pagination now have an upper bound on the number of records they will return. If not all records are returned, the return body will include hasMore as true, and nextCursor, representing the last entity returned in the payload.

1{
2  "entities": [...],
3  "nextCursor": "abc123",
4  "hasMore": true
5}

Using Pagination

To use the pagination, there are two query parameters:

ParameterDescription
pageSizeControls the number of items you receive in the response (default: 25-50, max: 100)
cursorThe value returned as nextCursor in the previous paginated request (can be unset for the first page)

Example

Here’s an example of how to use pagination with the entities endpoint:

1GET {{baseUrl}}/v1/entities?pageSize=1

Response:

1{
2    "entities": [
3        {
4            "id": "abc123",
5            "name": "ACME LLC",
6            "external_id": "acme-123",
7            "entity_type": "LLC",
8            "address": null,
9            "settings": null,
10            "plaid_accounts": [],
11            "created_at": "2025-05-15T21:35:57.295Z",
12            "developer_id": "my-developer",
13            "instance_id": "my-instance-id",
14            "status": "ACTIVE"
15        }
16    ],
17    "nextCursor": "abc123",
18    "hasMore": true
19}

To get the next page, make a request using the nextCursor value:

1GET {{baseUrl}}/v1/entities?pageSize=1&cursor=abc123

Best Practices

Choose Appropriate Page Size

Select a pageSize that balances your needs for data completeness with API performance. Larger page sizes mean fewer requests but more data per request.

Handle hasMore Flag

Always check the hasMore flag to determine if you need to make additional requests to get all the data.

Store Cursor Value

Save the nextCursor value from each response to use in subsequent requests.

Error Handling

Implement proper error handling for cases where the cursor might be invalid or expired.

Example Implementation

Here’s a complete example of how to fetch all entities using pagination:

1async function getAllEntities(baseUrl, pageSize = 100) {
2  let allEntities = [];
3  let cursor = null;
4  let hasMore = true;
5
6  while (hasMore) {
7    const url = new URL(`${baseUrl}/v1/entities`);
8    url.searchParams.set('pageSize', pageSize);
9    if (cursor) {
10      url.searchParams.set('cursor', cursor);
11    }
12
13    const response = await fetch(url, {
14      headers: {
15        'Authorization': 'Bearer YOUR_JWT_TOKEN',
16        'Content-Type': 'application/json'
17      }
18    });
19    
20    if (!response.ok) {
21      throw new Error(`API request failed: ${response.status}`);
22    }
23    
24    const data = await response.json();
25
26    allEntities = allEntities.concat(data.entities);
27    hasMore = data.hasMore;
28    cursor = data.nextCursor;
29  }
30
31  return allEntities;
32}
33
34// Usage:
35const entities = await getAllEntities('https://api.openledger.com');
36console.log(`Retrieved ${entities.length} entities`);