Pagination

Overview

List endpoints in the Arcus API use cursor-based pagination: you ask for a page with limit, and you ask for the next page by passing the ID of the last record you received as starting_after. Unlike offset pagination (?page=3), cursor pagination is stable: inserting or deleting records between pages does not cause items to be skipped or duplicated. The examples below use GET /v1/orders. By default that endpoint lists only quotes, sales orders, and invoices; pass document_type to page through returns, purchase orders, or late-fee invoices instead.

List response envelope

A list endpoint returns this envelope:

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "next_cursor": "7c1b6f0e-5a52-4d0e-9a52-0d6d5f3c9b11",
  "url": "/v1/orders"
}

Field	Description
`object`	Always `"list"`
`data`	Array of resource objects for this page
`has_more`	`true` if more pages exist after this one
`next_cursor`	The ID to pass as `starting_after` to get the next page; `null` when `has_more` is `false`
`url`	The endpoint URL for this list

Stop paging when has_more is false. Do not rely on a total count to decide when you are done.

Parameters

Parameter	Type	Description
`limit`	integer	Records per page. The default is 25 on most list endpoints and 50 on `GET /v1/orders`. The maximum is on each endpoint’s reference page (200 on `GET /v1/orders`).
`starting_after`	string	Cursor: return records after this ID (exclusive).
`ending_before`	string	Cursor: return records before this ID (exclusive). Accepted only by some list endpoints, and never together with `starting_after`; `GET /v1/orders` pages forward only.

Paginating forward

# Page 1
curl "https://api.arcuserp.com/v1/orders?limit=25" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

# Page 2: pass next_cursor (the last ID of page 1's data array) as starting_after
curl "https://api.arcuserp.com/v1/orders?limit=25&starting_after=$NEXT_CURSOR" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

Paginating backward

On list endpoints that accept ending_before, pass it instead of starting_after to get the records before a known ID. Check the endpoint’s reference page; where it is not listed, page forward only.

# Return records before a known ID (only where the endpoint accepts ending_before)
curl "https://api.arcuserp.com/v1/contacts?limit=25&ending_before=$KNOWN_ID" \
  -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:

# Open orders for a specific account
curl "https://api.arcuserp.com/v1/orders?account_id=$ACCOUNT_ID&order_status=open&limit=50" \
  -H "Authorization: Bearer $ARCUS_API_KEY"

GET /v1/orders returns the newest orders first and filters by document_type, account_id, order_status, payment_status, created_after, and created_before. Filter parameters vary by resource. See each endpoint’s reference page for the full list.

Notes on performance

Use the largest limit the endpoint allows when bulk-fetching to minimize round trips
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