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

# Pagination

> The list envelope, cursor rules, page sizes and totals for search and the changes feed.

Search and the changes feed return pages with a cursor. Batch retrieve and the jurisdictions list return everything in one response. For a worked loop, see the [Pagination guide](https://docs.pinakelai.com/guides/pagination.md).

## Search envelope

```json theme={null}
{
  "object": "list",
  "data": [],
  "has_more": true,
  "next_cursor": "eJxtkM1qwzAQhF-l7NkH2_qxpGNPPbSvUHoIJQ.Kp3mLzVk2jcR",
  "unavailable_jurisdictions": [],
  "search_progress": { "application_date_reached": "2019-03-04" },
  "total": { "value": 10000, "relation": "gte" }
}
```

| Field | Type | Meaning |
| - | - | - |
| `object` | string | `list` |
| `data` | array | `trademark_summary` objects, or `trademark` objects with `include=full` |
| `has_more` | boolean | Whether another page may hold results |
| `next_cursor` | string or null | Cursor for the next page; `null` exactly when `has_more` is `false` |
| `unavailable_jurisdictions` | array of strings | Registers skipped because they are reloading |
| `search_progress` | object | Broad searches only: `application_date_reached`, the application date the scan has reached, or `null` once it is past dated records |
| `total` | object or null | Only with `include_total=true`: `{value, relation}`, or `null` if counting did not finish |

A page can be short, or empty, while `has_more` is `true`. Stop only when `has_more` is `false`.

## Changes feed envelope

```json theme={null}
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": "eJxNjEEKwjAQRe9y1l3EVnDhOdQLFLp2IXRbxG0ZphgxIAwTF_n7iQqFt3n_Mf8FTRBCkMU.9cQ2aNfDdA",
  "unavailable_jurisdictions": [],
  "feed_start": "2026-11-30T02:41:09.000000Z",
  "complete_through": "2026-12-01T03:30:00.115406Z"
}
```

| Field | Type | Meaning |
| - | - | - |
| `data` | array | `change` items, in publication order |
| `has_more` | boolean | `false` means everything published before `complete_through` has been delivered |
| `next_cursor` | string | **Never null.** Your position in the feed; store it after every page |
| `unavailable_jurisdictions` | array of strings | Registers in your scope that are reloading; their changes follow later |
| `feed_start` | timestamp | The earliest point of the feed's history; `since` cannot be earlier |
| `complete_through` | timestamp | Every change published before this time has been delivered when `has_more` is `false` |

## Cursor rules

* A cursor is bound to the filters and sort of the request that produced it. Send the same filters and sort with the cursor; only `limit`, `include` and `include_total` may change. Otherwise: 400 [`cursor-mismatch`](https://docs.pinakelai.com/errors/cursor-mismatch).
* A cursor that is damaged, or signed with a retired key, gets 400 [`invalid-cursor`](https://docs.pinakelai.com/errors/invalid-cursor). A cursor longer than 6,000 characters gets 400 [`invalid-request`](https://docs.pinakelai.com/errors/invalid-request) with the code `query-too-long`.
* On the feed, `since` is accepted only on a request without `cursor`.
* Cursors are opaque. Do not parse or build them.
* There is no snapshot: records that change while you page can appear twice or be passed. Upsert by `id`.

## Page sizes

| Endpoint | `limit` default | `limit` maximum |
| - | - | - |
| Search | 25 | 100; 25 with `include=full` |
| Changes feed | 100 | 100; 25 with `include=full` |
| Batch retrieve | (not paged) | 100 ids; 25 with `include` of `goods_services`, `assignments` or `source_record` |

A `limit` above the maximum is a 400, not a silent cap.

## Totals

`include_total=true` on search adds `total` to the first page and repeats it on later pages:

| `relation` | Meaning |
| - | - |
| `eq` | `value` is exact. Returned for anchored searches, for a jurisdiction alone or with a status or status category, and for whole application years. |
| `gte` | At least `value` matches; counting stopped at about 10,000. |

`"total": null` means counting did not finish in time; the page is still complete.

## Ordering

Search results follow `sort` (default `-application_date`), with ties broken by jurisdiction and id. Records without a usable date for the sort field come last in both directions. The feed is ordered by publication time, then jurisdiction and id.


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