Pagination & Filtering

Cursor pagination on every list endpoint, stable under concurrent inserts, plus the filters worth knowing.

The shape

Every list endpoint returns the same wrapper:

{
  "data": [{ "id": "cus_...", "object": "customer" }],
  "has_more": true,
  "next_cursor": "MjAyNi0wOC0yNlQwOToxNTozMlp8Y3VzXzAzM3g..."
}

Walk pages by passing cursor back until has_more is false:

curl -s "$BASE/api/customers?limit=50" -H "Api-Key: $KEY"
curl -s "$BASE/api/customers?limit=50&cursor=MjAyNi0w..." -H "Api-Key: $KEY"

limit is 1 to 100. The default is 25.
Ordering is newest first.
Cursors are stable under concurrent inserts. Rows created while you paginate never shift or duplicate what you have already seen, because this is cursor pagination, not OFFSET.
Treat the cursor as opaque. Its format may change, and a cursor we did not issue returns 400 invalid_cursor.

A few endpoints return the wrapper with has_more: false and next_cursor: null because the set is inherently small: the nested virtual-account and wallet lists for one customer, the webhook list, and verification rounds.

Filters

Endpoint	Filters
`GET /api/customers`	`partner_reference_id`
`GET /api/virtual_accounts`	`customer_id`, `partner_reference_id`
`GET /api/wallets`	`customer_id`, `partner_reference_id`
`GET /api/deposits`, `/conversions`, `/payouts`, `/transactions`	`customer_id`

curl -s "$BASE/api/customers?partner_reference_id=user-8213" -H "Api-Key: $KEY"

partner_reference_id

partner_reference_id is your own identifier, echoed back. It is settable on customers, virtual accounts, and wallets at creation, unique per environment within your account (409 partner_reference_id_exists on a collision), and the intended way to correlate Rasto objects with your own records.

Set it at creation. It is the difference between a reconciliation job that joins on one column and one that maintains a mapping table.

Was this page helpful?