# Seiten, Filter und Sortierung

> Wie jede Liste funktioniert. Cursor-Seiten, Seitengröße, Filter und die Reihenfolge der Ergebnisse.

Stand: 2026-10-30. Quelle: https://docs.smartchat.marketing/de/concepts/pagination/

Jede Liste in der API funktioniert gleich. Listen geben nie alles auf einmal zurück.

## Seiten

| Parameter | Bedeutung |
|---|---|
| `limit` | Einträge pro Seite, 1 bis 100. Standard 20. (MCP-Werkzeuge: Standard 20, höchstens 50.) |
| `cursor` | Der Wert von `next_cursor` der vorherigen Seite. |

Die Antwort sagt dir, ob es mehr gibt:

```json
{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0yNVQwOTo0MTowN1oiLCJpIjoiLi4uIn0",
  "url": "/v1/contacts"
}
```

Die Python-Beispiele nutzen das Paket `requests` (`pip install requests`). Um alles zu lesen, wiederhole den Aufruf mit `cursor` gleich `next_cursor`, bis `has_more` den Wert `false` hat:

**Python**

```python
import os
import requests

url = "https://api.smartchat.marketing/v1/contacts"
headers = {"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"]}
params = {"limit": 100}
while True:
    page = requests.get(url, headers=headers, params=params).json()
    for item in page["data"]:
        print(item["id"])
    if not page["has_more"]:
        break
    params["cursor"] = page["next_cursor"]
```

**TypeScript**

```typescript
const headers = { Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}` };
let cursor: string | null = null;
do {
  const query = new URLSearchParams({ limit: "100", ...(cursor ? { cursor } : {}) });
  const page = await (await fetch(`https://api.smartchat.marketing/v1/contacts?${query}`, { headers })).json();
  for (const item of page.data) console.log(item.id);
  cursor = page.has_more ? page.next_cursor : null;
} while (cursor);
```

## Der Cursor

- Der Cursor ist ein undurchsichtiger Text. Lies ihn nicht und baue ihn nicht selbst.
- Er funktioniert nur mit den **gleichen Filtern** und für das **gleiche Konto**. Mit anderen Filtern lautet die Antwort [`invalid_cursor`](https://docs.smartchat.marketing/de/errors/#invalid_cursor). Fang ohne Cursor neu an.
- Die Reihenfolge ist stabil: Neue Einträge, die beim Blättern auftauchen, lassen dich keine Einträge verpassen oder doppelt sehen.

## Filter

Filter sind Query-Parameter, die wie das Feld heißen, zum Beispiel `tag=` oder `optin_whatsapp=`. Jede Listenseite in der [API-Referenz](https://docs.smartchat.marketing/de/api/) zeigt ihre Filter im Abschnitt "Listen, Filter und Sortierung". Ein unbekannter Filter ergibt [`unknown_parameter`](https://docs.smartchat.marketing/de/errors/#unknown_parameter); er wird nie still ignoriert.

## Sortierung

Die Standard-Reihenfolge ist neueste zuerst (`created_at` absteigend, dann `id` absteigend). Eine Liste, die sich anders sortieren lässt, sagt das auf ihrer Referenzseite und akzeptiert `order_by`.

## Die eine Ausnahme: Wissenssuche

`GET /knowledge/search` (MCP: `search_knowledge`) ist eine Suche, keine Liste. Sie gibt nur die besten Textstellen zurück: `limit` ist 1 bis 12 (Standard 5) und es gibt keinen `cursor`. Um die Dokumente selbst zu lesen, nutze die normale Liste `GET /knowledge-documents`.

## Summen

Die meisten Listen haben keine Summe. Wo `total_count` existiert, ist er ungefähr und kann ein wenig danebenliegen.