curl -X GET "https://api.tracklysms.com/api/v2/audiences?status=active&page=1&per_page=25" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
response = requests.get(
"https://api.tracklysms.com/api/v2/audiences",
headers={"X-Api-Key": "trk_your_api_key_here"},
params={"status": "active", "page": 1, "per_page": 25}
)
data = response.json()
for audience in data["audiences"]:
print(f"{audience['name']} — {audience['cached_size']} contacts")
const response = await fetch(
"https://api.tracklysms.com/api/v2/audiences?status=active&page=1&per_page=25",
{
headers: { "X-Api-Key": "trk_your_api_key_here" },
}
);
const data = await response.json();
data.audiences.forEach((audience) => {
console.log(`${audience.name} — ${audience.cached_size} contacts`);
});
{
"audiences": [
{
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "High-Value Clickers",
"description": "Contacts who clicked at least 3 times in the last 30 days",
"source_lists": [101, 102],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 30,
"unit": "days",
"listId": null
},
{
"conditionType": "count",
"field": "click_count",
"operator": "gte",
"value": 3,
"unit": null,
"listId": null
}
],
"groups": []
},
"cached_size": 12480,
"cached_size_updated_at": "2025-11-15T08:30:00",
"status": "active",
"created_at": "2025-10-01T14:22:00"
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total": 1,
"total_pages": 1
}
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Audiences (v2)
List Audiences
Retrieve all audiences for your account with optional filtering and pagination.
GET
/
v2
/
audiences
curl -X GET "https://api.tracklysms.com/api/v2/audiences?status=active&page=1&per_page=25" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
response = requests.get(
"https://api.tracklysms.com/api/v2/audiences",
headers={"X-Api-Key": "trk_your_api_key_here"},
params={"status": "active", "page": 1, "per_page": 25}
)
data = response.json()
for audience in data["audiences"]:
print(f"{audience['name']} — {audience['cached_size']} contacts")
const response = await fetch(
"https://api.tracklysms.com/api/v2/audiences?status=active&page=1&per_page=25",
{
headers: { "X-Api-Key": "trk_your_api_key_here" },
}
);
const data = await response.json();
data.audiences.forEach((audience) => {
console.log(`${audience.name} — ${audience.cached_size} contacts`);
});
{
"audiences": [
{
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "High-Value Clickers",
"description": "Contacts who clicked at least 3 times in the last 30 days",
"source_lists": [101, 102],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 30,
"unit": "days",
"listId": null
},
{
"conditionType": "count",
"field": "click_count",
"operator": "gte",
"value": 3,
"unit": null,
"listId": null
}
],
"groups": []
},
"cached_size": 12480,
"cached_size_updated_at": "2025-11-15T08:30:00",
"status": "active",
"created_at": "2025-10-01T14:22:00"
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total": 1,
"total_pages": 1
}
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Returns a paginated list of audiences belonging to your account.
Query Parameters
string
default:"active"
Filter audiences by status. Accepted values:
active, archived.integer
default:1
Page number for pagination.
integer
default:50
Number of audiences per page. Maximum:
100.Response Fields
array
Array of audience objects.
Show Audience object properties
Show Audience object properties
string
Unique audience identifier.
string
Audience name.
string
Audience description.
array of integers
Sending list IDs this audience is scoped to. Empty array means all lists.
object
Filter group definition. See Audience Filter DSL for structure. Filter condition objects use camelCase keys (e.g.
conditionType, listId).integer
Most recently calculated audience size.
datetime
Timestamp when
cached_size was last calculated.string
Audience status:
active or archived.datetime
Timestamp when the audience was created.
object
Examples
curl -X GET "https://api.tracklysms.com/api/v2/audiences?status=active&page=1&per_page=25" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
response = requests.get(
"https://api.tracklysms.com/api/v2/audiences",
headers={"X-Api-Key": "trk_your_api_key_here"},
params={"status": "active", "page": 1, "per_page": 25}
)
data = response.json()
for audience in data["audiences"]:
print(f"{audience['name']} — {audience['cached_size']} contacts")
const response = await fetch(
"https://api.tracklysms.com/api/v2/audiences?status=active&page=1&per_page=25",
{
headers: { "X-Api-Key": "trk_your_api_key_here" },
}
);
const data = await response.json();
data.audiences.forEach((audience) => {
console.log(`${audience.name} — ${audience.cached_size} contacts`);
});
{
"audiences": [
{
"id": "664f1a2b3c4d5e6f7a8b9c0d",
"name": "High-Value Clickers",
"description": "Contacts who clicked at least 3 times in the last 30 days",
"source_lists": [101, 102],
"filter": {
"operator": "AND",
"conditions": [
{
"conditionType": "time",
"field": "last_clicked_at",
"operator": "within",
"value": 30,
"unit": "days",
"listId": null
},
{
"conditionType": "count",
"field": "click_count",
"operator": "gte",
"value": 3,
"unit": null,
"listId": null
}
],
"groups": []
},
"cached_size": 12480,
"cached_size_updated_at": "2025-11-15T08:30:00",
"status": "active",
"created_at": "2025-10-01T14:22:00"
}
],
"pagination": {
"page": 1,
"per_page": 25,
"total": 1,
"total_pages": 1
}
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 401 | invalid_credentials | API key is missing or invalid |
| 403 | account_suspended | Your account is suspended. Resolve outstanding billing or contact support. |
| 429 | rate_limited | Request throttled; retry with exponential backoff after the window resets. |
Next Steps
Creating Audiences
Build audiences in the UI
Create Schedule
Schedule a campaign to an audience
⌘I