---
title: "Paging, filters and search"
description: "Page through lists with cursors, filter and sort them, search them, and pass a read's arguments."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Paging, filters and search

Every list below answers a page at a time, with a cursor to the next one. Two reads aren't paged: [`GET /contacts`](/customer-api/reference/list-contacts) answers an array, and [`GET /prompts`](/customer-api/reference/list-prompts) answers `{ items, truncated }`, where `truncated: true` means the list was cut short.

```bash
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>'
```

```json title="listEntries 200"
{
  "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](/customer-api/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.

```text
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`](/customer-api/errors#invalid), never ignored.

## Search

`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](/customer-api/reference/list-products) | `category` (`eq`, `in`), `listing` (`eq`: `primary`, `secondary`) | `catalog`, `published`, `title` | `title`, `subtitle` |
| [Entries](/customer-api/reference/list-entries) | `section` (`eq`, `in`), `tag` (`eq`, `in`, ignoring case), `published_at` (`gte`, `lte`) | `position`, `published` | `title`, `subtitle`, `preview` |
| [Entry sections](/customer-api/reference/list-entry-sections) | | `value` | `value` |
| [Entry tags](/customer-api/reference/list-entry-tags) | | `value` | `value` |
| [Pages](/customer-api/reference/list-pages) | `in_menu` (`eq`) | `title`, `menu` | `title`, `description` |
| [Completions](/customer-api/reference/list-completions) | `product_id` (`eq`) | `completed` | |
| [Notifications](/customer-api/reference/list-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](/customer-api/reference/list-checkouts) | `status` (`eq`, `in`: `open`, `frozen`, `paid`, `abandoned`, `expired`), `currency` (`eq`) | `created` | |
| [Orders](/customer-api/reference/list-orders) | `source` (`eq`, `in`: `checkout`, `api`, `manual`), `occurred_at` (`gte`, `lte`) | `occurred` | |
| [Order lines](/customer-api/reference/list-order-items) | | `line` | |
| [Order refunds](/customer-api/reference/list-order-refunds) | | `occurred` | |
| [Subscriptions](/customer-api/reference/list-subscriptions) | `status` (`eq`, `in`: `active`, `past_due`, `paused`, `cancelled`, `ended`, `unpaid`), `product_id` (`eq`) | `created` | |
| [Grants](/customer-api/reference/list-grants) | `product_id` (`eq`) | `valid_from` | |
| [Entitlements](/customer-api/reference/list-entitlements) | `product_id` (`eq`) | `product`, `title` | |
| [Reviews](/customer-api/reference/list-reviews) | `rating` (`eq`, `in`, `gte`, `lte`) | `created`, `rating` | |
| [Quiz attempts](/customer-api/reference/list-attempts) | `entry_id` (`eq`), `quiz_id` (`eq`), `status` (`eq`, `in`: `started`, `passed`, `failed`, `forfeited`) | `started` | |
| [Certificates](/customer-api/reference/list-certificates) | `product_id` (`eq`), `entry_id` (`eq`) | `issued` | |
| [Licenses](/customer-api/reference/list-licenses) | | `created` | |
| [License devices](/customer-api/reference/list-license-activations) | `status` (`eq`, `in`: `active`, `inactive`, `deactivated`) | `activated`, `last_seen` | |
| [Portfolio events](/customer-api/reference/list-portfolio-events) | `type` (`eq`, `in`), `symbol` (`eq`, `in`), `occurred_at` (`gte`, `lte`) | `occurred` | `symbol`, `note`, `name` |
| [Software activity](/customer-api/reference/list-software-events) | `type` (`eq`, `in`: `release`, `note`), `occurred_at` (`gte`, `lte`) | `occurred` | `version`, `body` |
| [Portfolio snapshots](/customer-api/reference/list-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`](/customer-api/reference/list-product-completions), [`GET /products/{product}/attempts`](/customer-api/reference/list-product-attempts) and [`GET /products/{product}/certificates`](/customer-api/reference/list-product-certificates). Prompts do the same, at [`GET /prompts`](/customer-api/reference/list-prompts) and [`GET /products/{product}/prompts`](/customer-api/reference/list-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.

Source: https://docs.sherpo.io/customer-api/pagination/index.mdx
