Docs
OverviewPlatformPlatform APIA2P Messaging API
AI & MCP
Open dashboard
OverviewPlatformPlatform APIA2P Messaging API
AI & MCP
  • Overview
  • Introduction
  • Create an account
  • Choose your API
  • Authentication
  • AI & MCP
Product API
  • Guide
  • Quickstart
    • API tokens
    • Connected apps (OAuth)
    • Project readiness
    • Channel readiness
    • Senders
    • Attention
    • Recommendations
    • Overview
    • Contacts and attributes
    • Events
    • Query filter
    • Event query filter
    • Probes
    • Counting and retrieval
    • Segments
    • Overview
    • Creating a draft
    • Audience targeting
    • Message content
    • Dates and scheduling
    • Reading campaigns
    • Estimating and deleting
    • OverviewBeta
    • Templates
    • Creating and editing drafts
    • Triggers and exits
    • Nodes
    • Delays and waits
    • Overview
    • Statistics catalog
    • Building queries
    • Conversions & revenue
    • Reading results
    • Flow reports
    • Rate limits
    • Errors
  • Full API Reference
Ingest API
  • Guide
  • Quickstart
  • Authentication
  • Rate limits
  • Errors
  • Full API Reference
Further reading
  • Query Filter
DashboardSupportinstasent.com

Platform API · Further reading

Query Filter

Shared syntax for filtering, sorting, paginating and grouping results on the Product API's list endpoints. Two equivalent formats: URL query string or a JSON _q parameter.

On this page▾
  • Quickstart
  • URL query string format
  • Filters
  • Sorting
  • Pagination
  • Grouping
  • Nested fields
  • Date formats
  • Array values
  • JSON _q format
  • Shape
  • Filter condition
  • Combining with AND / OR
  • Operators reference
  • Generic
  • Comparison
  • Numeric comparison
  • List
  • String
  • Range
  • Logical
  • Common patterns
  • Complete example

The list endpoints of the Product API — datasources, segments, campaigns, automations, senders and message listings — accept the same Query Filter (QF) syntax. You can express the same query in two equivalent formats: compact URL query string parameters, or a richer JSON _q parameter for conditions that need AND/OR logic.

Pick whichever is cleaner for the case at hand — the server parses both into the same internal structure.

QF is the generic filter system for the Product API's list endpoints. It is distinct from the Audience query filter (AQF) and Audience event query filter (EQF), which are separate systems specific to Product API audiences and events with their own syntax and capabilities. Similar names, independent semantics.

Quickstart

Filter by status:

GET /api/endpoint?status_eq=estimated

Filter with multiple conditions (combined with AND):

GET /api/endpoint?number_eq=34600000000&age_gte=35

URL query string format

The URL format packs filters, sorting, pagination and grouping into a compact set of query parameters. Use it when conditions combine with AND and the query is small enough to read in a URL.

Filters

  • Field and operator are joined by an underscore: field_operator=value.
  • Multiple filter parameters combine with & — implicit AND.
  • Any URL parameter that is not a reserved keyword (_sort, _start, _limit, _group, _q) is treated as a filter.
?number_eq=34600000000&age_gte=35

Sorting

  • Parameter: _sort.
  • Fields separated by commas.
  • Direction appended with : — - for descending, + or nothing for ascending (default).
?_sort=name,surname:-

Sorts by name ascending, then surname descending.

Pagination

Parameters _start and _limit. Both must be set or both omitted.

?_start=0&_limit=10

Grouping

For aggregate queries on statistics / reports endpoints.

  • Parameter: _group.
  • The value is not necessarily an existing field — tokens like hourly, daily, monthly are valid.
?_group=daily

Nested fields

Reference nested object fields with * as the path separator.

?age_gte=35&attributes*drink_eq=beer

Filters by age >= 35 AND attributes.drink == "beer".

Date formats

URL parameter values are strings; the server coerces them based on the field type. For date fields, the accepted formats are:

  • ISO 8601 — 2019-05-08T10:25:12+02:00
  • Microseconds (UTC) — 2019-05-08T10:25:12.715
  • Relative — 1 day ago. Valid periods: second, minute, hour, day, month, year.
?createdAt_gte=2019-05-08T10:25:12+02:00
?createdAt_gte=1 day ago

Array values

For operators that accept a list of values, separate items with |.

?age_betweeneq=18|35&name_in=david|daniel|marta

Filters by age between 18 and 35 (inclusive) AND name in ["david", "daniel", "marta"].

JSON _q format

For queries that need AND/OR logic or structured conditions, send a JSON object as the _q URL parameter.

Shape

{
  "filter": [
    { "field": "status", "operator": "eq", "value": "estimated" }
  ],
  "paging": { "start": 0, "limit": 20 },
  "sort": [["status", "asc"]],
  "group": "status"
}

Top-level keys:

  • filter — array of filter conditions.
  • paging — { start, limit }. Both must be present together.
  • sort — array of [field, direction] tuples. Direction is "asc" or "desc".
  • group — grouping expression (same semantics as _group).

Filter condition

Each entry in filter has three properties:

  • field — field name, or "" when combining sub-conditions.
  • operator — comparison operator (see Operators reference).
  • value — value to compare against. For list operators this is an array.

Combining with AND / OR

Nest sub-conditions with an empty field and operator: "and" | "or":

{
  "filter": [
    {
      "field": "",
      "operator": "or",
      "value": [
        { "field": "status", "operator": "eq", "value": "draft" },
        { "field": "status", "operator": "eq", "value": "confirmed" }
      ]
    },
    {
      "field": "deliveredText",
      "operator": "eq",
      "value": "Your activation code is 4812"
    }
  ]
}

Reads as: (status == "draft" OR status == "confirmed") AND deliveredText == "Your activation code is 4812".

Operators reference

Generic

OperatorDescriptionField types
existsField is present. Boolean check.Any

Comparison

OperatorDescriptionField types
eqEquals (exact match).String, number, date, id/ref
eqiEquals, case-insensitive.String
neNot equals.String, number, date, id/ref
neiNot equals, case-insensitive.String

Numeric comparison

OperatorDescriptionField types
ltLess than.Number, date
lteLess than or equal.Number, date
gtGreater than.Number, date
gteGreater than or equal.Number, date

List

OperatorDescriptionField types
inValue is in the list.String, id/ref
iniValue is in the list, case-insensitive.String
ninValue is not in the list.String, id/ref
niniValue is not in the list, case-insensitive.String

List operators take the value as an array.

String

OperatorDescriptionField types
containsContains substring.String
containsiContains substring, case-insensitive.String
ncontainsDoes not contain substring.String
ncontainsiDoes not contain substring, case-insensitive.String
startsStarts with.String
startsiStarts with, case-insensitive.String
endsEnds with.String
endsiEnds with, case-insensitive.String

All string operators also accept arrays of values.

Range

OperatorDescriptionBounds
rangeWithin range [min, max].min inclusive, max exclusive
betweenBetween [min, max].Both exclusive
betweeneqBetween [min, max], inclusive.Both inclusive

Range operators apply to number and date fields only. Value is always a two-element array.

Logical

OperatorDescription
andAll nested conditions must match. Used with empty field.
orAt least one nested condition must match. Used with empty field.

Common patterns

Filtering by status:

GET /api/endpoint?status_eq=estimated

Multiple AND conditions:

GET /api/endpoint?status_eq=confirmed&age_gte=18&age_lte=65

OR between two conditions:

GET /api/endpoint?status_eq=draft&status_eq=confirmed

In the URL format, repeating the same field_op (e.g. status_eq=draft&status_eq=confirmed) is interpreted as OR for that field. Whenever the intent is not obvious at a glance, prefer the JSON format — the explicit or operator is easier to read and safer for LLM-generated queries.

Date range:

GET /api/endpoint?createdAt_gte=2019-05-08T10:25:12%2B02:00&createdAt_lt=2019-06-08T10:25:12%2B02:00

Relative date:

GET /api/endpoint?createdAt_gte=1 day ago

Value in list:

GET /api/endpoint?name_in=david|daniel|marta

Nested fields:

GET /api/endpoint?attributes*drink_eq=beer

Filter + sort + paginate together:

GET /api/endpoint?status_eq=confirmed&_sort=createdAt:-&_start=0&_limit=20

Complete example

A query that filters by (status == "draft" OR status == "confirmed") AND a specific delivered text, paginated, sorted and grouped:

{
  "filter": [
    {
      "field": "",
      "operator": "or",
      "value": [
        { "field": "status", "operator": "eq", "value": "draft" },
        { "field": "status", "operator": "eq", "value": "confirmed" }
      ]
    },
    {
      "field": "deliveredText",
      "operator": "eq",
      "value": "Your activation code is 4812"
    }
  ],
  "paging": { "start": 0, "limit": 20 },
  "sort": [["status", "asc"]],
  "group": "status"
}

Last updated September 30, 2026

PreviousFull API Reference
  • Quickstart
  • URL query string format
  • Filters
  • Sorting
  • Pagination
  • Grouping
  • Nested fields
  • Date formats
  • Array values
  • JSON _q format
  • Shape
  • Filter condition
  • Combining with AND / OR
  • Operators reference
  • Generic
  • Comparison
  • Numeric comparison
  • List
  • String
  • Range
  • Logical
  • Common patterns
  • Complete example

© 2026 Instasent

Privacy PolicyTerms & ConditionsCookie PolicyLegal Notice
All systems operational