curl -X GET "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
audience_id = "664f1a2b3c4d5e6f7a8b9c0d"
response = requests.get(
f"https://api.tracklysms.com/api/v2/audiences/{audience_id}",
headers={"X-Api-Key": "trk_your_api_key_here"},
)
audience = response.json()
print(f"{audience['name']} — {audience['cached_size']} contacts")
const audienceId = "664f1a2b3c4d5e6f7a8b9c0d";
const response = await fetch(
`https://api.tracklysms.com/api/v2/audiences/${audienceId}`,
{
headers: { "X-Api-Key": "trk_your_api_key_here" },
}
);
const audience = await response.json();
console.log(`${audience.name} — ${audience.cached_size} contacts`);
{
"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"
}
{
"error": "Audience not found",
"code": "not_found"
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Audiences (v2)
Get Audience
Retrieve a single audience by its ID.
GET
/
v2
/
audiences
/
{id}
curl -X GET "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
audience_id = "664f1a2b3c4d5e6f7a8b9c0d"
response = requests.get(
f"https://api.tracklysms.com/api/v2/audiences/{audience_id}",
headers={"X-Api-Key": "trk_your_api_key_here"},
)
audience = response.json()
print(f"{audience['name']} — {audience['cached_size']} contacts")
const audienceId = "664f1a2b3c4d5e6f7a8b9c0d";
const response = await fetch(
`https://api.tracklysms.com/api/v2/audiences/${audienceId}`,
{
headers: { "X-Api-Key": "trk_your_api_key_here" },
}
);
const audience = await response.json();
console.log(`${audience.name} — ${audience.cached_size} contacts`);
{
"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"
}
{
"error": "Audience not found",
"code": "not_found"
}
{
"error": "Invalid credentials",
"code": "invalid_credentials"
}
Returns the full audience object for the specified ID, including its filter definition and cached size.
Path Parameters
Response Fields
Filter group definition. See Audience Filter DSL for structure. Note: filter condition objects use camelCase keys (e.g.
conditionType, listId).Examples
curl -X GET "https://api.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
-H "X-Api-Key: trk_your_api_key_here"
import requests
audience_id = "664f1a2b3c4d5e6f7a8b9c0d"
response = requests.get(
f"https://api.tracklysms.com/api/v2/audiences/{audience_id}",
headers={"X-Api-Key": "trk_your_api_key_here"},
)
audience = response.json()
print(f"{audience['name']} — {audience['cached_size']} contacts")
const audienceId = "664f1a2b3c4d5e6f7a8b9c0d";
const response = await fetch(
`https://api.tracklysms.com/api/v2/audiences/${audienceId}`,
{
headers: { "X-Api-Key": "trk_your_api_key_here" },
}
);
const audience = await response.json();
console.log(`${audience.name} — ${audience.cached_size} contacts`);
{
"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"
}
{
"error": "Audience not found",
"code": "not_found"
}
{
"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. |
| 404 | not_found | No audience exists with the specified ID |
Next Steps
Creating Audiences
Learn about audience segments
Create Schedule
Schedule a campaign