Get audiences

GET

/api/v1/public/audiences

Retrieve audiences for an account, optionally filtered by website or state. When ruleId is provided, returns a single audience by ID.

Filtering

• Filter by websiteId to scope results to a specific website
• Filter by state to retrieve live or stopped audiences (default: live)
• Use ruleId to fetch a single specific audience by its ID - returns { audience } instead of { audiences }

Notes

• All timestamp fields are in Unix timestamp format (milliseconds)
• Rules are stored as JSON strings and need to be parsed
• Priority (prio) determines execution order when multiple audiences could apply
• The variants array contains the different variations being tested

Parameters

Header Parameters

x-api-key

required

string

Your API key from account settings.

x-user-email

required

string

The email address of your user.

x-account-id

required

string

The ID of your account. You can find this in the account settings.

x-website-id

required

string

The ID of the workspace you want to use.

Query Parameters

ruleId

string format: uuid

Fetch a single audience by its ID. When provided, the response shape is { audience } instead of { audiences }.

state

string

default: live

Allowed values: live stopped

Filter by audience state. Defaults to live (all non-stopped audiences). Use stopped to retrieve stopped audiences.

Responses

200

Successful response with list of audiences.

object

audiences

Array<object>

object

accountId

The account ID that owns this audience.

string

websiteId

The website this audience belongs to.

string

ruleId

Unique identifier for this audience.

string

name

Display name of the audience.

string

state

Current state of the audience.

string

Allowed values: draft live stopped

rule

JSON string containing the targeting rule expression.

string

duration

One of:

number

number

string

string

Allowed values: session

durationType

Unit for the duration field.

string

Allowed values: minutes hours days

createdDate

Unix timestamp (ms) when the audience was created.

number

updatedDate

Unix timestamp (ms) when the audience was last updated.

number

disabled

Whether the audience is disabled. Disabled audiences are excluded from evaluation.

boolean

readOnly

Whether this audience can be modified.

boolean

audienceTags

Tags used to categorise and filter audiences.

Array<string>

Example

{
  "audiences": [
    {
      "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "websiteId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "ruleId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Homepage hero optimization",
      "state": "live",
      "prio": 100,
      "rule": "{\"and\":[{\"field\":\"url\",\"operator\":\"equals\",\"value\":\"/\"}]}",
      "startDate": 1640995200000,
      "createdDate": 1640995200000,
      "updatedDate": 1641081600000,
      "webPagePath": "/",
      "exclusive": false,
      "isComponent": false,
      "variants": [
        {
          "id": "control",
          "name": "Control",
          "weight": 50
        },
        {
          "id": "variation-1",
          "name": "New hero design",
          "weight": 50
        }
      ]
    }
  ]
}

400

Bad request - invalid parameters.

401

Unauthorized - invalid API key.

403

Forbidden - insufficient permissions.