What is API Pagination?
A technique for dividing large API result sets into smaller pages, allowing clients to retrieve data incrementally without overwhelming resources.
API pagination is a technique for dividing large result sets into smaller, manageable pages that clients can retrieve incrementally. Rather than returning thousands or millions of records in a single response, which would consume excessive bandwidth, memory, and processing time, a paginated API returns a limited number of results per page along with metadata that enables the client to request subsequent pages.
There are several common pagination strategies. Offset-based pagination uses a page number or numeric offset to specify which portion of the results to return (for example, "return results 101 through 200"). Cursor-based pagination uses an opaque token that points to the position in the result set, with each response including a cursor for the next page. Keyset-based pagination uses the value of a specific field (such as a timestamp or ID) to determine where the next page begins.
Each strategy has different performance characteristics. Offset-based pagination is simple to implement and understand but performs poorly on large datasets because the server must skip over all preceding records to reach the requested offset. Cursor-based pagination offers consistent performance regardless of the page depth because the cursor encodes the server's position in the index. Keyset-based pagination offers similar performance benefits and is more transparent than cursors but requires a stable sort order.
A well-designed paginated API response includes several pieces of metadata alongside the data itself: the current page's results, the total number of results available (or an indication that more results exist), the cursor or offset for the next page, and optionally the cursor for the previous page. This metadata enables clients to implement features like progress indicators, "load more" buttons, and sequential page traversal.
Why It Matters
Pagination is essential for any API that can return large result sets, which is virtually every API that provides search functionality. In the trademark context, a search for common words or short strings can match thousands of records across multiple jurisdictions. Returning all of these results in a single response would be impractical for several reasons.
First, response size. A single trademark record can contain several kilobytes of data. A result set of 10,000 records could produce a response of 50 MB or more, which would be slow to transmit and expensive to parse. Pagination keeps individual responses small and manageable, typically a few hundred kilobytes per page.
Second, server resources. Generating a complete result set of thousands of records requires significant server-side processing, including database queries, normalization, and serialization. Processing this in a single operation ties up server resources and can affect the performance of other requests. Pagination allows the server to process smaller chunks efficiently.
Third, client resources. Client applications, particularly mobile apps and browser-based frontends, have limited memory and processing capacity. A client that receives 10,000 records at once must store and process all of them, which can cause performance issues or crashes. Paginated results allow clients to process data incrementally, displaying results as they are received.
Fourth, user experience. Users rarely need to see all results at once. A trademark professional reviewing search results typically examines the first few pages of the most relevant matches. Pagination enables this natural browsing pattern while ensuring that additional results are available if needed.
How Signa Helps
Signa's API uses cursor-based pagination on its list and search endpoints. Each paginated response has object: "list", the current page's items in data, a top-level has_more boolean, and a pagination object whose cursor requests the next page (null on the last page).
The default page size is 20, and clients can set limit from 1 to 100. Passing include_total=true adds pagination.total_count; on trademark search the count stops at 10,000 and is marked total_count_approximate: true when more records match. Counts cost an extra query, so request them only when you need to display one.
A search with q pages through a ranked result by position and reaches at most 10,000 rows. To go further, narrow the query with filters such as a filing date range. A grouped request without q, using filters only, pages by key and has no fixed depth.
Cursors are opaque and keep the query's sort order, but a long walk through a live index does not freeze the result set: records indexed or re-ranked between requests can shift positions. Deduplicate on id, and restart from the first page if a cursor returns cursor_expired or cursor_invalid. The TypeScript SDK follows has_more and the cursor for you.
Example
A legal research tool uses Signa's search endpoint behind an "infinite scroll" results panel, where new results load as the user reaches the bottom of the list.
When a user searches, the tool calls the search endpoint with limit=25 and include_total=true. The response holds the first 25 results, has_more: true, a pagination.cursor and a pagination.total_count, so the tool can show "Showing 1-25 of N results."
As the user scrolls, the tool repeats the same request with the cursor from the previous page and appends the next 25 results, deduplicating on id. It stops when has_more is false, and if the user changes a filter it starts again from the first page, because a cursor belongs to one exact query.