Audience Endpoints
Introduction
Audiences give the ability to advertisers to define subsets of retailers visitors to be targeted in their campaigns.
Audiences are built of one or multiple audience segments that can be combined using logical Algebra Nodes to define target campaigns' audiences.
Note on Audience Computation
Audience updates are processed daily at 0h UTC and 12h UTC and can take around 5 hours to reflect on a live campaign. This is important for audiences that are frequently updated as changes should be ready for processing prior to these two times.
Endpoints
Verb | Endpoint | Description |
---|---|---|
POST | /accounts/{account-id}/audiences/search | Search for audiences by audience IDs, retailer IDs and/or segment IDs. |
Audience Attributes
Attribute | Data Type | Description |
---|---|---|
id | string | Audience ID, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
name | string | Audience name Accepted values: string Writeable? Y / Nullable? N |
description | string | Description of the Audience Accepted values: string Writeable? Y / Nullable? N |
accountId | string | Account ID associated with the Audience, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
retailerId * | string | Retailer ID, associated with the Audience Segment, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
algebra | object | Algebra node with the definition of how the different audience segments are combined together to create the audience, using logical operators and , or and not Accepted values: see Algebra Nodes Writeable? N / Nullable? N |
createdAt | timestamp | Timestamp of Audience creation, in UTC Accepted values: yyyy-mm-ddThh:mm:ss.msZ (in ISO-8601 )Writeable? N / Nullable? N |
createdById | string | User ID who created the Audience (null if created by a service)Accepted values: string Writeable? N / Nullable? Y |
updatedAt | timestamp | Timestamp of last Audience update, in UTC Accepted values: yyyy-mm-ddThh:mm:ss.msZ (in ISO-8601)Writeable? N / Nullable? N |
* Required at create operation
Search Audiences
This endpoint returns a list of audiences that match the provided filters. If present, the filters are AND'ed together when applied. You can search audiences by audience IDs, retailer IDs and/or segment IDs.
Results are paginated using offset
and limit
query parameters; if omitted, defaults to 0
and 500
, respective - see API Response

https://api.criteo.com/{version}/retail-media/accounts/{account-id}/audiences/search?offset={offset}&limit={limit)
Sample Request: searching by Retailer ID only
curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audiences/search' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
-d '{
"data": {
"type": "Audience",
"attributes": {
"audienceIds": null,
"retailerIds": [
"12"
],
"audienceSegmentIds": null
}
}
}
Sample Response
{
"meta": {
"totalItems": 400,
"limit": 50,
"offset": 0
},
"data": [
{
"attributes": {
"name": "My audience A",
"description": null,
"createdAt": "2024-01-12T11:46:13.77Z",
"updatedAt": "2024-02-12T11:46:13.77Z",
"accountId": "625702934721171442",
"retailerId": "12",
"algebra": {
"audienceSegmentId": "56159923678901880"
},
"createdById": "j.doe"
},
"id": "258216562069631686",
"type": "RetailMediaAudience"
},
// ...
{
"attributes": {
"name": "My audience B",
"description": null,
"createdAt": "2024-01-22T14:41:32.489Z",
"updatedAt": "2024-01-22T14:41:32.489Z",
"accountId": "625702934721171442",
"retailerId": "12",
"algebra": {
"audienceSegmentId": "225702933721195672"
},
"createdById": "a.jack"
},
"id": "920472839472539402",
"type": "RetailMediaAudience"
}
],
/* omitted if no errors */
"errors": [],
/* omitted if no warnings */
"warnings": []
}
Sample Request: searching by multiple filters
curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/625702934721171442/audiences/search' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
-d '{
"data": {
"type": "Audience",
"attributes": {
"audienceIds": [
"920472839472539402"
],
"retailerIds": [
"12"
],
"audienceSegmentIds": [
"225702933721195672"
]
}
}
}
Sample Response
{
"meta": {
"totalItems": 400,
"limit": 50,
"offset": 0
},
"data": [
{
"attributes": {
"name": "My audience",
"description": null,
"createdAt": "2024-01-22T14:41:32.489Z",
"updatedAt": "2024-01-22T14:41:32.489Z",
"accountId": "625702934721171442",
"retailerId": "12",
"algebra": {
"audienceSegmentId": "225702933721195672"
},
"createdById": "a.jack"
},
"id": "920472839472539402",
"type": "RetailMediaAudience"
}
],
/* omitted if no errors */
"errors": [],
/* omitted if no warnings */
"warnings": []
}
Updated 4 days ago