# Pagination and filtering

> The list envelope, page-based pagination, filters with field.condition=value, and sorting.

Every list endpoint takes `page` (from 1) and `limit` (default 20, max 100) and returns the same envelope:

```json
{
  "object": "list",
  "data": [{ "object": "post", "id": "pst_…" }],
  "page": 1,
  "limit": 20,
  "total": 123,
  "has_more": true,
  "next_page_url": "https://api.socialit.com/v1/posts?page=2&limit=20",
  "previous_page_url": null
}
```

`total` can be `null` on very large lists. Follow `next_page_url` until `has_more` is `false`.

## Filters

Filter with `field.condition=value` query parameters. Each list documents which fields it accepts.

| Type | Conditions |
|---|---|
| Strings | `exact`, `not_exact`, `contains`, `not_contains`, `starts_with`, `ends_with`, `empty`, `not_empty` |
| Numbers | `gt`, `gte`, `lt`, `lte` |
| Dates | `before`, `after` |

```bash
curl "https://api.socialit.com/v1/posts?content.contains=launch&scheduled_at.after=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Filters combine with AND. Add `match=or` to match any of them.

Common filters also have plain shortcuts, such as `?status=scheduled&profile_id=pro_…&platform=instagram`.

## Sorting

`sort=<field>&order=asc|desc`, for example `?sort=scheduled_at&order=asc`.

## Cursor lists

Lists read live from a network (Focus mode resources, ad libraries, catalog products) can't jump to a page. They use the same envelope plus a cursor:

```json
{
  "object": "list",
  "data": [{ "id": "dQw4w9WgXcQ", "title": "Launch video" }],
  "limit": 25,
  "total": null,
  "has_more": true,
  "next_cursor": "CBkQAA",
  "next_page_url": "https://api.socialit.com/v1/accounts/sa_…/focus/videos?limit=25&cursor=CBkQAA",
  "previous_page_url": null
}
```

Pass `next_cursor` back as `cursor` (some endpoints also accept `after`), or follow `next_page_url`, until `has_more` is `false`. `total` is set only when the network reports it.

## MCP

List tools take the same parameters, plus `filters: [{ "field": "status", "condition": "exact", "value": "scheduled" }]`, which maps to `status.exact=scheduled`.

---

Source: https://socialit.com/docs/api-reference/pagination/
