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

# Pagination

> Page through list endpoints with cursor or offset pagination.

List endpoints return a single page of results plus a `pagination` block on the [response envelope](/api-reference/response-format):

```json theme={null}
{
  "data": [ ... ],
  "pagination": {
    "has_more": true,
    "pagination_key": "abc123"
  }
}
```

Two strategies are available for walking through pages: cursor pagination with `pagination_key`, and offset pagination with `offset`.

## Cursor pagination (recommended)

Pass the `pagination_key` from the previous response as a query parameter in your next request. Keep going until `has_more` is `false` or `pagination_key` is `null`.

Cursor pagination stays fast no matter how deep you go, because the server resumes from the cursor instead of counting past the rows you skipped. **Use it for any programmatic consumer**: data syncs, backfills, agents, and background jobs.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.struct.to/v1/polymarket/market?pagination_key=abc123" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  let paginationKey = null;

  do {
    const params = new URLSearchParams();
    if (paginationKey) params.set("pagination_key", paginationKey);

    const res = await fetch(`https://api.struct.to/v1/polymarket/market?${params}`, {
      headers: { "X-API-Key": "YOUR_API_KEY" },
    });

    const json = await res.json();
    console.log(json.data);

    paginationKey = json.pagination?.pagination_key ?? null;
  } while (paginationKey);
  ```

  ```python Python theme={null}
  import requests

  pagination_key = None

  while True:
      params = {}
      if pagination_key:
          params["pagination_key"] = pagination_key

      response = requests.get(
          "https://api.struct.to/v1/polymarket/market",
          headers={"X-API-Key": "YOUR_API_KEY"},
          params=params,
      )

      json = response.json()
      print(json["data"])

      pagination = json.get("pagination")
      if not pagination or not pagination.get("has_more"):
          break

      pagination_key = pagination["pagination_key"]
  ```
</CodeGroup>

## Offset pagination

Some endpoints (currently the trader trades and PnL endpoints) also accept an `offset` query parameter, which skips a fixed number of rows from the start of the result set.

Offset exists for one specific case: **server-rendered, deep-linkable pages**. An SSR page at `?page=42` can map directly to `offset=4100&limit=100` and render that slice on the first request, without first replaying every page to obtain a cursor.

```bash cURL theme={null}
curl "https://api.struct.to/v1/polymarket/trader/trades/0xTRADER?limit=100&offset=4100" \
  -H "X-API-Key: YOUR_API_KEY"
```

`offset` is capped at a few thousand rows (typically in the 3,000 to 5,000 range). To read past that point, or to walk the whole dataset, switch to `pagination_key`.

<Warning>
  When both `offset` and `pagination_key` are supplied on the same request, `offset` takes precedence and the cursor is ignored.
</Warning>

## Which one to use

|                           | Cursor (`pagination_key`)             | Offset (`offset`)                         |
| ------------------------- | ------------------------------------- | ----------------------------------------- |
| Fetch the entire dataset  | Yes                                   | Not recommended                           |
| Jump to an arbitrary page | No                                    | Yes                                       |
| Best for                  | Programmatic consumers, syncs, agents | SSR pages with deep-linkable page numbers |

Default to `pagination_key`. Reach for `offset` only when you need to render an arbitrary page directly from a URL, and even then prefer the cursor once a user is paging sequentially.

<Note>
  Using the TypeScript SDK? The [`paginate` helper](/sdk/pagination) handles cursor iteration for you.
</Note>

<Tip>
  **Related guide:** [Fetching an entire dataset](/guides/fetching-all-data) walks through paging every row with the cursor for a complete backfill.
</Tip>