Pagination

Learn how to paginate api.vision results to manage large datasets efficiently.

Basic Pagination

To paginate results, use the page and limit query parameters:

GET /posts?page=2&limit=10

This fetches the second page of results, with 10 items per page.

page: The page number (starting from 1)
limit: The number of items per page

If you don't specify these parameters, api.vision uses default values:

Default page: 1
Default limit: 20

Pagination Headers

When using pagination, api.vision includes helpful headers in the response:

Header	Description
`X-Total-Count`	Total number of resources matching the query
`X-Total-Pages`	Total number of pages available
`X-Page`	Current page number
`X-Limit`	Number of items per page
`Link`	Navigation links for next, prev, first, last pages (following RFC 5988)

Example response headers:

X-Total-Count: 142
X-Total-Pages: 15
X-Page: 2
X-Limit: 10
Link: <https://api.vision/yourid/posts?page=1&limit=10>; rel="first", 
      <https://api.vision/yourid/posts?page=1&limit=10>; rel="prev", 
      <https://api.vision/yourid/posts?page=3&limit=10>; rel="next", 
      <https://api.vision/yourid/posts?page=15&limit=10>; rel="last"

Offset Pagination

For more control, you can use offset-based pagination with the offset and limit parameters:

GET /posts?offset=20&limit=10

This skips the first 20 items and returns the next 10 items.

offset: The number of items to skip
limit: The number of items to return

Note: You can use either page-based (page and limit) or offset-based (offset and limit) pagination, but not both in the same request.

Cursor-Based Pagination

For large datasets or frequently changing data, cursor-based pagination provides better performance and consistency. Use the cursor and limit parameters:

GET /posts?cursor=eyJpZCI6MTAwfQ==&limit=10

The cursor is a base64-encoded string that points to a specific item in the dataset. The response includes a next_cursor value that you can use for the next page.

How Cursor Pagination Works

Make an initial request without a cursor to get the first page
The response includes a next_cursor value in the response body (if there are more items)
For the next page, use the received cursor in your next request

// First request
GET /posts?limit=10

// Response includes next_cursor
{
  "data": [ ... ],
  "next_cursor": "eyJpZCI6MTB9=="
}

// Next request uses the cursor
GET /posts?cursor=eyJpZCI6MTB9==&limit=10

Tip: Cursor-based pagination is recommended for:

Data that changes frequently
Large datasets (millions of records)
Use cases requiring consistent results across page navigation

Combining Pagination with Other Query Features

Pagination can be combined with filtering, sorting, and other query features:

GET /products?category=electronics&price_gte=100&sort=-rating,price&page=1&limit=20

The pagination applies after filtering and sorting, so you get the first page of the filtered and sorted results.

Efficient Pagination Strategies

Choose the Right Pagination Method

Method	Best For	Considerations
Page-based	User interfaces with page numbers Static data Simplicity	Inefficient with large offsets Can duplicate/miss items if data changes
Offset-based	Random access to pages "Skip to page" functionality	Performance degrades with large offsets Can duplicate/miss items if data changes
Cursor-based	Large datasets Frequently changing data Infinite scrolling	Can't jump to arbitrary pages More complex implementation

Optimizing Page Size

Choose an appropriate page size for your use case:

Too small: Increased number of requests
Too large: Slower response times and higher resource usage
Typical ranges: 10-50 items for UI display, 100-1000 for data exports

Best Practice

Always use pagination when dealing with collections that could return large numbers of items. Even if you need all items, fetching them in manageable chunks improves performance and user experience.