Pagination

Search results are returned one page at a time. Instead of asking for a page number, you follow a cursor — a token that points to the next page. This keeps paging fast and consistent even while new photos are being added.

The `pagination` object

Every list response includes a pagination object next to your data:

{
  "success": true,
  "data": [ /* photos for this page */ ],
  "pagination": {
    "per_page": 20,
    "has_more": true,
    "next_cursor": "eyJycyI6Ij... (opaque token)"
  }
}

Field	Meaning
`per_page`	How many photos are on each page. You choose this on the first request with `per_page` (1–100, default 20).
`has_more`	`true` if there is at least one more page after this one.
`next_cursor`	The token to pass as `cursor` to get the next page. It is `null` when `has_more` is `false`.

Fetching the next page

Make your search as usual.
Read pagination.next_cursor from the response.
Repeat the same request, adding cursor=<next_cursor>.
Stop when has_more is false (at that point next_cursor is null).

curl "https://api.pexafy.com/api/v1/search/photos?q=a+child+discovering+snow+for+the+first+time&per_page=20" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://api.pexafy.com/api/v1/search/photos?q=a+child+discovering+snow+for+the+first+time&per_page=20&cursor=PASTE_next_cursor_HERE" \
  -H "x-api-key: YOUR_API_KEY"

Here is the same loop in Python:

import requests

BASE = "https://api.pexafy.com/api/v1/search/photos"
headers = {"x-api-key": "YOUR_API_KEY"}
params = {"q": "a child discovering snow for the first time", "per_page": 20}

photos = []
while True:
    r = requests.get(BASE, headers=headers, params=params).json()
    photos.extend(r["data"])
    page = r["pagination"]
    if not page["has_more"]:
        break
    params["cursor"] = page["next_cursor"]   # follow the cursor

print(f"Collected {len(photos)} photos")

Keep your query the same between pages. The cursor already remembers your search text and filters, so you only need to add cursor. Set per_page on the first request; following pages keep that same page size.

Cursors are short-lived — they stay valid for about 5 minutes. If a cursor expires (or you change the query), simply start again from the first page without a cursor.

Which endpoints paginate?

Three search endpoints support cursor pagination:

Search photos by text — GET /api/v1/search/photos
Search photos by image — POST /api/v1/search/photos
Find similar photos — GET /api/v1/photos/{photo_id}/similar

They all work the same way: read pagination.next_cursor and pass it back as cursor to get the next page, stopping when has_more is false. (On some plans the number of similar photos is capped to a single page — in that case has_more is false from the start.)

For image search, you only upload the image on the first request. To get the next page, send the request again with just cursor=<next_cursor> — no need to re-upload the image. The cursor already remembers your image and filters.

The other endpoints return a single response and do not take a cursor: facets, collections and usage return their full list directly.

Getting Started

AI Assistants (MCP)

Search

Photos

Facets

Collections

Usage

Fetching the next page

Which endpoints paginate?

​The pagination object

​Fetching the next page

​Which endpoints paginate?

The `pagination` object

Fetching the next page

Which endpoints paginate?