Mixedbread

Pagination

Understanding cursor-based pagination across Mixedbread API endpoints. Learn how to navigate through large result sets efficiently using cursors, handle pagination parameters, and implement robust pagination logic.

Overview

Mixedbread API uses cursor-based pagination for endpoints that return large result sets. This approach provides consistent performance regardless of dataset size and ensures reliable pagination even when data is being modified.

Supported Endpoints

Cursor-based pagination is used for:

Pagination Parameters

Request Parameters

Include these query parameters in your requests:

ParameterTypeDescriptionDefault
beforestringCursor for pagination. Returns items before this cursor.-
afterstringCursor for pagination. Returns items after this cursor.-
limitintegerMaximum number of items to return (1-100).20

Important Notes:

  • Use either before OR after, not both
  • Cursors are opaque strings - don't parse or modify them
  • Always include limit to control result size

Response Format

All paginated responses include:

{
  "data": [...],
  "pagination": {
    "first_cursor": "eyJpZCI6InZzXzEyMyJ9",
    "last_cursor": "eyJpZCI6InZzXzQ1NiJ9", 
    "has_more": true
  }
}
FieldTypeDescription
dataarrayThe actual results for the current page
first_cursorstringCursor pointing to the first item in current page
last_cursorstringCursor pointing to the last item in current page
has_morebooleanWhether more results are available

Forward Pagination

Start with no cursor to get the first page:

GET /v1/stores?limit=10

Continue with last_cursor from the previous response:

GET /v1/stores?after=eyJpZCI6InZzXzQ1NiJ9&limit=10

Backward Pagination

Use first_cursor with before parameter:

GET /v1/stores?before=eyJpZCI6InZzXzEyMyJ9&limit=10
Cursor pagination demo: 13 stores listed with a demo limit of 4 (the API default is 20). The first request, GET /v1/stores?limit=4, sends no cursor and returns the first 4 stores with a pagination object whose first_cursor and last_cursor point at the first and last store on the page, and has_more: true. Next sends GET /v1/stores?limit=4&after={last_cursor} for the following 4 stores; Previous sends GET /v1/stores?limit=4&before={first_cursor} for the 4 before them. Each request uses only one of before or after, and cursors are opaque strings copied from the previous response. The fourth page holds only the last store and returns has_more: false, so there is no next request. has_more follows the direction of the request: after a before request it tells whether more stores exist before the page.
{
  "data": [...],
  "pagination": {
    "first_cursor": "k2Vd9x",
    "last_cursor": "Hy5uBn",
    "has_more": true
  }
}

has_more refers to stores after this page, the direction of this request.

First page: nothing before it

GET /v1/stores?limit=4&after=Hy5uBn

The demo uses limit=4 so 13 stores span 4 pages; the API default is 20.

On this page

OverviewSupported EndpointsPagination ParametersRequest ParametersResponse FormatNavigation PatternsForward PaginationBackward Pagination