Skip to main content
Every endpoint that returns many items returns a list, and you page through it with a cursor. A list has the same shape everywhere:
  • data. The items on this page.
  • has_more. true when another page follows.
  • next_cursor. Pass it as cursor to get the next page. null on the last page.
  • total. How many items match. Counting stops at 10,000, and relation is then gte, meaning at least that many.

​
Parameters

​
integer
default:"25"
The page size, at most 100. A few sub-lists use fixed pages of 25 rows, and limit can only make those smaller: a shop’s products, a shop’s reviews, a product’s reviews and related keywords.
​
string
The next_cursor of the previous page. A cursor works only with the request that made it: the same endpoint, filters, sort, key and workspace. Change any of them and the answer is 400 invalid_cursor. Start again without a cursor.

​
Example

Fetch the first page, then pass next_cursor back with the same query:
Find products has a paging loop in curl, TypeScript and Python.

​
Limits

  • 10,000 results. Paging stops there with 400 cursor_window_exceeded. Narrow the query to reach further.
  • Stable order. Ties are broken by ID, so a page boundary never splits two equal items. Values can change between pages, so an item can still move.
  • MCP pages. Through MCP, pages default to 20 items and hold at most 50.
  • Cost. A search costs the same per page whatever limit is. Use limit=100 when you want many results.

​
Choosing fields

fields takes comma-separated dotted paths and returns only those. id, object and as_of always come back.
An unknown path answers 400 invalid_request, with the valid paths in valid_fields. fields never changes the price of a call. Some endpoints take expand to include related objects in the same response, for free: An expansion never fetches anything from Etsy. When Alura has no data for it, the field is null.