> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brand-wallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination & filtering

> How BrandWallet list endpoints return paged results and how to filter them with the f[field]=value query syntax.

BrandWallet list endpoints return a common envelope: the records in `data`, and paging information in `meta`. Single-resource and action endpoints return the object directly, without an envelope.

## Pagination

<ParamField query="limit" type="number">
  Page size. Defaults to `50`, maximum `250`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque paging token. When a response includes `meta.cursor`, pass it back as `?cursor=` to fetch the next page. When `meta.cursor` is absent, you are on the last page.
</ParamField>

<ResponseField name="meta.total" type="number">
  Total record count for the current filter, independent of paging position.
</ResponseField>

## Filtering

Filters use the `f[field]=value` query syntax. Each list endpoint documents its own **filterable fields**. An unknown field is rejected with `invalid_filter_field` (the error lists the allowed fields).

<Steps>
  <Step title="Exact match">
    `f[status]=1`. Comma means IN: `f[status]=1,2`.
  </Step>

  <Step title="Contains match">
    Text fields like `f[data.phone]=531951` match case-insensitively anywhere in the value, with a minimum term length per field.
  </Step>

  <Step title="Combining filters">
    Multiple `f[...]` params are ANDed together, and can be mixed with `limit` / `cursor`.
  </Step>
</Steps>

<RequestExample>
  ```bash Request theme={null}
  curl "$BASE_URL/v1/customers?f[status]=1&f[data.phone]=531951&limit=50" \
    -H "Authorization: Bearer ACCESS_TOKEN"
  ```

  ```bash Next page theme={null}
  curl "$BASE_URL/v1/customers?f[status]=1&cursor=eyJ0IjoiMjAyNi0wNy0yNFQx..." \
    -H "Authorization: Bearer ACCESS_TOKEN"
  ```
</RequestExample>

<ResponseExample>
  ```json List envelope — 200 OK theme={null}
  {
    "data": [ /* records */ ],
    "meta": {
      "total": 1240,
      "limit": 50,
      "cursor": "eyJ0IjoiMjAyNi0wNy0yNFQxMjo1NjowMy43MDJaIi..."
    }
  }
  ```
</ResponseExample>

## Filter errors

| Token                  | Status | Meaning                                                                                          |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `invalid_filter_field` | 400    | The `f[...]` field is not filterable on this endpoint. The description lists the allowed fields. |
| `invalid_filter_value` | 400    | The filter value is malformed (wrong type, empty, or below the minimum term length).             |
| `invalid_limit`        | 400    | `limit` is not an integer between 1 and 250.                                                     |
| `invalid_cursor`       | 400    | `cursor` is not a cursor returned in `meta`.                                                     |

See the complete [Error Reference](/api/errors).