> For the complete documentation index, see [llms.txt](https://docs.flash.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flash.im/docs/api-reference/incremental-fetching-and-rate-limits.md).

# Incremental Fetching & Rate Limits

## Cursors: poll without missing or re-reading anything

{% stepper %}
{% step %}

### First call

Set `limit` to your display size. Store the `nextCursor` that comes back.
{% endstep %}

{% step %}

### Poll with the cursor

Call again with `cursor=<stored>`. You get only what is new.
{% endstep %}

{% step %}

### Drain while hasMore

While `hasMore` is `true`, keep fetching with the returned `nextCursor`.
{% endstep %}
{% endstepper %}

```mermaid
flowchart LR
    A["First call<br/>limit=20"] --> B["Store nextCursor"]
    B --> C["Poll with cursor"]
    C --> D{hasMore?}
    D -->|true| C
    D -->|false| E["Wait 10 min"]
    E --> C
```

The cursor advances only over items you have received, so nothing is ever missed, regardless of polling interval.

* `since` (ISO 8601 UTC) fetches everything published after a given time. Use it for the very first call or to recover after downtime; when both are sent, `cursor` wins
* On [`/v1/match`](/docs/api-reference/match-api.md), cursors work **per query**: each result carries its own `nextCursor`

## Polling

{% hint style="info" %}
Recommended polling interval: **every 10 minutes**. With cursors, most polls return only what is new, so frequent polling buys little.

[Top News](/docs/api-reference/top-news-api.md) is the exception: it regenerates hourly, so poll it once an hour at 10 minutes past the hour.
{% endhint %}

## Rate limits

If you send requests faster than your key allows, you get **429** with a `Retry-After` header (seconds). Back off and retry after that time.

## Errors

| Code | Meaning                                                                                                                           |
| ---- | --------------------------------------------------------------------------------------------------------------------------------- |
| 200  | Success (including no-match results in the Match API)                                                                             |
| 400  | Malformed request: missing required field, invalid `category`, unknown `fields` name, more than 100 queries, more than 5 keywords |
| 401  | Missing or invalid API key                                                                                                        |
| 429  | Rate limit. Retry after `Retry-After` seconds                                                                                     |