Skip to main content

Audiences REST API

Manage user audiences and segments via the REST API.

Endpoints​

List Audiences​

Get all audiences for an app.

GET /v1/apps/:appId/audiences

Query Parameters:

ParameterTypeDescription
statusstringFilter by status: active, archived
limitnumberNumber of results (default: 20, max: 100)
pagestringPage number

Example Response:

{
  "data": [
    {
      "id": 1,
      "name": "Premium Users",
      "status": "active",
      "customerCount": 1234,
      "lastCalculatedAt": "2025-11-23T14:00:00Z",
      "definition": {
        "logic": "AND",
        "rules": [
          {
            "field": "subscriptionTier",
            "operator": "equals",
            "value": "premium"
          }
        ]
      }
    }
  ]
}

Get Audience​

Get a specific audience by ID.

GET /v1/audiences/:audienceId

Create Audience​

Create a new audience.

POST /v1/apps/:appId/audiences

Request Body:

{
  "name": "Active Users",
  "status": "active",
  "definition": {
    "logic": "AND",
    "rules": [
      {
        "ruleType": "event",
        "eventId": "login",
        "operator": "performed_within",
        "timeWindow": { "value": 30, "unit": "days" }
      }
    ]
  }
}

Update Audience​

Update an existing audience.

PATCH /v1/audiences/:audienceId

Delete Audience​

Delete an audience.

DELETE /v1/audiences/:audienceId

Audience Rules​

Attribute Rules​

Filter by user attributes:

{
  "field": "country",
  "operator": "equals",
  "value": "USA"
}

Event Rules​

Filter by user events:

{
  "ruleType": "event",
  "eventId": "purchased",
  "operator": "has_performed"
}

Time-based Rules​

Filter by recent activity:

{
  "ruleType": "event",
  "eventId": "login",
  "operator": "performed_within",
  "timeWindow": {
    "value": 7,
    "unit": "days"
  }
}

Next Steps​