Skip to main content
GET
/
v2
/
audiences
/
{id}
curl -X GET "https://app.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
  -H "X-Api-Key: trk_your_api_key_here"

{
  "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"
      },
      {
        "conditionType": "count",
        "field": "click_count",
        "operator": "gte",
        "value": 3
      }
    ],
    "groups": []
  },
  "cached_size": 12480,
  "cached_size_updated_at": "2025-11-15T08:30:00",
  "status": "active",
  "created_at": "2025-10-01T14:22:00"
}
Returns the full audience object for the specified ID, including its filter definition and cached size.

​
Path Parameters

​
id
string
required
The unique identifier of the audience.

​
Response Fields

​
id
string
Unique audience identifier.
​
name
string
Audience name.
​
description
string
Audience description.
​
source_lists
array of integers
Sending list IDs this audience is scoped to. Empty array means all lists.
​
filter
object
Filter group definition. See Audience Filter DSL for structure. Note: filter condition objects use camelCase keys (e.g. conditionType, listId).
​
cached_size
integer
Most recently calculated audience size. null if never calculated.
​
cached_size_updated_at
datetime
Timestamp when cached_size was last calculated. null if never calculated.
​
status
string
Audience status: active or archived.
​
created_at
datetime
Timestamp when the audience was created.

​
Examples

curl -X GET "https://app.tracklysms.com/api/v2/audiences/664f1a2b3c4d5e6f7a8b9c0d" \
  -H "X-Api-Key: trk_your_api_key_here"

{
  "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"
      },
      {
        "conditionType": "count",
        "field": "click_count",
        "operator": "gte",
        "value": 3
      }
    ],
    "groups": []
  },
  "cached_size": 12480,
  "cached_size_updated_at": "2025-11-15T08:30:00",
  "status": "active",
  "created_at": "2025-10-01T14:22:00"
}

​
Error Codes

HTTP StatusError CodeDescription
401unauthorizedAPI key is missing or invalid
404not_foundNo audience exists with the specified ID

​
Next Steps

Creating Audiences

Learn about audience segments

Create Schedule

Schedule a campaign