# Stránkování

> Procházejte výpisy API Emailitu po stránkách přes page a limit, čtěte next_page_url, pracujte s formáty per_page a offset a s časovými okny výpisů e-mailů a událostí.

Endpointy pro výpisy vracejí výsledky po stránkách. Většina z nich používá čísla stránek s `page` a `limit`, šablony a automatizace používají `page` a `per_page` a endpointy DMARC používají `limit` a `offset`. Tato stránka vysvětluje jednotlivé formáty, časová okna výpisů e-mailů a událostí a jak projít všechny stránky.

## Page a limit

Většina endpointů pro výpisy přijímá dva parametry dotazu:

| Parametr | Popis |
| --- | --- |
| `page` | Stránka, kterou chcete načíst, od `1`. Výchozí hodnota je `1`. |
| `limit` | Počet objektů na stránce, od `1` do `100`. Hodnoty mimo tento rozsah vrátí chybu validace `400`. |

Výchozí velikost stránky závisí na endpointu:

| Výchozí `limit` | Endpointy |
| --- | --- |
| 10 | Domény, API klíče, seznamy kontaktů, kontakty, kampaně, formuláře, blokované adresy, webhooky, seznamy k ověření |
| 25 | E-maily, odběratelé |
| 50 | Výsledky seznamů k ověření |
| 100 | Události |

[Výpis odběratelů](/cs/docs/api-reference/audiences/subscribers/list/) přijímá také `per_page` jako alias pro `limit`.

### Odpověď

```json
{
  "data": [
    { "object": "domain", "id": "dom_4K468YrjOkR1wwdhqiO0G9XEUey", "name": "acme.com" }
  ],
  "next_page_url": "/v2/domains?page=3&limit=10",
  "previous_page_url": "/v2/domains?page=1&limit=10"
}
```

| Pole | Popis |
| --- | --- |
| `data` | Objekty na této stránce, od nejnovějších, pokud je [neseřadíte](/cs/docs/api-reference/filtering/) jinak. |
| `next_page_url` | Cesta k další stránce, nebo `null` na poslední stránce. |
| `previous_page_url` | Cesta k předchozí stránce, nebo `null` na první stránce. |

URL stránek jsou cesty, ne úplné URL, a u většiny endpointů obsahují jen `page` a `limit`, ne vaše filtry. Další stránku načtete tak, že zopakujete vlastní požadavek s `page` zvýšeným o jedna, a skončíte, když je `next_page_url` `null`.

Některé výpisy přidávají vedle `data` další pole:

| Pole | Endpointy | Obsahuje |
| --- | --- | --- |
| `total_records` | Kontakty, seznamy kontaktů, kampaně, formuláře | Počet odpovídajících objektů na všech stránkách. |
| `usage` | Webhooky | `used` a `limit` endpointů webhooků pro váš tarif a `filters_allowed`. |
| `usage` | Odběratelé | `used` a `limit` odběratelů seznamu kontaktů a `plan`. |
| `domain_limit`, `domain_count`, `plan_name` | Domény | Kolik odesílacích domén váš tarif povoluje (`null` znamená bez limitu), kolik jich máte a název tarifu. |

## Page a per_page

[Výpis šablon](/cs/docs/api-reference/templates/list/), [Výpis automatizací](/cs/docs/api-reference/automations/list/) a [Výpis spuštění](/cs/docs/api-reference/automations/runs/) používají místo `limit` parametr `per_page` a místo URL stránek vracejí počty stránek:

| Parametr | Popis |
| --- | --- |
| `page` | Stránka, kterou chcete načíst, od `1`. Výchozí hodnota je `1`. |
| `per_page` | Počet objektů na stránce, od `1` do `100`. Výchozí hodnota je `25`. |

```json
{
  "data": [],
  "total_records": 42,
  "per_page": 25,
  "current_page": 2,
  "total_pages": 2
}
```

Načítejte další stránky, dokud je `current_page` menší než `total_pages`.

## Limit a offset

Endpointy DMARC místo počítání stránek přeskakují určitý počet řádků:

| Parametr | Popis |
| --- | --- |
| `limit` | Počet vrácených řádků. Reporty: výchozí `25`, nejvýše `100`. Zdroje, země, sítě a odesílatelé reportů: výchozí `50`, nejvýše `200`. |
| `offset` | Počet přeskočených řádků. Výchozí hodnota je `0`. |

[Výpis souhrnných reportů](/cs/docs/api-reference/dmarc/list/) a [Výpis forenzních reportů](/cs/docs/api-reference/dmarc/forensic/) vracejí celkový počet, takže víte, kdy skončit:

```json
{
  "data": [],
  "meta": { "total": 130, "limit": 25, "offset": 50 }
}
```

Endpointy s rozpady vracejí `meta` jen s `limit` a `offset`. Skončete, když má stránka méně řádků než `limit`.

## Časová okna

Dva výpisy se dívají jen na nedávná data, pokud si nevyžádáte víc:

- **E-maily.** [Výpis e-mailů](/cs/docs/api-reference/emails/list/) ve výchozím stavu vrací e-maily za posledních 14 dní. Pokud chcete hledat dál do minulosti, předejte `date_from` (a volitelně `date_to`) jako datum, například `2026-08-01`. Filtry `created_at` okno nerozšiřují, proto použijte `date_from`.
- **Události.** [Výpis událostí](/cs/docs/api-reference/events/list/) ve výchozím stavu vrací události za poslední dva dny. Jakýkoli filtr `created_at`, například `created_at.after=2026-09-01`, toto okno nahradí. Výpis navíc končí na offsetu 2 500: stránka, která začíná za 2 500. událostí, vrátí `422` s kódem `events_offset_too_large`. Ke starším událostem se dostanete tak, že výsledky zúžíte filtry `type` nebo `created_at`.

## Načtěte všechny stránky

Opakujte požadavky, dokud API neoznámí, že další stránka není. Tyto příklady načtou všechny kontakty v seznamu kontaktů:

**cURL**

```bash
page=1
while : ; do
  response=$(curl -s -G https://api.emailit.com/v2/contacts \
    -H "Authorization: Bearer $EMAILIT_API_KEY" \
    --data-urlencode "audience_id=aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2" \
    --data-urlencode "limit=100" \
    --data-urlencode "page=$page")

  echo "$response" | jq -c '.data[]'

  [ "$(echo "$response" | jq -r '.next_page_url')" = "null" ] && break
  page=$((page + 1))
done
```

**Node.js**

```javascript
async function* listAll(path, params = {}) {
  for (let page = 1; ; page++) {
    const query = new URLSearchParams({ ...params, limit: '100', page: String(page) });
    const response = await fetch(`https://api.emailit.com/v2${path}?${query}`, {
      headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
    });
    if (!response.ok) throw new Error(`Emailit ${response.status}`);

    const body = await response.json();
    yield* body.data;
    if (!body.next_page_url) return;
  }
}

for await (const contact of listAll('/contacts', { audience_id: 'aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2' })) {
  console.log(contact.email);
}
```

**Python**

```python
import os
import requests

def list_all(path, params=None):
    session = requests.Session()
    session.headers["Authorization"] = f"Bearer {os.environ['EMAILIT_API_KEY']}"
    page = 1
    while True:
        response = session.get(
            f"https://api.emailit.com/v2{path}",
            params={**(params or {}), "limit": 100, "page": page},
            timeout=30,
        )
        response.raise_for_status()
        body = response.json()
        yield from body["data"]
        if not body["next_page_url"]:
            return
        page += 1

for contact in list_all("/contacts", {"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2"}):
    print(contact["email"])
```

## Konzistentní výsledky

Stránky se počítají v okamžiku, kdy si je vyžádáte. Pokud se během procházení výpisu řazeného od nejnovějších vytvoří nebo smažou objekty, mohou se objekty mezi stránkami posunout, takže některý uvidíte dvakrát, nebo vám některý unikne. Pro stabilní export výpisu, který stále roste, řaďte od nejstarších přes `order=created_at&direction=asc` (u kontaktů a blokovaných adres přes `sort=created_at&order=asc`) a přeskakujte ID, která už jste viděli.

## Související

  - [Filtrování a řazení](/cs/docs/api-reference/filtering/): Zužte a seřaďte výsledky výpisů.
  - [Limity rychlosti](/cs/docs/api-reference/rate-limits/): Udržujte hromadné čtení v rozumných mezích.

---
Zdroj: https://emailit.com/cs/docs/api-reference/pagination/