Skip to content

Requests and responses

Filtering

Narrow a list with the filter parameter.

Syntax

List endpoints take a filter query parameter. A filter is an operator applied to a field and a value, written like a function call:

http
GET /api/profiles?filter=equals(email,"sarah.mason@example.com")
GET /api/events?filter=greater-than(datetime,2026-10-01T00:00:00Z)
GET /api/lists?filter=any(name,["Newsletter","VIP"])

Encode the filter when you put it in a URL. Most HTTP libraries do this for you when you pass query parameters as a map.

Operators

OperatorMatches when
equalsThe field equals the value
anyThe field equals any value in a list
hasThe array field contains the value
containsThe text or array field contains the value
contains-anyThe field contains any of the listed values
contains-allThe field contains all of the listed values
starts-withThe text starts with the value
ends-withThe text ends with the value
greater-thanGreater than, or later than for dates
greater-or-equalGreater than or equal to
less-thanLess than, or earlier than for dates
less-or-equalLess than or equal to

Not every field takes every operator. Each endpoint's reference page lists its filterable fields and the operators each one accepts.

Values

  • Text in double or single quotes: "VIP" or 'VIP'. Escape a quote inside the text with a backslash.
  • Numbers, true, false and null without quotes.
  • Dates and date-times without quotes, in ISO 8601: 2026-01-01, 2026-01-01T00:00:00Z, 2026-01-01T09:30:00-05:00.
  • Lists in square brackets, for any, contains-any and contains-all: ["a","b"].
  • Nested fields with dots: subscriptions.email.marketing.suppression.reason.

Combining filters

Wrap conditions in and(...) or or(...), and negate one with not(...). Conditions separated by commas at the top level must all match, the same as and.

http
filter=and(greater-than(created,2026-01-01T00:00:00Z),less-than(created,2026-02-01T00:00:00Z))
filter=greater-than(created,2026-01-01T00:00:00Z),less-than(created,2026-02-01T00:00:00Z)

When a filter is wrong

A field the endpoint does not filter on, an operator the field does not take, or a value of the wrong type returns 400 invalid with source.parameter set to filter. The detail names what is allowed, so read it before you change the request.

Endpoints with filters

EndpointFilterable fields
GET /api/billing-usageid
GET /api/campaign-messagesidcampaign_idnamestatuscreatedupdated
GET /api/campaignsidnamearchivedbuildercreated_atupdated_atmessages.channelstatusscheduled_at
GET /api/catalog-categoriesidsitem.idname
GET /api/catalog-category-bulk-create-jobsstatus
GET /api/catalog-category-bulk-delete-jobsstatus
GET /api/catalog-category-bulk-update-jobsstatus
GET /api/catalog-item-bulk-create-jobsstatus
GET /api/catalog-item-bulk-delete-jobsstatus
GET /api/catalog-item-bulk-update-jobsstatus
GET /api/catalog-itemsidscategory.idtitlepublished
GET /api/catalog-variant-bulk-create-jobsstatus
GET /api/catalog-variant-bulk-delete-jobsstatus
GET /api/catalog-variant-bulk-update-jobsstatus
GET /api/catalog-variantsidsitem.idskutitlepublished
GET /api/catalog-categories/{id}/itemsidscategory.idtitlepublished
GET /api/catalog-items/{id}/categoriesidsitem.idname
GET /api/catalog-items/{id}/variantsidsitem.idskutitlepublished
GET /api/catalog-categories/{id}/relationships/itemsidscategory.idtitlepublished
GET /api/catalog-items/{id}/relationships/categoriesidsitem.idname
GET /api/catalog-items/{id}/relationships/variantsidsitem.idskutitlepublished
GET /client/review-values-reportsproduct_external_ids
GET /client/reviewsstatusreview_typeratingidcontentsmart_quotepublic_replyverifiedincentivizededitedmediacreatedupdated
GET /api/coupon-code-bulk-create-jobsstatus
GET /api/coupon-codesexpires_atstatuscoupon.idprofile.id
GET /api/coupons/{id}/coupon-codesexpires_atstatuscoupon.idprofile.id
GET /api/coupons/{id}/relationships/coupon-codesexpires_atstatuscoupon.idprofile.id
GET /api/data-sourcesnamespace
GET /api/object-typesnamespace
GET /api/object-types/{id}/object-ingestion-logsrecord_idstatusevent_typetimestamp
GET /api/object-types/{id}/relationships/object-ingestion-logsrecord_idstatusevent_typetimestamp
GET /api/eventsmetric_idprofile_idproperties.<key>datetimetimestamp
GET /api/flowsidnamestatusarchivedcreatedupdatedtrigger_type
GET /api/flow-actions/{id}/flow-messagesidnamecreatedupdated
GET /api/flows/{id}/flow-actionsidaction_typestatuscreatedupdated
GET /api/flow-actions/{id}/relationships/flow-messagesnamecreatedupdated
GET /api/flows/{id}/relationships/flow-actionsidaction_typestatuscreatedupdated
GET /api/formsidnameab_teststatuscreated_atupdated_at
GET /api/forms/{id}/form-versionsform_typestatuscreated_atupdated_at
GET /api/forms/{id}/relationships/form-versionsform_typestatuscreated_atupdated_at
GET /api/imagesidupdated_atformatnamesizehidden
GET /api/listsnameidcreatedupdated
GET /api/lists/{id}/profilesemailphone_numberpush_token_kxjoined_group_at
GET /api/lists/{id}/relationships/profilesemailphone_numberpush_token_kxjoined_group_at
GET /api/metricsintegration.nameintegration.category
GET /api/profile-bulk-import-jobsstatus
GET /api/profile-suppression-bulk-create-jobsstatuslist_idsegment_id
GET /api/profile-suppression-bulk-delete-jobsstatuslist_idsegment_id
GET /api/profilesidemailphone_numberexternal_id_kxcreatedupdatedsubscriptions.email.marketing.list_suppressions.reasonsubscriptions.email.marketing.list_suppressions.timestampsubscriptions.email.marketing.list_suppressions.list_idsubscriptions.email.marketing.suppression.reasonsubscriptions.email.marketing.suppression.timestamp
GET /api/push-tokensidprofile.idenablement_statusplatform
GET /api/reviewscreatedratingiditem.idcontentstatusreview_typeverified
GET /api/segmentsnameidcreatedupdatedis_activeis_starred
GET /api/segments/{id}/profilesprofile_idemailphone_numberpush_token_kxjoined_group_at
GET /api/segments/{id}/relationships/profilesprofile_idemailphone_numberpush_token_kxjoined_group_at
GET /api/tag-groupsnameexclusivedefault
GET /api/tagsname
GET /api/template-universal-contentidnamecreatedupdateddefinition.content_typedefinition.type
GET /api/templatesidnamecreatedupdated
GET /api/translationsidresource_typechannelrelated_resource_id
GET /api/web-feedsnamecreatedupdated