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 theq[]grammar, for reading and listing: look up a customer, filter orders, paginate a report. QON 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'sq[], 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/1for ascending,DESC/desc/0for 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-31means2026-08-31 00:00:00— everything that happened during the 31st is left out. Either go to23:59:59, or useB(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]=completeddoes the same asq[status][E]=completed. - Column names differ per service. It is
createdAtin register andorder_date/createAtin order — use the same name the endpoint returns. e=0(ore=all) removes the limit. On a large base that is a huge response and an expensive query; prefer paginating.