# Filters Reference

Analytics endpoints (`POST /analytics/resource/{experienceId}` and the `POST /analytics/sitewide/*` endpoints) accept a `filters` parameter to narrow the result data as a **JSON object** in the request body.

The deprecated `GET /analytics/resource/{experienceId}` endpoint does not accept the new filters contract. It remains available only during the beta for the original query-parameter shape and will be removed when the beta version ends.

All filter fields are optional. Omit a field or set it to `null` to skip that filter.

#### Dimension Filters

| Field                   | Type      | Description                                   |
| ----------------------- | --------- | --------------------------------------------- |
| `deviceType`            | string    | `"any"`, `"mobile"`, or `"desktop"`           |
| `visitorType`           | string    | `"any"`, `"new"`, or `"returning"`            |
| `countryCodes`          | string\[] | ISO 3166-1 alpha-2 codes, e.g. `["US", "GB"]` |
| `sourceSitesOrChannels` | string\[] | Traffic channel names (see list below)        |

**Available traffic channels:** `Referral`, `All Social`, `Organic Social`, `Paid Social`, `Organic Search`, `Paid Search`, `Paid Shopping`, `Email`, `Google`, `Facebook`, `Instagram`, `Linktree`, `TikTok`, `Twitter`, `Direct`, `SMS`, `Meta`, `Youtube`, `Other`

#### Page & URL Filters

| Field         | Type   | Description                                                                       |
| ------------- | ------ | --------------------------------------------------------------------------------- |
| `landingPage` | object | `{ landingPageUrlPath: string, landingPageUrlPathFilterType: operator }`          |
| `urlParam`    | object | `{ queryParam: string, queryParamValue: string, queryParamFilterType: operator }` |

**Match operators** for `landingPageUrlPathFilterType`: `equals`, `contains`, `startsWith`, `endsWith`, `doesNotEqual`, `doesNotContain`, `doesNotStartWith`, `doesNotEndWith`, `isNull`, `isNotNull`

**Match operators** for `queryParamFilterType`: all of the above plus `regex`

#### User Behavior Filters

| Field                  | Type   | Description                                                                                                        |
| ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ |
| `userBehavior`         | object | `{ viewedCheckout?: boolean, addedToCart?: boolean, viewedProductPage?: boolean, viewedCollectionPage?: boolean }` |
| `reachedCheckoutStage` | string | `"any"`, `"started"`, `"contact_info_submitted"`, `"address_info_submitted"`, `"added_to_cart"`                    |

#### Revenue & Order Filters

| Field                | Type           | Description                                          |
| -------------------- | -------------- | ---------------------------------------------------- |
| `minNetRevenue`      | number         | Minimum order net revenue (inclusive)                |
| `maxNetRevenue`      | number         | Maximum order net revenue (inclusive)                |
| `minShippingRevenue` | number         | Minimum shipping revenue (inclusive)                 |
| `maxShippingRevenue` | number         | Maximum shipping revenue (inclusive)                 |
| `shippingMethods`    | string\[]      | Shipping method names to include                     |
| `currency`           | string\[]      | ISO 4217 codes, e.g. `["USD", "EUR"]`                |
| `maxZScore`          | number \| null | Outlier Z-score threshold; `null` disables filtering |

#### Custom Events Filters

| Field                    | Type      | Description                                                                                                                                  |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `triggeredCustomEvents`  | string\[] | Custom event identifiers. You can find the id for your custom event in the GET <https://api.intelligems.io/v25-10-beta/experiences> payload. |
| `customEventsFilterType` | string    | `"any"` (at least one), `"all"` (every event), `"none"` (none of the events)                                                                 |

#### Product Filters

| Field                    | Type      | Description                             |
| ------------------------ | --------- | --------------------------------------- |
| `experimentProductsOnly` | boolean   | Only include products in the experiment |
| `onlyProductIds`         | string\[] | Shopify product IDs to include          |
| `onlyProductHandles`     | string\[] | Shopify product handles to include      |

#### Advanced Targeting

| Field                                  | Type  | Description                                        |
| -------------------------------------- | ----- | -------------------------------------------------- |
| `pageTargeting`                        | array | Expression groups for page-level targeting         |
| `productTargeting`                     | array | Expression groups for product-level targeting      |
| `applyExperienceTargetingExperienceId` | UUID  | Reuse targeting config from an existing experience |

**Page targeting** — each group has `type` (one of: `utm`, `url`, `urlPath`, `device`, `visitor`, `trafficSource`, `country`, `referrer`, `cookie`, `klaviyo`, `landingPage`) and `queries` array. Each query: `{ key: string, value: string, filter: matchOperator, type: filterType }`.

**Product targeting** — each group has `type` (one of: `productId`, `collection`, `tag`, `price`, `inventory`) and `queries` array. Each query: `{ key: productAttribute, value: string | number, filter: productOperator, type: productAttribute }`. Product operators: `includes`, `doesNotInclude`, `greaterThan`, `lessThan`.

#### Example Filter Object

```json
{
  "deviceType": "mobile",
  "countryCodes": ["US", "CA"],
  "sourceSitesOrChannels": ["Paid Search", "Email"],
  "landingPage": {
    "landingPageUrlPath": "/collections/sale",
    "landingPageUrlPathFilterType": "startsWith"
  },
  "userBehavior": {
    "addedToCart": true
  },
  "minNetRevenue": 10,
  "maxNetRevenue": 500,
  "maxZScore": 3
}
```

For the resource and sitewide POST endpoints, send the filter object directly in the JSON body under `filters`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.intelligems.io/developer-resources/external-api-dev/intelligems-external-api/filters-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.