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

# Pagination

> List endpoints return pages of up to 100 items with an opaque next_cursor; pass it back as cursor until it is null.

Every list endpoint uses cursor pagination. You ask for a page size, the response tells you where the next page starts, and you stop when there isn't one.

## Request

| Parameter | Type | Default | Rules |
| - | - | - | - |
| `limit` | integer | `50` | From `1` to `100`. The reporting endpoints take `1` to `5000` (default `1000`); see below. Out-of-range or non-integer values return `400 invalid_parameter`; they're never silently clamped. |
| `cursor` | string | none | The `next_cursor` value from the previous page, passed back unchanged. At most 1,024 characters. |

## Response

Every list response has the same shape:

```json theme={"system"}
{
  "data": [
    { "id": "c4a1e8f2-7d3b-4c6a-9e5f-1b2d3c4e5f60", "name": "Acme Analytics" }
  ],
  "next_cursor": "eyJ…"
}
```

| Field | Meaning |
| - | - |
| `data` | The items on this page, up to `limit` of them. |
| `next_cursor` | Pass it as `cursor` to get the next page. `null` means this is the last page. |

The last page can be full: a page with exactly `limit` items may still be the last one. Always use `next_cursor`, not the item count, to decide whether to continue. You never get an empty trailing page.

## Sort order

Each list has a fixed order, so pages never overlap:

| Endpoint | Order |
| - | - |
| `GET /projects` | Oldest brand first |
| `GET /projects/{project_id}/prompts` | Oldest prompt first |
| `GET /projects/{project_id}/citations` | Most cited first (`times_cited`, descending) |
| `GET /projects/{project_id}/articles` | Newest article first (by creation date) |
| `GET /projects/{project_id}/demand/terms` | Alphabetical by normalized term |
| `GET /projects/{project_id}/facts` | Oldest fact first |
| `GET /projects/{project_id}/fact-checks` | Most recently seen claim first |
| `GET /reporting/answers`, `/reporting/mentions`, `/reporting/citations` | By brand, then by day |

`GET /projects/{project_id}/visibility` isn't paginated. It returns one point per tracked day for a range of at most 366 days.

On the reporting endpoints, `limit` counts answers, and a page always holds whole days. A page can run past `limit` by the rest of its last day.

## Cursors are stable

Cursors point at the last item you received, not at a numeric offset. Adding items while you page doesn't shift the pages, so you never see an item twice. Items that sort after your position (a new brand or prompt, for example) show up on a later page. Items that sort before it (a claim seen again in fact checks, since they're newest first) show up on your next pass from the first page. Citation counts can also change mid-pass: a source whose `times_cited` rises past your position moves to an earlier page.

## Rules for cursors

* **Treat cursors as opaque.** Their format can change at any time. Don't decode, build or modify them.
* **Reuse a cursor only with the endpoint and filters that produced it.** Mixing them gives unpredictable pages or `400 invalid_cursor`.
* **An invalid cursor returns `400 invalid_cursor`.** Start again from the first page, without `cursor`.

```json theme={"system"}
{
  "type": "/api/v1/problems/invalid_cursor",
  "title": "Invalid cursor",
  "status": 400,
  "instance": "urn:request:2f4e6a8c-1b3d-4f5a-8c7e-9d0b2a4c6e81"
}
```

## Fetch every page

```bash cURL theme={"system"}
# First page
curl "https://app.usequotable.com/api/v1/projects/$PROJECT_ID/prompts?limit=100" \
  -H "Authorization: Bearer $QUOTABLE_API_KEY"

# Next page: pass next_cursor from the previous response
curl "https://app.usequotable.com/api/v1/projects/$PROJECT_ID/prompts?limit=100&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $QUOTABLE_API_KEY"
```

```javascript JavaScript theme={"system"}
const BASE = "https://app.usequotable.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.QUOTABLE_API_KEY}` };

export async function* paginate(path, params = {}) {
  let cursor = null;
  do {
    const query = new URLSearchParams({ ...params, limit: "100" });
    if (cursor) query.set("cursor", cursor);
    const res = await fetch(`${BASE}${path}?${query}`, { headers });
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const page = await res.json();
    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor);
}

// Usage
for await (const prompt of paginate(`/projects/${process.env.PROJECT_ID}/prompts`, { active: "true" })) {
  console.log(prompt.text);
}
```

```python Python theme={"system"}
import os
import requests

BASE = "https://app.usequotable.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['QUOTABLE_API_KEY']}"

def paginate(path, **params):
    cursor = None
    while True:
        query = {**params, "limit": 100}
        if cursor:
            query["cursor"] = cursor
        res = session.get(f"{BASE}{path}", params=query, timeout=30)
        res.raise_for_status()
        page = res.json()
        yield from page["data"]
        cursor = page["next_cursor"]
        if not cursor:
            break

# Usage
for prompt in paginate(f"/projects/{os.environ['PROJECT_ID']}/prompts", active="true"):
    print(prompt["text"])
```

## Filters

Filters combine with pagination. Unknown query parameters are ignored, and an empty value (`?status=`) counts as absent.

| Endpoint | Filter | Values |
| - | - | - |
| `/prompts` | `active` | `true` for active prompts only, `false` for inactive only. Both when absent. |
| `/citations` | `domain` | Case-insensitive substring of the cited domain, up to 253 characters. |
| `/articles` | `status` | One of the values the `status` field returns: `suggested`, `researching`, `outline`, `generating`, `polishing`, `awaiting_review`, `publishing`, `draft`, `published`, `publish_unknown`, `publish_quarantined`. |
| `/demand/terms` | `q` | Case-insensitive substring of the normalized term, up to 200 characters. |
| `/demand/terms` | `location_code`, `language` | Narrow to one location, for example `location_code=2840&language=English`. |
| `/facts` | `status` | `approved` (the default), `suggested`, `archived` or `rejected`. |
| `/facts` | `active` | `true` for switched-on facts only, `false` for switched-off only. Both when absent. |
| `/fact-checks` | `from`, `to` | A date range, `YYYY-MM-DD`. The last 30 days when absent; at most 366 days. |
| `/fact-checks` | `engine`, `verdict` | Comma-separated engine ids; `supported` or `contradicted`. All when absent. |
| `/reporting/*` | `from`, `to` | A date range, `YYYY-MM-DD`. The last 30 days when absent; at most 366 days. |
| `/reporting/*` | `project_id`, `engine` | Comma-separated brand ids (up to 100) and engine ids. Every brand the key can read, and every engine, when absent. |
| `/reporting/*` | `runs` | `all` (the default), or `complete` to leave out days that answered under half the prompt set. |

## Next steps

> [card] [Export to a spreadsheet](https://docs.usequotable.com/guides/export-to-spreadsheet.md)
>
> Page through every list and write it to CSV.

> [card] [Rate limits](https://docs.usequotable.com/api-reference/rate-limits.md)
>
> Pace bulk exports so they never hit a 429.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.