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

# Pagination

> Navigate large result sets with cursor-based pagination on all Arcus list endpoints.

## Overview

All list endpoints in the Arcus API use **cursor-based pagination**. Unlike offset pagination (`?page=3`), cursor pagination is stable: inserting or deleting records between pages does not cause items to be skipped or duplicated.

## List response envelope

Every list endpoint returns this envelope:

```json theme={null}
{
  "object": "list",
  "data": [...],
  "has_more": true,
  "url": "/v1/entities/{entity_id}/orders",
  "total_count": 1247
}
```

| Field         | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `object`      | Always `"list"`                                                   |
| `data`        | Array of resource objects for this page                           |
| `has_more`    | `true` if more pages exist after this one                         |
| `url`         | The endpoint URL for this list                                    |
| `total_count` | Total matching records (only when `include_count=true` is passed) |

## Parameters

| Parameter        | Type    | Description                                                                           |
| ---------------- | ------- | ------------------------------------------------------------------------------------- |
| `limit`          | integer | Records per page. Default: 20. Max: 100.                                              |
| `starting_after` | string  | Cursor: return records after this ID (exclusive).                                     |
| `ending_before`  | string  | Cursor: return records before this ID (exclusive).                                    |
| `include_count`  | boolean | Include `total_count` in response. Adds a COUNT query; use sparingly on large tables. |

## Paginating forward

```bash theme={null}
# Page 1
curl "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders?limit=25" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

# Page 2: pass the last ID from page 1's data array
curl "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders?limit=25&starting_after=ord_01H..." \
  -H "Authorization: Bearer $ARCUS_API_KEY"
```

## Paginating backward

```bash theme={null}
# Return records before a known ID
curl "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders?limit=25&ending_before=ord_01H..." \
  -H "Authorization: Bearer $ARCUS_API_KEY"
```

## SDK usage: auto-pagination

All SDKs support automatic page iteration:

<CodeGroup>
  ```javascript Node theme={null}
  // Iterate all orders without manual cursor management
  for await (const order of arcus.orders.list({ limit: 100 })) {
    console.log(order.id, order.document_type);
  }
  ```

  ```python Python theme={null}
  # Auto-paginate
  for order in arcus.orders.list(limit=100):
      print(order.id, order.document_type)

  # Or manual
  page = arcus.orders.list(limit=25)
  while True:
      for order in page.data:
          process(order)
      if not page.has_more:
          break
      page = arcus.orders.list(limit=25, starting_after=page.data[-1].id)
  ```

  ```go Go theme={null}
  params := &arcus.OrderListParams{Limit: arcus.Int(100)}
  iter := client.Orders.List(ctx, params)
  for iter.Next() {
      order := iter.Order()
      fmt.Println(order.ID, order.DocumentType)
  }
  if err := iter.Err(); err != nil {
      panic(err)
  }
  ```
</CodeGroup>

## Filtering and sorting

Most list endpoints support additional query parameters for filtering:

```bash theme={null}
# Orders for a specific account, newest first
curl "https://api.arcuserp.com/v1/entities/$ARCUS_ENTITY_ID/orders?account_id=acc_01H...&sort=created_at_desc&limit=50" \
  -H "Authorization: Bearer $ARCUS_API_KEY"
```

Filter parameters vary by resource. See each endpoint's reference page for the full list.

## Notes on performance

* Use `limit=100` (the maximum) when bulk-fetching to minimize round trips
* Avoid `include_count=true` on hot paths -- it adds a COUNT query to every request
* Cursors are stable: you can safely resume a paginated scan after an interruption by restarting from the last ID you successfully processed