Skip to main content
List and search endpoints use cursor-based pagination: each page gives you a cursor that picks up where it left off. Paginated responses include:
  • object: always list.
  • data: the items on this page.
  • has_more: whether more items follow.
  • pagination.cursor: pass this to get the next page. null on the last page.
You can page through results with these query parameters:
​
integer
default:"20"
Items per page, from 1 to 100 unless the endpoint says otherwise.
​
string
The pagination.cursor from the previous response. Leave it out on the first request.
​
boolean
default:"false"
Adds pagination.total_count to the response. Supported on trademark search and the owner, attorney, firm, entity and jurisdiction lists. pagination.total_count_approximate: true marks a count that is not exact. On trademark search it means more than 10,000 matched: total_count reads 10,000 and is a lower bound. On the owner, attorney, firm and entity lists it can also mean the count includes records hidden from the results, so it can be higher than the rows you can page through. Request counts only when you need them, since they cost an extra query.

​
Example

Request the next page with the same parameters plus the cursor, and stop when has_more is false:
The TypeScript SDK does this for you with async iterators.

​
Cursor rules

  • Keep every other parameter (q, filters, sort, limit) the same across pages.
  • Treat cursors as opaque. Their format can change without notice.
  • Cursors don’t expire on a timer, but they can be invalidated. If a page returns cursor_expired or cursor_invalid, restart from the first page. See Errors.

​
Search depth

Trademark search pages in one of two ways, and only one has a depth limit:
  • By position, up to 10,000 rows. A search with q, and any request served one row per record (international_registrations=expanded, or a grouped request that fell back with an expanded_fallback warning), pages through a ranked or sorted result by position. It reaches at most 10,000 rows. When more match, the last page inside that window carries a result_window_reached warning, and a cursor past it returns 400 cursor_window_exceeded. To reach more, narrow the query with filters, such as a filing_date range.
  • By key, no fixed depth. A grouped request without q, using filters or text filters only, pages by the sort values of the last row, so it can walk past 10,000 rows.
A position walk does not freeze the result set. Records indexed or re-ranked between two page requests can shift positions, so a long walk can repeat or skip a row. Deduplicate on id, and prefer a filter such as an updated_at or filing_date range over a very deep walk when you sync. When the search index is rebuilt, an older cursor returns cursor_invalid: restart from the first page.