Docs·Visitors and people
/api/v1/spreelytics/people/queryCount people who match
Counts the people who match a people-query, without saving anything. The body is the same definition a segment stores, and Create a segment explains every condition. Use it to try a definition before you save it as a segment: this endpoint checks each condition in full and answers 400 with the reason, which saving a segment does not.
Add breakdown to group the matched people by the channel, country or source of their first visit. Add the filter parameter to keep only people with at least one visit that passes it. When the workspace is past its plan's allowance, nothing after the moment it ran out is counted.
It is a read sent as a POST because a query does not fit in a URL, so every role can call it, Viewer included.
Keys: an account key or an audience key. Getting started explains both kinds.
Parameters
| Prop | In | Type | Notes |
|---|---|---|---|
contactListId | query | string | The audience id, a UUID. With an audience key it must be that key's own audience. |
filter? | query | string | Optional. The same filter the web analytics endpoints take: a URL-encoded JSON array of [dimension, values, operator] entries, for example [["country",["US"]]] (leave the operator out to mean is). A person passes when at least one of their visits matches it. |
Request body
| Prop | Type | Notes |
|---|---|---|
conditions | PeopleQueryConditionDto[] | Required: 1 to 5 conditions. Each has "source": "internal" and a kind of event, property or revenue. The Cohorts API page describes the fields of each. |
match? | ``all` \ | `any`` |
breakdown? | ``channel` \ | country \ |
startDate? | string | Optional outer window for every condition, sent together with endDate. An ISO 8601 date or timestamp (a bare date is midnight UTC), included. Leave both out for all time. An event condition can carry its own timeframe instead. |
endDate? | string | The end of the outer window, not included. It must come after startDate, or the call answers 400. |
Response
| Prop | Type | Notes |
|---|---|---|
people | number | How many distinct people match. |
rows | PeopleQueryRowDto[] | With breakdown: one { name, people } per value, most people first. Countries are two-letter codes, and people with no visits at all are grouped under an empty name. Empty without breakdown. |
Each item in rows
| Prop | Type | Notes |
|---|---|---|
name | string | |
people | number | How many distinct people match. |
Request
curl -X POST 'https://app.spreelytics.com/api/v1/spreelytics/people/query?contactListId=…' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ … }'
const res = await fetch('https://app.spreelytics.com/api/v1/spreelytics/people/query', {
method: 'POST',
headers: {
Authorization: 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ /* see Request body above */ }),
});
const data = await res.json();
import requests
res = requests.post(
"https://app.spreelytics.com/api/v1/spreelytics/people/query",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={}, # see Request body above
)
data = res.json()
Response
{
"people": 0,
"rows": [
{
"name": "string",
"people": 0
}
]
}