Filter subscribers by engagement, sign-up date, state, and tags
curl --request POST \
--url https://api.kit.com/v4/subscribers/filter \
--header 'Content-Type: application/json' \
--header 'X-Kit-Api-Key: <api-key>' \
--data '
{
"all": [
{
"type": "opens",
"count_greater_than": 5,
"after": "2024-01-01",
"before": "2024-12-31"
},
{
"type": "clicks",
"count_greater_than": 2,
"after": "2024-01-01",
"before": "2024-12-31",
"any": [
{
"type": "urls",
"urls": [
"kit.com",
"amazon.com"
],
"matching": "contains"
},
{
"type": "broadcasts",
"ids": [
1,
2,
3
]
}
]
},
{
"type": "tags",
"any": [
{
"type": "ids",
"matching": [
123,
456
]
}
]
},
{
"type": "attribution",
"any": [
{
"type": "forms",
"ids": [
789,
1001
]
},
{
"type": "kit_source",
"source_type": "api_subscription",
"source_ids": [
555
],
"source_names": [
"Welcome"
],
"mechanism": "import",
"mechanism_ids": [
9
]
}
]
},
{
"type": "custom_field",
"subscriber_custom_field_id": 42,
"value": "premium",
"comparison": "is"
}
]
}
'require 'uri'
require 'net/http'
url = URI("https://api.kit.com/v4/subscribers/filter")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Kit-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"all\": [\n {\n \"type\": \"opens\",\n \"count_greater_than\": 5,\n \"after\": \"2024-01-01\",\n \"before\": \"2024-12-31\"\n },\n {\n \"type\": \"clicks\",\n \"count_greater_than\": 2,\n \"after\": \"2024-01-01\",\n \"before\": \"2024-12-31\",\n \"any\": [\n {\n \"type\": \"urls\",\n \"urls\": [\n \"kit.com\",\n \"amazon.com\"\n ],\n \"matching\": \"contains\"\n },\n {\n \"type\": \"broadcasts\",\n \"ids\": [\n 1,\n 2,\n 3\n ]\n }\n ]\n },\n {\n \"type\": \"tags\",\n \"any\": [\n {\n \"type\": \"ids\",\n \"matching\": [\n 123,\n 456\n ]\n }\n ]\n },\n {\n \"type\": \"attribution\",\n \"any\": [\n {\n \"type\": \"forms\",\n \"ids\": [\n 789,\n 1001\n ]\n },\n {\n \"type\": \"kit_source\",\n \"source_type\": \"api_subscription\",\n \"source_ids\": [\n 555\n ],\n \"source_names\": [\n \"Welcome\"\n ],\n \"mechanism\": \"import\",\n \"mechanism_ids\": [\n 9\n ]\n }\n ]\n },\n {\n \"type\": \"custom_field\",\n \"subscriber_custom_field_id\": 42,\n \"value\": \"premium\",\n \"comparison\": \"is\"\n }\n ]\n}"
response = http.request(request)
puts response.read_bodyconst options = {
method: 'POST',
headers: {'X-Kit-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
all: [
{
type: 'opens',
count_greater_than: 5,
after: '2024-01-01',
before: '2024-12-31'
},
{
type: 'clicks',
count_greater_than: 2,
after: '2024-01-01',
before: '2024-12-31',
any: [
{type: 'urls', urls: ['kit.com', 'amazon.com'], matching: 'contains'},
{type: 'broadcasts', ids: [1, 2, 3]}
]
},
{type: 'tags', any: [{type: 'ids', matching: [123, 456]}]},
{
type: 'attribution',
any: [
{type: 'forms', ids: [789, 1001]},
{
type: 'kit_source',
source_type: 'api_subscription',
source_ids: [555],
source_names: ['Welcome'],
mechanism: 'import',
mechanism_ids: [9]
}
]
},
{
type: 'custom_field',
subscriber_custom_field_id: 42,
value: 'premium',
comparison: 'is'
}
]
})
};
fetch('https://api.kit.com/v4/subscribers/filter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.kit.com/v4/subscribers/filter"
payload := strings.NewReader("{\n \"all\": [\n {\n \"type\": \"opens\",\n \"count_greater_than\": 5,\n \"after\": \"2024-01-01\",\n \"before\": \"2024-12-31\"\n },\n {\n \"type\": \"clicks\",\n \"count_greater_than\": 2,\n \"after\": \"2024-01-01\",\n \"before\": \"2024-12-31\",\n \"any\": [\n {\n \"type\": \"urls\",\n \"urls\": [\n \"kit.com\",\n \"amazon.com\"\n ],\n \"matching\": \"contains\"\n },\n {\n \"type\": \"broadcasts\",\n \"ids\": [\n 1,\n 2,\n 3\n ]\n }\n ]\n },\n {\n \"type\": \"tags\",\n \"any\": [\n {\n \"type\": \"ids\",\n \"matching\": [\n 123,\n 456\n ]\n }\n ]\n },\n {\n \"type\": \"attribution\",\n \"any\": [\n {\n \"type\": \"forms\",\n \"ids\": [\n 789,\n 1001\n ]\n },\n {\n \"type\": \"kit_source\",\n \"source_type\": \"api_subscription\",\n \"source_ids\": [\n 555\n ],\n \"source_names\": [\n \"Welcome\"\n ],\n \"mechanism\": \"import\",\n \"mechanism_ids\": [\n 9\n ]\n }\n ]\n },\n {\n \"type\": \"custom_field\",\n \"subscriber_custom_field_id\": 42,\n \"value\": \"premium\",\n \"comparison\": \"is\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Kit-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.kit.com/v4/subscribers/filter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'all' => [
[
'type' => 'opens',
'count_greater_than' => 5,
'after' => '2024-01-01',
'before' => '2024-12-31'
],
[
'type' => 'clicks',
'count_greater_than' => 2,
'after' => '2024-01-01',
'before' => '2024-12-31',
'any' => [
[
'type' => 'urls',
'urls' => [
'kit.com',
'amazon.com'
],
'matching' => 'contains'
],
[
'type' => 'broadcasts',
'ids' => [
1,
2,
3
]
]
]
],
[
'type' => 'tags',
'any' => [
[
'type' => 'ids',
'matching' => [
123,
456
]
]
]
],
[
'type' => 'attribution',
'any' => [
[
'type' => 'forms',
'ids' => [
789,
1001
]
],
[
'type' => 'kit_source',
'source_type' => 'api_subscription',
'source_ids' => [
555
],
'source_names' => [
'Welcome'
],
'mechanism' => 'import',
'mechanism_ids' => [
9
]
]
]
],
[
'type' => 'custom_field',
'subscriber_custom_field_id' => 42,
'value' => 'premium',
'comparison' => 'is'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Kit-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://api.kit.com/v4/subscribers/filter"
payload = { "all": [
{
"type": "opens",
"count_greater_than": 5,
"after": "2024-01-01",
"before": "2024-12-31"
},
{
"type": "clicks",
"count_greater_than": 2,
"after": "2024-01-01",
"before": "2024-12-31",
"any": [
{
"type": "urls",
"urls": ["kit.com", "amazon.com"],
"matching": "contains"
},
{
"type": "broadcasts",
"ids": [1, 2, 3]
}
]
},
{
"type": "tags",
"any": [
{
"type": "ids",
"matching": [123, 456]
}
]
},
{
"type": "attribution",
"any": [
{
"type": "forms",
"ids": [789, 1001]
},
{
"type": "kit_source",
"source_type": "api_subscription",
"source_ids": [555],
"source_names": ["Welcome"],
"mechanism": "import",
"mechanism_ids": [9]
}
]
},
{
"type": "custom_field",
"subscriber_custom_field_id": 42,
"value": "premium",
"comparison": "is"
}
] }
headers = {
"X-Kit-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"subscribers": [
{
"id": "456",
"first_name": "Jane",
"email_address": "jane@example.com",
"created_at": "2024-12-01T15:45:00Z",
"tag_names": [
"newsletter",
"engaged"
],
"tag_ids": [
"123",
"456"
]
},
{
"id": "789",
"first_name": null,
"email_address": "anonymous@example.com",
"created_at": "2024-11-15T10:00:00Z",
"tag_names": [],
"tag_ids": []
}
],
"pagination": {
"has_previous_page": false,
"has_next_page": true,
"start_cursor": "WzQ1Nl0=",
"end_cursor": "Wzc4OV0=",
"per_page": 10,
"total_count": 42
}
}{
"errors": [
"The access token is invalid"
]
}Subscribers
Filter subscribers by engagement, sign-up date, state, and tags
Searches your subscriber list with compound conditions: email engagement (opens, clicks, sends, deliveries — with count thresholds and date ranges), sign-up date, subscriber state, and tags. Every condition in the all array must match (AND logic).
Use counting_mode to control how engagement thresholds are tallied — raw (default) counts every event, unique_email counts distinct emails — and the include array to embed extra fields (tags, stats, custom fields, location, attribution, canceled_at) on each returned subscriber.
Data retention: Email stats (opens, clicks, sends, bounces, and unsubscribes) are available via the API for the last 5 years — engagement-condition after/before dates and stats include ranges are limited to the last 3 years instead, and anything further back returns a 400 error naming the earliest allowed date. See Email data retention for the full policy.
POST
/
v4
/
subscribers
/
filter
Filter subscribers by engagement, sign-up date, state, and tags
curl --request POST \
--url https://api.kit.com/v4/subscribers/filter \
--header 'Content-Type: application/json' \
--header 'X-Kit-Api-Key: <api-key>' \
--data '
{
"all": [
{
"type": "opens",
"count_greater_than": 5,
"after": "2024-01-01",
"before": "2024-12-31"
},
{
"type": "clicks",
"count_greater_than": 2,
"after": "2024-01-01",
"before": "2024-12-31",
"any": [
{
"type": "urls",
"urls": [
"kit.com",
"amazon.com"
],
"matching": "contains"
},
{
"type": "broadcasts",
"ids": [
1,
2,
3
]
}
]
},
{
"type": "tags",
"any": [
{
"type": "ids",
"matching": [
123,
456
]
}
]
},
{
"type": "attribution",
"any": [
{
"type": "forms",
"ids": [
789,
1001
]
},
{
"type": "kit_source",
"source_type": "api_subscription",
"source_ids": [
555
],
"source_names": [
"Welcome"
],
"mechanism": "import",
"mechanism_ids": [
9
]
}
]
},
{
"type": "custom_field",
"subscriber_custom_field_id": 42,
"value": "premium",
"comparison": "is"
}
]
}
'require 'uri'
require 'net/http'
url = URI("https://api.kit.com/v4/subscribers/filter")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Kit-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"all\": [\n {\n \"type\": \"opens\",\n \"count_greater_than\": 5,\n \"after\": \"2024-01-01\",\n \"before\": \"2024-12-31\"\n },\n {\n \"type\": \"clicks\",\n \"count_greater_than\": 2,\n \"after\": \"2024-01-01\",\n \"before\": \"2024-12-31\",\n \"any\": [\n {\n \"type\": \"urls\",\n \"urls\": [\n \"kit.com\",\n \"amazon.com\"\n ],\n \"matching\": \"contains\"\n },\n {\n \"type\": \"broadcasts\",\n \"ids\": [\n 1,\n 2,\n 3\n ]\n }\n ]\n },\n {\n \"type\": \"tags\",\n \"any\": [\n {\n \"type\": \"ids\",\n \"matching\": [\n 123,\n 456\n ]\n }\n ]\n },\n {\n \"type\": \"attribution\",\n \"any\": [\n {\n \"type\": \"forms\",\n \"ids\": [\n 789,\n 1001\n ]\n },\n {\n \"type\": \"kit_source\",\n \"source_type\": \"api_subscription\",\n \"source_ids\": [\n 555\n ],\n \"source_names\": [\n \"Welcome\"\n ],\n \"mechanism\": \"import\",\n \"mechanism_ids\": [\n 9\n ]\n }\n ]\n },\n {\n \"type\": \"custom_field\",\n \"subscriber_custom_field_id\": 42,\n \"value\": \"premium\",\n \"comparison\": \"is\"\n }\n ]\n}"
response = http.request(request)
puts response.read_bodyconst options = {
method: 'POST',
headers: {'X-Kit-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
all: [
{
type: 'opens',
count_greater_than: 5,
after: '2024-01-01',
before: '2024-12-31'
},
{
type: 'clicks',
count_greater_than: 2,
after: '2024-01-01',
before: '2024-12-31',
any: [
{type: 'urls', urls: ['kit.com', 'amazon.com'], matching: 'contains'},
{type: 'broadcasts', ids: [1, 2, 3]}
]
},
{type: 'tags', any: [{type: 'ids', matching: [123, 456]}]},
{
type: 'attribution',
any: [
{type: 'forms', ids: [789, 1001]},
{
type: 'kit_source',
source_type: 'api_subscription',
source_ids: [555],
source_names: ['Welcome'],
mechanism: 'import',
mechanism_ids: [9]
}
]
},
{
type: 'custom_field',
subscriber_custom_field_id: 42,
value: 'premium',
comparison: 'is'
}
]
})
};
fetch('https://api.kit.com/v4/subscribers/filter', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.kit.com/v4/subscribers/filter"
payload := strings.NewReader("{\n \"all\": [\n {\n \"type\": \"opens\",\n \"count_greater_than\": 5,\n \"after\": \"2024-01-01\",\n \"before\": \"2024-12-31\"\n },\n {\n \"type\": \"clicks\",\n \"count_greater_than\": 2,\n \"after\": \"2024-01-01\",\n \"before\": \"2024-12-31\",\n \"any\": [\n {\n \"type\": \"urls\",\n \"urls\": [\n \"kit.com\",\n \"amazon.com\"\n ],\n \"matching\": \"contains\"\n },\n {\n \"type\": \"broadcasts\",\n \"ids\": [\n 1,\n 2,\n 3\n ]\n }\n ]\n },\n {\n \"type\": \"tags\",\n \"any\": [\n {\n \"type\": \"ids\",\n \"matching\": [\n 123,\n 456\n ]\n }\n ]\n },\n {\n \"type\": \"attribution\",\n \"any\": [\n {\n \"type\": \"forms\",\n \"ids\": [\n 789,\n 1001\n ]\n },\n {\n \"type\": \"kit_source\",\n \"source_type\": \"api_subscription\",\n \"source_ids\": [\n 555\n ],\n \"source_names\": [\n \"Welcome\"\n ],\n \"mechanism\": \"import\",\n \"mechanism_ids\": [\n 9\n ]\n }\n ]\n },\n {\n \"type\": \"custom_field\",\n \"subscriber_custom_field_id\": 42,\n \"value\": \"premium\",\n \"comparison\": \"is\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Kit-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.kit.com/v4/subscribers/filter",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'all' => [
[
'type' => 'opens',
'count_greater_than' => 5,
'after' => '2024-01-01',
'before' => '2024-12-31'
],
[
'type' => 'clicks',
'count_greater_than' => 2,
'after' => '2024-01-01',
'before' => '2024-12-31',
'any' => [
[
'type' => 'urls',
'urls' => [
'kit.com',
'amazon.com'
],
'matching' => 'contains'
],
[
'type' => 'broadcasts',
'ids' => [
1,
2,
3
]
]
]
],
[
'type' => 'tags',
'any' => [
[
'type' => 'ids',
'matching' => [
123,
456
]
]
]
],
[
'type' => 'attribution',
'any' => [
[
'type' => 'forms',
'ids' => [
789,
1001
]
],
[
'type' => 'kit_source',
'source_type' => 'api_subscription',
'source_ids' => [
555
],
'source_names' => [
'Welcome'
],
'mechanism' => 'import',
'mechanism_ids' => [
9
]
]
]
],
[
'type' => 'custom_field',
'subscriber_custom_field_id' => 42,
'value' => 'premium',
'comparison' => 'is'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Kit-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}import requests
url = "https://api.kit.com/v4/subscribers/filter"
payload = { "all": [
{
"type": "opens",
"count_greater_than": 5,
"after": "2024-01-01",
"before": "2024-12-31"
},
{
"type": "clicks",
"count_greater_than": 2,
"after": "2024-01-01",
"before": "2024-12-31",
"any": [
{
"type": "urls",
"urls": ["kit.com", "amazon.com"],
"matching": "contains"
},
{
"type": "broadcasts",
"ids": [1, 2, 3]
}
]
},
{
"type": "tags",
"any": [
{
"type": "ids",
"matching": [123, 456]
}
]
},
{
"type": "attribution",
"any": [
{
"type": "forms",
"ids": [789, 1001]
},
{
"type": "kit_source",
"source_type": "api_subscription",
"source_ids": [555],
"source_names": ["Welcome"],
"mechanism": "import",
"mechanism_ids": [9]
}
]
},
{
"type": "custom_field",
"subscriber_custom_field_id": 42,
"value": "premium",
"comparison": "is"
}
] }
headers = {
"X-Kit-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"subscribers": [
{
"id": "456",
"first_name": "Jane",
"email_address": "jane@example.com",
"created_at": "2024-12-01T15:45:00Z",
"tag_names": [
"newsletter",
"engaged"
],
"tag_ids": [
"123",
"456"
]
},
{
"id": "789",
"first_name": null,
"email_address": "anonymous@example.com",
"created_at": "2024-11-15T10:00:00Z",
"tag_names": [],
"tag_ids": []
}
],
"pagination": {
"has_previous_page": false,
"has_next_page": true,
"start_cursor": "WzQ1Nl0=",
"end_cursor": "Wzc4OV0=",
"per_page": 10,
"total_count": 42
}
}{
"errors": [
"The access token is invalid"
]
}Authorizations
API KeyOAuth2
Authenticate API requests via an API Key
Body
application/json
Filter subscribers based on engagement and subscription criteria using the 'all' array with filter conditions that must all be met (AND logic).
Array of filter conditions where ALL must be met (AND logic)
Show child attributes
Show child attributes
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.
Available options:
raw, unique_email 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; both must fall within the last 3 years or the API returns 400). The custom_fields type adds a fields object with all account custom field values (null for fields the subscriber has not set).
Show child attributes
Show child attributes
Example:
[ { "type": "tags" }, { "type": "stats", "range": { "start": "2026-05-01", "end": "2026-06-30" } } ]
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.
Available options:
id, first_name, email_address, created_at, engagement__sent, engagement__opens, engagement__clicks, engagement__open_rate, engagement__click_rate, location__distance Sort direction (default: desc).
Available options:
asc, desc Was this page helpful?