Skip to main content

​
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
}
FieldDescription
objectAlways "list"
dataArray of resource objects for this page
has_moretrue if more pages exist after this one
urlThe endpoint URL for this list
total_countTotal matching records (only when include_count=true is passed)

​
Parameters

ParameterTypeDescription
limitintegerRecords per page. Default: 20. Max: 100.
starting_afterstringCursor: return records after this ID (exclusive).
ending_beforestringCursor: return records before this ID (exclusive).
include_countbooleanInclude 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