What is API Pagination?

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 implements cursor-based pagination for all endpoints that return collections, providing consistent performance and reliable traversal regardless of result set size. This approach was chosen over offset-based pagination because trademark searches can return large, dynamic result sets where offset-based approaches would suffer performance degradation on deep pages.

Each paginated response from Signa's API includes a standardized pagination envelope. The data array contains the current page's results. The pagination object includes nextCursor (an opaque token for requesting the next page), hasMore (a boolean indicating whether more results exist), and totalCount (the total number of matching records, when available). This consistent structure applies across all collection endpoints, from trademark search to monitor listing to alert retrieval.

The default page size is 25 results, which balances response size with round-trip efficiency. Clients can request custom page sizes up to 100 results per page using the limit parameter. For applications that need to process large result sets efficiently, larger page sizes reduce the total number of API calls required, while staying within reasonable response size boundaries.

Signa's cursors are stable across concurrent modifications to the underlying data. If new records are added to the database while a client is paginating through results, the cursor ensures that the client does not skip records or see duplicates. This stability is important for applications that process complete result sets, such as data exports or comprehensive portfolio audits.

The API also supports sorted pagination, allowing clients to specify the sort order of results (by relevance, filing date, similarity score, or other criteria) and paginate through the sorted results consistently. The cursor mechanism preserves the sort order across pages, ensuring that results appear in the same sequence regardless of which page they fall on.

For search endpoints specifically, Signa includes relevance metadata in each paginated response. The maxScore field indicates the highest similarity score in the complete result set, and the minScore field indicates the lowest score on the current page. This metadata helps clients decide whether to continue fetching additional pages or stop at the current page, optimizing their API usage.

Real-World Example

A legal research tool integrates Signa's API to provide trademark search functionality to its users. The tool's interface includes a search results panel that displays results in a scrollable list with an "infinite scroll" pattern, where new results are loaded automatically as the user scrolls to the bottom of the list.

When a user initiates a trademark search, the tool calls Signa's search endpoint with the default page size of 25. The response includes the first 25 results, a nextCursor value, and a totalCount of 847 matching records. The tool displays the first 25 results and shows a message indicating "Showing 1-25 of 847 results."

As the user scrolls to the bottom of the list, the tool sends a follow-up request with the cursor parameter set to the nextCursor value from the previous response. Signa returns the next 25 results along with a new nextCursor for subsequent pages. This continues as the user scrolls, loading results on demand without fetching the entire 847-record result set upfront.

The cursor-based approach ensures that this experience is seamless even if new trademark filings are added to Signa's database while the user is browsing results. The cursor maintains the user's position in the result set, preventing duplicates or gaps that could confuse the user. The total processing load is distributed across multiple small requests rather than a single large one, ensuring responsive performance for both the user and the API.