Skip to content

Paging, filters and search

Page through lists with cursors, filter and sort them, search them, and pass a read's arguments.

Updated

Every list below answers a page at a time, with a cursor to the next one. Two reads aren’t paged: GET /contacts answers an array, and GET /prompts answers { items, truncated }, where truncated: true means the list was cut short.

curl 'https://api.sherpo.io/customer/v1/stores/yourstore.sherpo.io/products/slug:intro-course/entries?limit=2&count=true' \
  --header 'Publishable-Key: <publishable key>'
listEntries 200json
{
  "items": [
    { "id": "<entry id>", "slug": "welcome", "title": "Welcome", "position": 0, "access": "unlocked" },
    { "id": "<entry id>", "slug": "setting-up", "title": "Setting up", "position": 1, "access": "locked" }
  ],
  "cursor": "eyJrIjpbMV19",
  "total": 12
}

Here and in every guide, an example answer is trimmed to the fields it’s about; the reference lists every field.

Pages

Parameter
limit Items per page: 20 unless you ask, at most 100. A portfolio’s snapshots page 100 at a time, at most 400.
cursor The cursor of the page before, to read the next one. Leave it out for the first page.
count true adds total, how many items match in all.

A page answers { items, cursor }, and total when you asked for it. On a product’s reviews, total counts the reviews shown, so it can be lower than the product’s rating.count, which counts every rating. While cursor isn’t null, more items follow: pass it back, with the same filters, sort and search, for the next page. The answer also names the next page in a Link: <...>; rel="next" header. A cursor of null is the end.

Sort

sort names one of the list’s orders (below), and direction (asc or desc) the direction of its leading field; asking for the other direction reverses the whole order. Without sort, a list takes its default order.

Filters

filter[<field>]=<value> keeps the items whose field equals the value. filter[<field>][<op>]=<value> names the operator:

  • eq: equals, the same as filter[<field>]=<value>;
  • in: equals any of the values, the parameter repeated once per value;
  • gte and lte: at least, and at most.
filter[status][in]=active&filter[status][in]=past_due
filter[occurred_at][gte]=2026-01-01T00:00:00.000Z
filter[rating][gte]=4

A timestamp is an ISO 8601 time, a date a calendar day (2026-11-03), a boolean true or false. A filter, operator, sort or value the list doesn’t declare is refused as 422 invalid, never ignored.

search=<words> keeps the items whose fields match, on lists that offer it (below), and takes up to 200 characters; a longer one is refused as invalid. While searching, an empty page that still has a cursor means nothing matched so far, not the end: keep paging until cursor is null. A searched page past the counting budget comes back without total, even when you asked for it, which never means zero.

What each list takes

List Filters Sorts Search
Products category (eq, in), listing (eq: primary, secondary) catalog, published, title title, subtitle
Entries section (eq, in), tag (eq, in, ignoring case), published_at (gte, lte) position, published title, subtitle, preview
Entry sections value value
Entry tags value value
Pages in_menu (eq) title, menu title, description
Completions product_id (eq) completed
Notifications read (eq), type (eq, in: portfolio_trade, new_lesson, new_episode, new_post, new_file, new_product, new_discount, event_reminder, event_follow_up) created
Checkouts status (eq, in: open, frozen, paid, abandoned, expired), currency (eq) created
Orders source (eq, in: checkout, api, manual), occurred_at (gte, lte) occurred
Order lines line
Order refunds occurred
Subscriptions status (eq, in: active, past_due, paused, cancelled, ended, unpaid), product_id (eq) created
Grants product_id (eq) valid_from
Entitlements product_id (eq) product, title
Reviews rating (eq, in, gte, lte) created, rating
Quiz attempts entry_id (eq), quiz_id (eq), status (eq, in: started, passed, failed, forfeited) started
Certificates product_id (eq), entry_id (eq) issued
Licenses created
License devices status (eq, in: active, inactive, deactivated) activated, last_seen
Portfolio events type (eq, in), symbol (eq, in), occurred_at (gte, lte) occurred symbol, note, name
Software activity type (eq, in: release, note), occurred_at (gte, lte) occurred version, body
Portfolio snapshots date (gte, lte) date

Each list’s first sort is its default, except a blog’s or a podcast’s entries, which list newest first (published).

Completions, quiz attempts and certificates list the customer’s across every product at the top level, and one product’s under it, with the same filters and sorts: GET /products/{product}/completions, GET /products/{product}/attempts and GET /products/{product}/certificates. Prompts do the same, at GET /prompts and GET /products/{product}/prompts.

A read’s other arguments

A read (GET) takes its arguments in the query string:

  • a scalar as it is: runnable=true, coupon=WELCOME10;
  • an object one level deep, each field in brackets: target[kind]=entry&target[id]=<entry id>;
  • an array by repeating the parameter: include=body, kinds=summary&kinds=chapters;
  • a reference as its id, or slug:<slug> where the kind has slugs: product=slug:intro-course.

A write (POST, PUT, PATCH, DELETE) takes its other arguments, if any, in a JSON body; the ids its path names stay out of it.

Type to search…

↑↓ navigate↵ selectEsc close