> ## 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

> Learn how BrandWallet list endpoints return paged results and how to filter the results with a filter query.

**All top-level API resources support bulk fetches through list endpoints. Lists return a common envelope — records in `data`, paging information in `meta`. Single-resource and action endpoints return the object directly, without an envelope.**

```json theme={null}
{
  "data": [ { "…": "…" } ],
  "meta": {
    "total": 1240,
    "limit": 50,
    "cursor": "eyJ0IjoiMjAyNi0wNy0yNFQxMjo1NjowMy43MDJaIi..."
  }
}
```

### Pagination parameters

| Parameter | Type | Description |
| - | - | - |
| `limit` | number | Page size. Defaults to `50`, maximum `250`. |
| `cursor` | 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. |

`meta.total` is the total record count for the current filter, independent of paging position.

### 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's description lists the allowed fields).

* **Exact match:** `f[status]=1`. Comma means IN: `f[status]=1,2`.
* **Contains match:** text fields like `f[data.phone]=531951` match case-insensitively anywhere in the value, with a minimum term length per field. The comma is searched literally in contains fields.
* **Combining:** multiple `f[...]` params are **AND**ed together, and can be mixed with `limit` / `cursor`.

### Example

```bash theme={null}
curl "$BASE_URL/v1/customers?f%5Bstatus%5D=1&f%5Bdata.phone%5D=531951&limit=50" \
  --header 'Authorization: Bearer ACCESS_TOKEN'
```

```bash theme={null}
# Next page
curl "$BASE_URL/v1/customers?f%5Bstatus%5D=1&cursor=eyJ0IjoiMjAyNi0wNy0yNFQx..." \
  --header 'Authorization: Bearer ACCESS_TOKEN'
```

### 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.