List audiences within a project

post

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/audiences

Retrieves a list of all audiences defined for a specific project. Audiences segment visitors based on criteria like behavior, demographics, traffic source, or custom data, to target experiences. Supports filtering by status, type, name, and pagination. The Knowledge Base article "Define Audiences for your Experience" explains: "An 'Audience' is a group of visitors that you want to be included in your experience".

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account_id

integer

required

ID of the account that owns the retrieved/saved data

project_id

integer

required

ID of the project to which save/retrieved data is connected

Body Params

onlyCount

boolean

If set to true in a list request, the response will only contain the total count of matching items (extra.pagination.items_count) and will not include the actual item data. Useful for quickly getting totals without fetching full datasets.

results_per_page

integer | null

0 to 50

Defaults to 30

Specifies the maximum number of items to return in a single page of results. Used for pagination. Default is 30, maximum is 50.

sort_direction

string | null

enum

Defaults to desc

The direction for sorting the list results, based on the sort_by field.

asc: Ascending order (e.g., A-Z, 1-10, oldest to newest).
desc: Descending order (e.g., Z-A, 10-1, newest to oldest). Defaults to desc (newest/highest first) if not specified.

Allowed:

status

array of objects | null

List of audience statuses to be returned

status

string | null

a search string that would be used to search against audience's name or description

is_default

boolean | null

A flag to filter audiences by default status

If set to true, only default audiences will be returned, if not set, all audiences will be returned

sort_by

string | null

enum

Defaults to id

A value to sort audiences by specific field

Defaults to id if not provided

Allowed:

type

string | null

enum

Allowed:

experiences

array of integers | null

List of experiences to be returned

experiences

usage

string | null

enum

It indicates wherever retrieved audiences are used or not inside experiences

Allowed:

page

integer

≥ 1

The page number for paginated results. For example, if results_per_page is 30, page: 2 will retrieve items 31-60. Defaults to 1 if not specified.

include

array of objects

Specifies the list of fields to be included in the response, which otherwise would not be sent.

include

only

array of integers | null

Only retrieve audiences with the given ids.

only

except

array of integers

length ≤ 100

Except audiences with the given ids.

except

Responses

200A list of audiences defined within a project. Each audience entry includes its ID, name, type (permanent, transient, segmentation), status, and potentially usage statistics. Audiences define who sees an experience.

defaultIndicates an error occurred while processing the request. The code provides an HTTP status code, message offers a human-readable explanation or an array of validation errors, and fields (if present) specifies which input fields were problematic.