Sign in
.md

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 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.