# Lists and filters > What list endpoints return, how to page through and filter them, and how to treat IDs. Source: https://abuna.app/docs/lists-and-filters Every list endpoint returns its items newest first, one page at a time, in the same shape. Products, prices, customers, subscriptions, invoices, sessions, events, webhook deliveries, and customer messages (notices) all work this way. ## Pages A list returns an object with two fields: - `items`: the page, newest first. `[]` when nothing matches. - `next_cursor`: a string to get the next page, or `null` on the last one. Treat it as opaque. **A page** ```json { "items": [ { "id": "x9QbL2sK", "status": "active", "created_at": 1727600000 } ], "next_cursor": "eDlRYkwyc0s" } ``` Two query parameters control paging: - `limit`: how many items to return, from 1 to 100. It defaults to 50. A value outside 1 to 100 returns `422` with code `invalid` and an `errors` item for `limit`. - `cursor`: the `next_cursor` from the page before. Send the same filters and `limit` with it. Paging never skips or repeats an item, even when many items share a `created_at`. For events, use [Catch up on missed events](https://abuna.app/docs/api/events.md#catch-up). **Read every page** Node.js: ```javascript const base = "https://api.abuna.app/v1/apps/8ddhXCDW/customers?limit=100"; const headers = { Authorization: "Bearer sk_test_..." }; const customers = []; let cursor = null; do { const url = base + (cursor ? "&cursor=" + encodeURIComponent(cursor) : ""); const page = await (await fetch(url, { headers })).json(); customers.push(...page.items); cursor = page.next_cursor; } while (cursor); ``` Python: ```python import requests base = "https://api.abuna.app/v1/apps/8ddhXCDW/customers" headers = {"Authorization": "Bearer sk_test_..."} customers = [] params = {"limit": 100} while True: page = requests.get(base, headers=headers, params=params).json() customers.extend(page["items"]) if page["next_cursor"] is None: break params["cursor"] = page["next_cursor"] ``` The prices list includes archived prices. An archived price has a timestamp in `archived_at`. ## IDs Treat every ID as an opaque string. Don't parse it, and don't assume its length or what characters it has: objects created before launch can have longer IDs than new ones. Don't sort by ID either. The one exception is event IDs, which sort in the order the events happened. See [Event order](https://abuna.app/docs/api/events.md#order). ## Filters Send filters as query parameters. The API ignores a blank filter. A `status` it doesn't know returns `422` with code `invalid`. - **Invoices**: `status` is `open`, `paid`, `void`, or `overdue`. `search` matches part of the number, name, or email, ignoring case. `from` and `to` bound the issue date in Unix seconds. `customer_id` is one customer's ID. - **Sessions**: `type` is `checkout`, `payment`, `plan_change`, `cancel`, or `portal`. `status` is `open`, `completed`, or `expired`. `subscription_id` is one subscription's ID. - **Customers**: `search` matches part of the name or email, ignoring case. - **Subscriptions**: `status` is `pending`, `active`, `past_due`, or `canceled`. `customer_id` is one customer's ID. `email` matches part of the customer's email, ignoring case. - **Events**: `type` is one event type, such as `invoice.paid`. - **Webhook deliveries**: `type` is one event type. `status` is `pending`, `delivering`, `delivered`, or `failed`. - **Customer messages**: `subscription_id` is one subscription's ID. `status` is `pending`, `sending`, `sent`, `failed`, or `withdrawn`. Filters combine, so a list returns only items that match all of them. **GET /v1/apps/{appID}/subscriptions** cURL: ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA" \ -H "Authorization: Bearer sk_test_..." ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python: ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP: ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go: ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ```