---
title: 'List query parameters'
description: 'Filter, sort and paginate any list endpoint with q[]/o[]/e/p syntax.'
---

# List query parameters

Every list endpoint in the Guper API understands a shared querystring grammar for filtering, sorting and pagination. Once you know it for one resource it works the same on every other.

> **`q[]` or QON?** This is the `q[]` grammar, for **reading and listing**: look up a customer, filter orders, paginate a report. [QON](/docs/{lang}/api-reference/register/audience-query/qon-query) is a different thing — nested JSON expressions used **only to build an audience** in the segmentation builder. To find a customer by tax ID or email, it's `q[]`, here — not QON.

## Filtering — `q[column][operator]=value`

```
q[column][operator]=value
```

- **`column`** — can be composite, separated by `;` or `|`.
- **`operator`** — one of:

| Operator | Meaning | SQL equivalent |
|---|---|---|
| `E` | equal | `=` |
| `!E` | not equal | `!=` |
| `B` | before | `<` |
| `BE` | before or equal | `<=` |
| `A` | after | `>` |
| `AE` | after or equal | `>=` |
| `IS` | is | `IS NULL` |
| `!IS` | not is | `IS NOT NULL` |
| `IN` | in set | `IN (1, 2, …)` |
| `!IN` | not in set | `NOT IN (1, 2, …)` |
| `L` | like | `LIKE "value"` |
| `!L` | not like | `NOT LIKE "value"` |
| `LL` | left-like | `LIKE "%value"` |
| `!LL` | not left-like | `NOT LIKE "%value"` |
| `RL` | right-like | `LIKE "value%"` |
| `!RL` | not right-like | `NOT LIKE "value%"` |
| `LRL` | left+right like | `LIKE "%value%"` |
| `!LRL` | not left+right like | `NOT LIKE "%value%"` |
| `S` | search | term-based search across one or more columns |

### Multiple values

Operators that accept multiple values must be configured in sequence:

```
q[column][IN]=1&q[column][]=2&q[column][]=3
```

Generates `column IN (1, 2, 3)`.

### NULL filter

```
q[column][IS]=null
```

## Sorting — `o[column]=dir`

```
o[column]=dir
```

- **`column`** — column to sort by.
- **`dir`** — `ASC` / `asc` / `1` for ascending, `DESC` / `desc` / `0` for descending.

## Pagination — `e=entries&p=page`

| Param | Default | Notes |
|---|---|---|
| `e` (entries) | `20` | Items per page. Max `1000`. `0` means unlimited. |
| `p` (page) | `1` | Minimum `1`. |

## Examples

### Date range

The same column takes **two operators in one query** — that is how you build a range:

```
GET /api/register/customer?q[createdAt][AE]=2026-08-01 00:00:00&q[createdAt][BE]=2026-08-31 23:59:59
```

Produces `createdAt >= '2026-08-01 00:00:00' AND createdAt <= '2026-08-31 23:59:59'`.

> **Careful with a bare date on `BE`.** `q[createdAt][BE]=2026-08-31` means `2026-08-31 00:00:00` — everything that happened **during** the 31st is left out. Either go to `23:59:59`, or use `B` (less than) on the next day:
>
> ```
> q[createdAt][AE]=2026-08-01&q[createdAt][B]=2026-09-01
> ```

One-sided ranges work too:

```
q[order_date][AE]=2026-08-01     → from August 1st onwards
q[order_date][B]=2026-08-01      → before August 1st
```

Remember to URL-encode the values: a space becomes `%20` (or `+`), so `2026-08-01 00:00:00` becomes `2026-08-01%2000%3A00%3A00`.

### Customer by exact email

```
GET /api/register/customer?q[email][E]=maria@example.com
```

Looking a customer up **is this** — the filtered listing. Do not use `create` or `get-or-create` to search: they write, and will create the very customer you were only looking for.

### A fragment of the text

```
GET /api/register/customer?q[name][LRL]=silva
```

`LRL` means "contains" (`LIKE '%silva%'`). Since it matches any fragment, `q[email][LRL]=x@gmail.com` also returns `maria.mx@gmail.com` — for real duplicates, use `E`.

### Search across several columns at once

```
GET /api/register/customer?q[name;email][S]=maria silva
```

The term is split on whitespace: **each word** must appear in **at least one** of the columns. Words combine with `AND`, columns with `OR`.

### Several values on the same column

```
GET /api/order/data?q[status][IN]=completed&q[status][]=shipped
```

### Set or empty

```
q[canceledAt][IS]=null      → only the ones not canceled
q[canceledAt][!IS]=null     → only the canceled ones
```

### All together

```
GET /api/order/data?q[status][E]=completed&q[order_date][AE]=2026-08-01&q[order_date][B]=2026-09-01&o[order_date]=desc&e=50&p=2
```

Second page of 50 orders completed in August 2026, newest first.

## Before you start filtering

- **A non-filterable column is dropped silently.** Some resources restrict which columns accept filters; anything else is discarded without an error — and the response comes back **without that filter**, with more rows than you expected. Check the result instead of assuming.
- **No operator means equality**: `q[status]=completed` does the same as `q[status][E]=completed`.
- **Column names differ per service.** It is `createdAt` in register and `order_date` / `createAt` in order — use the same name the endpoint returns.
- **`e=0` (or `e=all`) removes the limit.** On a large base that is a huge response and an expensive query; prefer paginating.
