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
  • Best practices
  • Full API Reference
Further reading
  • Query Filter
DashboardSupportinstasent.com

Platform API · Product API · Audience

Audience event query filter

Search and aggregate audience events with a structured JSON filter. Group by event type, filter on parameters, run date histograms and sum metrics across the last N days.

On this page▾
  • Quickstart
  • All create events from the last 30 days
  • Ecommerce orders between €100 and €200
  • Basic concepts
  • Filter structure
  • Condition types
  • Native event attributes
  • Event parameters
  • Common patterns
  • By event type and source
  • Date range
  • Events for specific contacts
  • Additional filter options
  • Cursor-based pagination
  • How it works
  • Cursor format
  • Using cursors
  • Aggregations
  • Date histogram
  • Date histogram with nested aggregations
  • Fixed interval vs calendar interval
  • Terms aggregation
  • Terms with nested aggregations
  • Sum aggregation
  • Complete sales analysis
  • Listing event types in a project
  • Range aggregations
  • Operators reference
  • Generic
  • Boolean
  • String
  • Numeric
  • Date
  • Geographic
  • values shape — quick reference
  • Date histogram parameters
  • Terms aggregation parameters
  • What's next

The Audience Event Query Filter (EQF) is a structured JSON filter posted to /project/{project}/event/search (and related event endpoints) to find events by type, parameters, creation date or any native event attribute. It shares the overall shape of the Audience query filter (AQF) but is specific to the event collection — the condition grammar is narrower and the aggregation surface is richer (date histograms, sums, metrics).

Event parameters live under the event type namespace. For a create event you filter on create.source; for an order you filter on ecommerce_order_create.order-euro-amount. Parameter keys are auto-resolved against the event type configuration of your project.

Probe before you filter. A filter on an event type that never arrives, or on a parameter value spelled differently in the data, returns 200 and nothing. POST /event/volumes reports which types this project actually receives inside a window, when the last one arrived, and, for one type, the real values its parameters hold. It accepts the same root documented on this page.

Quickstart

All create events from the last 30 days

{
  "version": "0.0.1",
  "root": {
    "type": "group",
    "join": "and",
    "children": [
      {
        "type": "event_condition",
        "key": "event-type",
        "operator": "matches-string",
        "values": ["create"]
      },
      {
        "type": "event_condition",
        "key": "created-at",
        "operator": "range-date-relative",
        "values": {
          "lowerOffset": -30,
          "upperOffset": null,
          "lowerExcludeEquals": false,
          "upperExcludeEquals": false,
          "lowerRounding": false,
          "upperRounding": false,
          "lowerOffsetPeriod": "day",
          "upperOffsetPeriod": "day"
        }
      }
    ]
  },
  "limit": 10,
  "offset": 0
}

Ecommerce orders between €100 and €200

{
  "version": "0.0.1",
  "root": {
    "type": "group",
    "join": "and",
    "children": [
      {
        "type": "event_condition",
        "key": "event-type",
        "operator": "matches-string",
        "values": ["ecommerce_order_create"]
      },
      {
        "type": "event_condition",
        "key": "ecommerce_order_create.order-euro-amount",
        "operator": "range-number",
        "values": {
          "lowerNumber": 100.0,
          "upperNumber": 200.0
        }
      }
    ]
  },
  "limit": 10,
  "offset": 0
}

Basic concepts

Filter structure

  • root — the main filter condition, typically a group of event conditions.
  • limit — maximum number of results to return.
  • offset — number of results to skip.
  • sortField — field to sort by (optional).
  • sortAsc — sort direction: true for ascending, false for descending (optional).

Condition types

  • event_condition — filter by a native event attribute or an event parameter.
  • group — combine multiple conditions with AND/OR logic (join: "and" | "or").

Native event attributes

Available directly as key in an event_condition:

AttributeMeaning
bucketBucket number.
received-atWhen the event was received.
created-atWhen the event was created.
event-sourceSource of the event.
event-typeType of event (e.g. create, update, ecommerce_order_create).
audience-idID of the audience contact.
audience-idsMultiple audience contact IDs.
audience-ds-idsAudience datasource IDs.
audience-categoriesAudience categories.
audience-target-groupsAudience target groups.
ds-contact-idDatasource contact ID.
ds-idDatasource ID.
ds-event-idDatasource event ID.

Event parameters

Filter by event-specific parameters by prefixing the key with the event type. Examples:

  • create.source — the source parameter of create events.
  • ecommerce_order_create.order-euro-amount — the order-euro-amount parameter of ecommerce_order_create events.

Parameter keys are auto-resolved based on the event type configuration of the project.

Common patterns

By event type and source

{
  "version": "0.0.1",
  "root": {
    "type": "group",
    "join": "and",
    "children": [
      {
        "type": "event_condition",
        "key": "event-type",
        "operator": "matches-string",
        "values": ["create"]
      },
      {
        "type": "event_condition",
        "key": "create.source",
        "operator": "matches-string",
        "values": ["datasource|_instasent"]
      }
    ]
  },
  "limit": 10,
  "offset": 0,
  "sortField": "create.source",
  "sortAsc": true
}

Date range

{
  "version": "0.0.1",
  "root": {
    "type": "group",
    "children": [
      {
        "type": "event_condition",
        "key": "created-at",
        "operator": "range-date-relative",
        "values": {
          "lowerOffset": -30,
          "upperOffset": null,
          "lowerExcludeEquals": false,
          "upperExcludeEquals": false,
          "lowerRounding": false,
          "upperRounding": false,
          "lowerOffsetPeriod": "day",
          "upperOffsetPeriod": "day"
        }
      }
    ]
  },
  "limit": 10,
  "offset": 0
}

Events for specific contacts

{
  "version": "0.0.1",
  "root": {
    "type": "group",
    "children": [
      {
        "type": "event_condition",
        "key": "audience-id",
        "operator": "matches-string",
        "values": ["0aCcUIewHALKk9jpaS9QaazifbmUr8fB"]
      }
    ]
  },
  "limit": 100,
  "offset": 0
}

Additional filter options

Top-level filters that narrow the result set without going through root:

FieldEffect
filterAudienceIdsRestrict to specific audience contact IDs.
filterEventIdsRestrict to specific event IDs.
filterEventIdsNotExclude specific event IDs.
filterDatasourceIdsRestrict to specific datasource IDs.
filterAudienceDatasourceIdsRestrict events for contacts from specific datasources.
filterSamplingPercentRetrieve only a percentage of results (0–100, default: 100).
filterBucketMinMinimum bucket number (0–100, default: 0).
filterBucketMaxMaximum bucket number (0–100, default: 100).

Example:

{
  "version": "0.0.1",
  "limit": 100,
  "offset": 0,
  "root": {
    "type": "group",
    "children": [
      {
        "type": "event_condition",
        "key": "event-type",
        "operator": "matches-string",
        "values": ["create"]
      }
    ]
  },
  "filterSamplingPercent": 33,
  "filterAudienceIds": ["0aCcUIewHALKk9jpaS9QaazifbmUr8fB"],
  "filterEventIdsNot": ["S9QaazifbmUr8fB0aCcUIewHALKk9jpa"]
}

Cursor-based pagination

For large traverses, use cursor pagination instead of offset/limit. A cursor keeps a consistent snapshot of the data across requests.

How it works

  1. First request — run a query without a cursor. The response includes a cursor string.
  2. Subsequent requests — pass the cursor from the previous response to continue.
  3. End of results — when cursor is null, there are no more results.

Cursor format

The cursor is a base64-encoded string containing a snapshot identifier, position information and a keep-alive setting. You do not need to parse or modify it — just pass it back as-is.

Using cursors

// First request
{
  "version": "0.0.1",
  "root": {
    "type": "group",
    "children": [
      {
        "type": "event_condition",
        "key": "event-type",
        "operator": "matches-string",
        "values": ["create"]
      }
    ]
  },
  "limit": 100
}
 
// Response includes: { "cursor": "eyJwb2ludEluVGltZUlkIjoiLi4uIn0=", ... }
 
// Next request — just pass the cursor
{
  "cursor": "eyJwb2ludEluVGltZUlkIjoiLi4uIn0="
}
  • The cursor expires after a period of inactivity (default: 1–5 minutes).
  • offset is not compatible with cursor pagination and is cleared when a cursor is set.
  • Cursors are stateless — any process holding the cursor can continue the iteration.

Aggregations

Aggregations are disabled by default and are only available on endpoints that explicitly support them. Check the endpoint in the API Reference before using them. Access requires the PROJECT_AGGREGATIONS scope, which is manually granted by Instasent and reserved for trusted partners.

Aggregations analyse and summarise the filtered events. All configuration goes inside params; use the @ prefix to reference event parameters — they are auto-resolved.

Date histogram

Group events by time intervals:

{
  "version": "0.0.1",
  "limit": 0,
  "offset": 0,
  "aggregations": {
    "eventsByDay": {
      "type": "date_histogram",
      "params": {
        "field": "@created-at",
        "calendar_interval": "1d",
        "format": "yyyy-MM-dd",
        "time_zone": "UTC"
      }
    }
  }
}

Date histogram with nested aggregations

Calculate metrics for each time period:

{
  "version": "0.0.1",
  "limit": 0,
  "offset": 0,
  "aggregations": {
    "salesByDate": {
      "type": "date_histogram",
      "params": {
        "field": "@ecommerce_order_create.created-at",
        "calendar_interval": "1d",
        "format": "yyyy-MM-dd (EEE)",
        "time_zone": "Europe/Madrid"
      },
      "aggs": {
        "totalSales": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.order-euro-amount" }
        },
        "orderCount": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.product-count" }
        }
      }
    }
  }
}

Fixed interval vs calendar interval

  • calendar_interval — calendar-aware intervals (1d, 1w, 1M, 1y).
  • fixed_interval — fixed time intervals (1h, 6h, 30m).
{
  "version": "0.0.1",
  "limit": 0,
  "offset": 0,
  "aggregations": {
    "salesBy6HourInterval": {
      "type": "date_histogram",
      "params": {
        "field": "@ecommerce_order_create.created-at",
        "fixed_interval": "6h",
        "format": "HH:00",
        "time_zone": "UTC"
      },
      "aggs": {
        "salesAmount": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.order-euro-amount" }
        }
      }
    }
  }
}

Terms aggregation

Group events by unique values in a field:

{
  "version": "0.0.1",
  "limit": 0,
  "offset": 0,
  "aggregations": {
    "eventTypes": {
      "type": "terms",
      "params": {
        "field": "@event-type",
        "size": 10
      }
    }
  }
}

Terms with nested aggregations

Detailed metrics per category:

{
  "version": "0.0.1",
  "limit": 0,
  "offset": 0,
  "aggregations": {
    "topProducts": {
      "type": "terms",
      "params": {
        "field": "@ecommerce_order_create.product-name",
        "size": 5,
        "missing": "unknown",
        "order": { "salesCount": "desc" }
      },
      "aggs": {
        "salesCount": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.product-count" }
        },
        "salesEuroAmount": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.product-price-euro" }
        }
      }
    }
  }
}

Sum aggregation

Calculate totals across matching events:

{
  "version": "0.0.1",
  "limit": 0,
  "offset": 0,
  "aggregations": {
    "totalRevenue": {
      "type": "sum",
      "params": { "field": "@ecommerce_order_create.order-euro-amount" }
    }
  }
}

Complete sales analysis

Sales patterns across multiple dimensions:

{
  "version": "0.0.1",
  "limit": 0,
  "offset": 0,
  "root": {
    "type": "group",
    "children": [
      {
        "type": "event_condition",
        "key": "event-type",
        "operator": "matches-string",
        "values": ["ecommerce_order_create"]
      },
      {
        "type": "event_condition",
        "key": "created-at",
        "operator": "range-date-relative",
        "values": {
          "lowerOffset": -21,
          "upperOffset": 0,
          "lowerOffsetPeriod": "day",
          "upperOffsetPeriod": "day"
        }
      }
    ]
  },
  "aggregations": {
    "totalSalesAmount": {
      "type": "sum",
      "params": { "field": "@ecommerce_order_create.order-euro-amount" }
    },
    "salesByDate": {
      "type": "date_histogram",
      "params": {
        "field": "@ecommerce_order_create.created-at",
        "calendar_interval": "1d",
        "format": "yyyy-MM-dd (EEE)",
        "time_zone": "UTC"
      },
      "aggs": {
        "salesCount": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.product-count" }
        },
        "salesEuroAmount": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.order-euro-amount" }
        }
      }
    },
    "topProducts": {
      "type": "terms",
      "params": {
        "field": "@ecommerce_order_create.product-name",
        "size": 10,
        "missing": "unknown",
        "order": { "salesCount": "desc" }
      },
      "aggs": {
        "salesCount": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.product-count" }
        },
        "salesEuroAmount": {
          "type": "sum",
          "params": { "field": "@ecommerce_order_create.product-price-euro" }
        }
      }
    }
  }
}

Listing event types in a project

{
  "version": "0.0.1",
  "limit": 0,
  "aggregations": {
    "total": {
      "type": "terms",
      "params": {
        "field": "@event-type",
        "size": 100
      }
    }
  }
}

Range aggregations

Group events into ranges:

{
  "version": "0.0.1",
  "limit": 0,
  "offset": 0,
  "aggregations": {
    "contactsByBucketRange": {
      "type": "range",
      "params": {
        "field": "@bucket",
        "ranges": [
          { "from": 0,  "to": 33  },
          { "from": 33, "to": 66  },
          { "from": 66, "to": 100 }
        ]
      }
    }
  }
}

Operators reference

Every condition node has the shape:

{
  "type": "event_condition",
  "key": "<event attribute or parameter>",
  "operator": "<operator name>",
  "values": "<values — shape depends on the operator>"
}

The subsections below describe, for each operator, the exact shape of values and any behavioural notes. About key:

  • A native event attribute (e.g. event-type, created-at, received-at, audience-id, ds-id).
  • An event parameter, scoped by event type: <event-type>.<parameter> — e.g. ecommerce_order_create.order-euro-amount, create.source. Parameters are resolved against the event-type configuration of the project, and their data type drives which operators are valid.
FamilyOperators
Genericmatch-all, match-none, exists, exists-not
Booleanmatches-bool
Stringcontains, contains-not, startswith, startswith-not, endswith, endswith-not, matches-string, matches-string-not
Numericmatches-number, matches-number-not, range-number, range-number-not
Datematches-date, range-date, range-date-not, range-date-relative, range-date-anniversary, range-date-dayversary, range-date-timeversary
Geographicgeopoint-distance

Conventions used below:

  • Negation. Every operator with a -not suffix takes the same values as its positive counterpart and inverts the match. A missing field is not matched by the positive operator and is matched by the negated one — i.e. negation is "not (positive match)", which includes events where the field is absent.
  • Multi-value fields + && prefix. For array-valued fields, string and numeric "list" operators default to OR semantics across the provided values. Passing "&&" as the first element of values switches to AND — all values must be present. "||" (the default) is also accepted explicitly.

Generic

These work regardless of the field's data type.

match-all

Matches every event. Used internally. values is ignored.

match-none

Matches no events. Used internally. values is ignored.

exists

The field is present on the event (non-null, and non-empty for array fields).

{ "type": "event_condition", "key": "ecommerce_order_create.coupon-code", "operator": "exists", "values": [] }

exists-not

The field is missing or null.

Boolean

matches-bool

Exact boolean match. values must be an array with exactly one element: [true] or [false].

{ "type": "event_condition", "key": "ecommerce_order_create.is-first-order", "operator": "matches-bool", "values": [true] }

String

Apply to fields of type STRING, KEYWORD and TEXT. All string operators accept an array of strings; the first element may optionally be "&&" or "||" to set the combination mode for multi-value fields (default || / OR).

OperatorBehaviourCaseMin length
containsSubstring match (*value*)Case-insensitive2 chars
contains-notInverse of containsCase-insensitive2 chars
startswithPrefix match (value*)Case-insensitive1 char
startswith-notInverse of startswithCase-insensitive1 char
endswithSuffix match (*value)Case-insensitive1 char
endswith-notInverse of endswithCase-insensitive1 char
matches-stringExact value matchCase-sensitive1 char
matches-string-notInverse of matches-stringCase-sensitive1 char

Max value length for contains / contains-not: 128 chars.

OR across multiple values (default):

{ "type": "event_condition", "key": "event-type", "operator": "matches-string", "values": ["create", "update"] }

AND across multiple values (for multi-value fields such as audience-target-groups):

{
  "type": "event_condition",
  "key": "audience-target-groups",
  "operator": "matches-string",
  "values": ["&&", "vip", "newsletter"]
}

Numeric

Apply to fields of type INT and DECIMAL.

matches-number / matches-number-not

Exact match against one or more numbers. Same && / || semantics as the string operators.

{
  "type": "event_condition",
  "key": "ecommerce_order_create.product-count",
  "operator": "matches-number",
  "values": [1, 2, 3]
}

range-number / range-number-not

Range query. values is an object, not an array:

{
  "type": "event_condition",
  "key": "ecommerce_order_create.order-euro-amount",
  "operator": "range-number",
  "values": {
    "lowerNumber": 100,
    "upperNumber": 200,
    "lowerExcludeEquals": false,
    "upperExcludeEquals": false
  }
}
FieldTypeDefaultMeaning
lowerNumbernumber | nullnullLower bound. null = unbounded below.
upperNumbernumber | nullnullUpper bound. null = unbounded above.
lowerExcludeEqualsboolfalseIf true, lower bound is exclusive (gt); otherwise inclusive (gte).
upperExcludeEqualsboolfalseIf true, upper bound is exclusive (lt); otherwise inclusive (lte).

Both bounds null on range-number matches everything (and nothing on range-number-not).

Date

Apply to fields of type DATE. All date operators honour the project timezone.

matches-date

Exact day match. Internally expanded to [00:00:00, 23:59:59] in the project timezone.

{
  "type": "event_condition",
  "key": "created-at",
  "operator": "matches-date",
  "values": { "date": "2026-04-22" }
}
FieldTypeNotes
datestring (YYYY-MM-DD)Required. Exactly one.

range-date / range-date-not

Absolute date range.

{
  "type": "event_condition",
  "key": "created-at",
  "operator": "range-date",
  "values": {
    "lowerDate": "2026-01-01",
    "upperDate": "2026-03-31",
    "lowerExcludeEquals": false,
    "upperExcludeEquals": false,
    "lowerRounding": true,
    "upperRounding": true
  }
}
FieldTypeDefaultMeaning
lowerDateISO date/datetime | nullnullLower bound. null = unbounded below.
upperDateISO date/datetime | nullnullUpper bound. null = unbounded above.
lowerExcludeEqualsboolfalseExclude equality on lower bound (gt vs gte).
upperExcludeEqualsboolfalseExclude equality on upper bound (lt vs lte).
lowerRoundingboolfalseIf true, rounds the lower bound to the start of its day (/d).
upperRoundingboolfalseIf true, rounds the upper bound to the end of its day (/d).

range-date-relative / range-date-relative-not

Range expressed relative to now.

{
  "type": "event_condition",
  "key": "created-at",
  "operator": "range-date-relative",
  "values": {
    "lowerOffset": -30,
    "upperOffset": 0,
    "lowerOffsetPeriod": "day",
    "upperOffsetPeriod": "day",
    "lowerExcludeEquals": false,
    "upperExcludeEquals": false,
    "lowerRounding": false,
    "upperRounding": false
  }
}
FieldTypeDefaultMeaning
lowerOffsetint | nullnullSigned offset from now. Negative = past, positive = future. null = unbounded.
upperOffsetint | nullnullSigned offset from now.
lowerOffsetPeriodenum"day"Unit of lowerOffset. One of: min, hour, day, week, month, year.
upperOffsetPeriodenum"day"Unit of upperOffset. Same options.
lowerExcludeEqualsboolfalseSame semantics as range-date.
upperExcludeEqualsboolfalseSame semantics as range-date.
lowerRoundingboolfalseRounds the bound to the start of the period.
upperRoundingboolfalseRounds the bound to the end of the period.

range-date-anniversary

Matches date anniversaries independent of year (e.g. "happened in the next 7 days of the year", "falls between Jan 25 and Dec 01"). Only available on DATE fields backed by the anniversary index (event created-at and custom date parameters that opt in).

// Relative mode — N days before/after today's anniversary
{
  "values": {
    "mode": "relative",
    "lowerOffsetDays": 0,
    "upperOffsetDays": 7
  }
}
 
// Absolute mode — month-day range (format MMDD)
{
  "values": {
    "mode": "absolute",
    "lowerDate": "0125",
    "upperDate": "1201"
  }
}
FieldTypeRequired whenNotes
mode"relative" | "absolute"alwaysDefault "relative".
lowerOffsetDaysintmode = relativeSigned. Negative = before, positive = after. gte.
upperOffsetDaysintmode = relativeSigned. Exclusive upper (lt). Default 1.
lowerDatestring (MMDD)mode = absolutee.g. "0125" = Jan 25.
upperDatestring (MMDD)mode = absoluteInverted ranges wrap around the year boundary.

range-date-dayversary

Matches a weekday + hour-of-day window. Only valid on created-at. Use it for recurring weekly schedules — e.g. "orders on Friday evenings".

{
  "type": "event_condition",
  "key": "created-at",
  "operator": "range-date-dayversary",
  "values": { "lowerDay": "518", "upperDay": "523" }
}
FieldTypeFormatExample
lowerDaystringDHH — 1 digit weekday (1 = Monday … 7 = Sunday) + 2 digit hour (00–23)"518" = Friday 18:00, gte.
upperDaystringsame"523" = Friday 23:00, lte.

If the lower day/hour is greater than the upper (e.g. Friday → Monday), the range wraps across the week boundary automatically.

range-date-timeversary

Matches a time-of-day window independent of the date.

// Relative mode — N minutes around the current time
{
  "values": {
    "mode": "relative",
    "lowerOffsetMinutes": -15,
    "upperOffsetMinutes": 15
  }
}
 
// Absolute mode — HH:MM range (format HHMM or HH:MM — colons are stripped)
{
  "values": {
    "mode": "absolute",
    "lowerTime": "0900",
    "upperTime": "1800"
  }
}
FieldTypeRequired whenNotes
mode"relative" | "absolute"alwaysDefault "relative".
lowerOffsetMinutesintmode = relativeSigned, gte.
upperOffsetMinutesintmode = relativeSigned, lt. Default 1.
lowerTimestring (HHMM)mode = absolute24h. "0900" = 09:00.
upperTimestring (HHMM)mode = absoluteInverted ranges wrap across midnight.

Geographic

geopoint-distance

Matches events within a radius of a (longitude, latitude) point. Only applies to geopoint fields (custom event parameters configured as geopoint).

{
  "type": "event_condition",
  "key": "store_visit.location",
  "operator": "geopoint-distance",
  "values": {
    "longitude": -3.7038,
    "latitude": 40.4168,
    "distance": 25
  }
}
FieldTypeRequiredNotes
longitudedecimalyesWGS-84 longitude.
latitudedecimalyesWGS-84 latitude.
distancedecimalyesRadius. Default unit is kilometres.

All three fields are required; missing any raises a validation error.

values shape — quick reference

Operatorvalues shape
match-all, match-noneignored
exists, exists-not[]
matches-bool[true] or [false]
contains(-not), startswith(-not), endswith(-not), matches-string(-not)string[], optional leading "&&" / `"
matches-number(-not)number[], optional leading "&&" / `"
range-number(-not){ lowerNumber, upperNumber, lowerExcludeEquals?, upperExcludeEquals? }
matches-date{ date: "YYYY-MM-DD" }
range-date(-not){ lowerDate, upperDate, lowerExcludeEquals?, upperExcludeEquals?, lowerRounding?, upperRounding? }
range-date-relative(-not){ lowerOffset, upperOffset, lowerOffsetPeriod, upperOffsetPeriod, lower/upperExcludeEquals?, lower/upperRounding? }
range-date-anniversary{ mode: "relative", lowerOffsetDays, upperOffsetDays } or { mode: "absolute", lowerDate: "MMDD", upperDate: "MMDD" }
range-date-dayversary{ lowerDay: "DHH", upperDay: "DHH" } (only on created-at)
range-date-timeversary{ mode: "relative", lowerOffsetMinutes, upperOffsetMinutes } or { mode: "absolute", lowerTime: "HHMM", upperTime: "HHMM" }
geopoint-distance{ longitude, latitude, distance }

Date histogram parameters

ParameterTypeDescriptionExample values
fieldstringDate field to aggregate on.@created-at, @ecommerce_order_create.created-at
calendar_intervalstringCalendar-aware intervals.1d, 1w, 1M, 1y
fixed_intervalstringFixed time intervals.1h, 6h, 30m, 1d
formatstringDate format for bucket keys.yyyy-MM-dd, HH:00, E
time_zonestringTimezone for date calculations.UTC, Europe/Madrid, America/New_York
offsetstringTime offset for bucket boundaries.+1h, -30m
min_doc_countintegerMinimum document count per bucket.0, 1
extended_boundsobjectExtend bounds beyond data range.{"min":"2024-01-01","max":"2024-12-31"}

Terms aggregation parameters

ParameterTypeDescriptionExample values
fieldstringField to group by.@product-name, @event-type, @audience-categories
sizeintegerNumber of top terms to return.5, 10, 100
missingstringLabel for documents with missing values."unknown", "N/A"
orderobjectSort order for terms.{"salesCount":"desc"}, {"_count":"asc"}
min_doc_countintegerMinimum document count per term.1, 5
includearray/stringInclude only specific terms.["product1","product2"]
excludearray/stringExclude specific terms.["excluded1","excluded2"]

What's next

  • Audience probes: find out which event types this project actually receives, when the last one arrived, and what values their parameters carry, before you filter on any of them.
  • Audience query filter (AQF) — the contact-side filter, with segment and group_event conditions.
  • API Reference — endpoints that accept this filter (/event/search, /event/scroll, /event/aggregations, and /event/volumes to probe the events it selects).

Last updated September 30, 2026

PreviousQuery filterNextProbes
  • Quickstart
  • All create events from the last 30 days
  • Ecommerce orders between €100 and €200
  • Basic concepts
  • Filter structure
  • Condition types
  • Native event attributes
  • Event parameters
  • Common patterns
  • By event type and source
  • Date range
  • Events for specific contacts
  • Additional filter options
  • Cursor-based pagination
  • How it works
  • Cursor format
  • Using cursors
  • Aggregations
  • Date histogram
  • Date histogram with nested aggregations
  • Fixed interval vs calendar interval
  • Terms aggregation
  • Terms with nested aggregations
  • Sum aggregation
  • Complete sales analysis
  • Listing event types in a project
  • Range aggregations
  • Operators reference
  • Generic
  • Boolean
  • String
  • Numeric
  • Date
  • Geographic
  • values shape — quick reference
  • Date histogram parameters
  • Terms aggregation parameters
  • What's next

© 2026 Instasent

Privacy PolicyTerms & ConditionsCookie PolicyLegal Notice
All systems operational