> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Filter subscribers

> Filters subscribers by engagement, sign-up, state, and tags.

`kit.filterSubscribers` filters subscribers by engagement, sign-up, state, and tags.

```ts automations/filter-subscribers.automation.ts theme={null}
import { automation, markSignificant } from "automate.ax"
import { kit } from "automate.ax/kit"

export default automation("Filter subscribers", () => {
  markSignificant(
    kit.filterSubscribers({
      countingMode: "unique_email",
      all: [
        {
          type: "opens",
          countGreaterThanOrEqual: 2,
          after: "2026-08-01",
        },
        {
          type: "attribution",
          any: [
            {
              type: "kit_source",
              sourceType: "api_subscription",
            },
          ],
        },
      ],
      include: [{ type: "tags" }],
      sortField: "engagement__open_rate",
      sortOrder: "desc",
    }),
  )
})
```

## Input

Pass these fields:

| Field          | Type                                                                                                                                                                                                          | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `countingMode` | `"raw" \| "unique_email"`                                                                                                                                                                                     | No       | Controls how engagement-filter count thresholds are tallied. `raw` (default) counts every event—five opens of the same email = five. `unique_email` counts distinct emails on which the action occurred—five opens of the same email = one. Applies to every engagement filter (opens, clicks, sent, delivered) in the request; ignored for other filter types.                                                                                                                                                                                                                                                                                                                                       |
| `all`          | `FilterCondition[]`                                                                                                                                                                                           | Yes      | Conditions that every returned subscriber must match.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `include`      | `object[]`                                                                                                                                                                                                    | No       | Optional. Array of `{ type, ...config }` objects naming additional fields to embed on each subscriber row. Valid types: `attribution`, `tags`, `location`, `canceled_at`, `stats`, `custom_fields`. The `stats` type accepts an optional `range: { start, end }` (YYYY-MM-DD dates, defaulting to the last 90 days). The `custom_fields` type adds a `fields` object with all account custom field values (null for fields the subscriber has not set).                                                                                                                                                                                                                                               |
| `sortField`    | `"id" \| "first_name" \| "email_address" \| "created_at" \| "engagement__sent" \| "engagement__opens" \| "engagement__clicks" \| "engagement__open_rate" \| "engagement__click_rate" \| "location__distance"` | No       | Field to order results by. Base columns (`id`, `first_name`, `email_address`, `created_at`) order by that subscriber attribute. `engagement__<metric>` orders by an engagement stat over the trailing 90 days: counts (`sent`, `opens`, `clicks`) and rates (`open_rate`, `click_rate`); subscribers with no sends order as 0. `location__distance` orders by great-circle distance and requires a `location` filter in the same request—its `latitude`/`longitude` supply the origin, and subscribers without a primary location are excluded. Distance defaults to nearest-first (`sort_order` defaults to `asc` for this field); pass `sort_order=desc` for farthest-first. Default: `created_at`. |
| `sortOrder`    | `"asc" \| "desc"`                                                                                                                                                                                             | No       | Sort direction (default: desc).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

Each filter condition requires `type`. Engagement conditions (`opens`, `clicks`, `sent`, or `delivered`) accept `countGreaterThan`, `countGreaterThanOrEqual`, `countLessThan`, `countLessThanOrEqual`, `after`, and `before`. A `subscriber_state` condition accepts `states`; a `custom_field` condition accepts `subscriberCustomFieldId`, `value`, and `comparison`; and a `location` condition requires `latitude`, `longitude`, and `radius`.

Some conditions accept an `any` array:

* Engagement conditions accept `{ type: "broadcasts", ids }` or `{ type: "urls", urls, matching }`.
* A `tags` condition accepts `{ type: "ids", matching }`.
* An `attribution` condition accepts `{ type: "forms", ids }` or `{ type: "kit_source", sourceType?, sourceIds?, sourceNames?, mechanism?, mechanismIds? }`.

## Output

Returns an object with these fields:

| Field         | Type       | Required | Description |
| ------------- | ---------- | -------- | ----------- |
| `subscribers` | `object[]` | Yes      | —           |
| `pagination`  | `object`   | Yes      | —           |

Kit list and reporting endpoints can lag recent writes. Cursor-based list actions accept `after` or `before`; `perPage` defaults to Kit's provider default and cannot exceed 1,000.

Kit rate limits OAuth connections to 600 requests per 60 seconds and V4 API keys to 120 requests per 60 seconds. Automate.ax honors provider retry timing for rate-limit and temporary bulk-capacity responses.