Pagination

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:

{
  "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

# 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

# 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:

// Iterate all orders without manual cursor management
for await (const order of arcus.orders.list({ limit: 100 })) {
  console.log(order.id, order.document_type);
}

# 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)

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)
}

Filtering and sorting

Most list endpoints support additional query parameters for filtering:

# 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

Get Started

Concepts

Guides

SDKs

Collections

Overview

List response envelope

Parameters

Paginating forward

Paginating backward

Filtering and sorting

Notes on performance

​Overview

​List response envelope

​Parameters

​Paginating forward

​Paginating backward

​SDK usage: auto-pagination

​Filtering and sorting

​Notes on performance

Overview

List response envelope

Parameters

Paginating forward

Paginating backward

SDK usage: auto-pagination

Filtering and sorting

Notes on performance