# Read collections reliably

Follow the pagination model declared by each resource and preserve the response metadata.

Successful Partner API responses wrap their payload in `data`. The outer `object` identifies the result type. A collection uses `object: "list"`; cursor-paginated collections also include `meta`.

## Cursor-paginated resources

Methods such as the reconciliation ledger and analytics decisions accept `limit` and `cursor`.

```json
{
  "object": "list",
  "data": [],
  "meta": {
    "total": 0,
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  }
}
```

Omit the cursor for the first request. For the next page, pass back `meta.next_cursor` unchanged. Keep the other filters stable while traversing the collection. Stop when `next_cursor` is `null` or `has_more` is false.

The shared pagination DTO accepts a page size from 1 to 200. Use the method reference to confirm that a given endpoint supports these parameters.

## Other collection shapes

Not every list is cursor-paginated. `/partner/users` returns its attributed-user collection without cursor metadata. The user ledger and webhook delivery list have a bounded `limit` but no next-cursor field.

Do not append pagination parameters to methods that do not document them. Some routes reject unknown query parameters; others have legacy parsing behavior.

## SDK metadata

SDK resource methods return the unwrapped `data` value. Response metadata is available separately on the client. Read it immediately after the relevant request; a shared client's next completed request can replace it.

For concurrent page traversals, use separate client instances or keep each returned page and its metadata together in your own code.