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:
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
| Operator | Matches when |
|---|---|
equals | The field equals the value |
any | The field equals any value in a list |
has | The array field contains the value |
contains | The text or array field contains the value |
contains-any | The field contains any of the listed values |
contains-all | The field contains all of the listed values |
starts-with | The text starts with the value |
ends-with | The text ends with the value |
greater-than | Greater than, or later than for dates |
greater-or-equal | Greater than or equal to |
less-than | Less than, or earlier than for dates |
less-or-equal | Less 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,falseandnullwithout 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-anyandcontains-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.
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
| Endpoint | Filterable fields |
|---|---|
| GET /api/billing-usage | id |
| GET /api/campaign-messages | idcampaign_idnamestatuscreatedupdated |
| GET /api/campaigns | idnamearchivedbuildercreated_atupdated_atmessages.channelstatusscheduled_at |
| GET /api/catalog-categories | idsitem.idname |
| GET /api/catalog-category-bulk-create-jobs | status |
| GET /api/catalog-category-bulk-delete-jobs | status |
| GET /api/catalog-category-bulk-update-jobs | status |
| GET /api/catalog-item-bulk-create-jobs | status |
| GET /api/catalog-item-bulk-delete-jobs | status |
| GET /api/catalog-item-bulk-update-jobs | status |
| GET /api/catalog-items | idscategory.idtitlepublished |
| GET /api/catalog-variant-bulk-create-jobs | status |
| GET /api/catalog-variant-bulk-delete-jobs | status |
| GET /api/catalog-variant-bulk-update-jobs | status |
| GET /api/catalog-variants | idsitem.idskutitlepublished |
| GET /api/catalog-categories/{id}/items | idscategory.idtitlepublished |
| GET /api/catalog-items/{id}/categories | idsitem.idname |
| GET /api/catalog-items/{id}/variants | idsitem.idskutitlepublished |
| GET /api/catalog-categories/{id}/relationships/items | idscategory.idtitlepublished |
| GET /api/catalog-items/{id}/relationships/categories | idsitem.idname |
| GET /api/catalog-items/{id}/relationships/variants | idsitem.idskutitlepublished |
| GET /client/review-values-reports | product_external_ids |
| GET /client/reviews | statusreview_typeratingidcontentsmart_quotepublic_replyverifiedincentivizededitedmediacreatedupdated |
| GET /api/coupon-code-bulk-create-jobs | status |
| GET /api/coupon-codes | expires_atstatuscoupon.idprofile.id |
| GET /api/coupons/{id}/coupon-codes | expires_atstatuscoupon.idprofile.id |
| GET /api/coupons/{id}/relationships/coupon-codes | expires_atstatuscoupon.idprofile.id |
| GET /api/data-sources | namespace |
| GET /api/object-types | namespace |
| GET /api/object-types/{id}/object-ingestion-logs | record_idstatusevent_typetimestamp |
| GET /api/object-types/{id}/relationships/object-ingestion-logs | record_idstatusevent_typetimestamp |
| GET /api/events | metric_idprofile_idproperties.<key>datetimetimestamp |
| GET /api/flows | idnamestatusarchivedcreatedupdatedtrigger_type |
| GET /api/flow-actions/{id}/flow-messages | idnamecreatedupdated |
| GET /api/flows/{id}/flow-actions | idaction_typestatuscreatedupdated |
| GET /api/flow-actions/{id}/relationships/flow-messages | namecreatedupdated |
| GET /api/flows/{id}/relationships/flow-actions | idaction_typestatuscreatedupdated |
| GET /api/forms | idnameab_teststatuscreated_atupdated_at |
| GET /api/forms/{id}/form-versions | form_typestatuscreated_atupdated_at |
| GET /api/forms/{id}/relationships/form-versions | form_typestatuscreated_atupdated_at |
| GET /api/images | idupdated_atformatnamesizehidden |
| GET /api/lists | nameidcreatedupdated |
| GET /api/lists/{id}/profiles | emailphone_numberpush_token_kxjoined_group_at |
| GET /api/lists/{id}/relationships/profiles | emailphone_numberpush_token_kxjoined_group_at |
| GET /api/metrics | integration.nameintegration.category |
| GET /api/profile-bulk-import-jobs | status |
| GET /api/profile-suppression-bulk-create-jobs | statuslist_idsegment_id |
| GET /api/profile-suppression-bulk-delete-jobs | statuslist_idsegment_id |
| GET /api/profiles | idemailphone_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-tokens | idprofile.idenablement_statusplatform |
| GET /api/reviews | createdratingiditem.idcontentstatusreview_typeverified |
| GET /api/segments | nameidcreatedupdatedis_activeis_starred |
| GET /api/segments/{id}/profiles | profile_idemailphone_numberpush_token_kxjoined_group_at |
| GET /api/segments/{id}/relationships/profiles | profile_idemailphone_numberpush_token_kxjoined_group_at |
| GET /api/tag-groups | nameexclusivedefault |
| GET /api/tags | name |
| GET /api/template-universal-content | idnamecreatedupdateddefinition.content_typedefinition.type |
| GET /api/templates | idnamecreatedupdated |
| GET /api/translations | idresource_typechannelrelated_resource_id |
| GET /api/web-feeds | namecreatedupdated |