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

# Pagination & filters

> Cursor pagination, sparse fieldsets, and structured search.

## Cursor pagination

Lists return `object: "list"` with a `pagination` block:

```json theme={null}
{
  "object": "list",
  "data": [ … ],
  "pagination": { "next_cursor": "eyJ…", "has_more": true, "limit": 25 },
  "meta": { "request_id": "req_…" }
}
```

Request the next page by passing `next_cursor` as `?cursor=`:

```bash theme={null}
curl "https://api.apyconnect.io/v1/contacts?limit=50&cursor=eyJ…" \
  -H "Authorization: Bearer $TOKEN"
```

The cursor is **opaque** (don't build it by hand). When `has_more` is `false`, you've reached the end.
`limit` ranges from 1 to 100 (default 25).

## Filters

Many lists accept query filters. Examples on contacts:

```
GET /v1/contacts?q=ada&stage=lead&tag=vip&country=US
GET /v1/conversations?status=open&channel_type=whatsapp&assignee_id=usr_…
```

## Sparse fieldsets

Request only the fields you need with `?fields=` (comma-separated). `object` and `id` always return:

```
GET /v1/contacts?fields=name,email,tags
```

## Structured search

For richer filters (including custom fields), use `POST /v1/{resource}/search`:

```bash theme={null}
curl -X POST https://api.apyconnect.io/v1/contacts/search \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "filters": { "stage": "customer", "custom_fields": { "plan": "gold" } } }'
```

It returns a paginated list just like the `GET`.