Audiences size
Introduction
The "audiences sizes" endpoints allow estimating (estimate
endpoint) and retrieving (compute
endpoint) the size of one or more audiences.
Those endpoints are resource-intensive; therefore, bulk processing is not supported.
Comparative use of estimate
VS compute
endpoints
estimate
VS compute
endpointsFeature | compute Audience Endpoint | estimate Audience Endpoint |
---|---|---|
Purpose | Computes size for one or more previously saved audiences by ID. | Provides a quick size estimation for a dynamically defined audience. |
Input Definition | Requires a list of saved audience IDs. | Audience is defined inline using logical structure (algebra ). |
Use Case | Used for analyzing reach of known, existing audience resources. | Ideal for previewing potential audience reach during design. |
Audience Composition | Audience composition is already stored in the system. | Expressed directly in the request payload using and , or , not . |
Response Format | Returns an array of audience sizes, one per provided ID. | Returns a single audience size object. |
Channel Specification | Required in the request payload. | Required in the request payload. |
Endpoints
Method | Path | Description |
---|---|---|
POST | /accounts/{accountId}/audiences/compute-sizes | Compute audience(s) sizes |
POST | /accounts/{accountId}/audiences/estimate-size | Estimate audience sizes |
Compute Audience(s) sizes
This endpoint returns the size computation for one or multiple audiences (if available and if supported). If the size cannot be estimated, an error is returned.

https://api.criteo.com/preview/retail-media/accounts/{accountId}/audiences/compute-sizes
Audience Size Computation Attributes
Name | Format | Description |
---|---|---|
id /ids * | string / list | Audience ID(s), generated internally by Criteo, to which the computation(s) are required Accepted values: string of int64 / list of strings of int64 Writeable? N / Nullable? N |
accountId | string | Account ID associated with the Audience, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N |
channel * | enum | Channels associated to the audience Accepted values: Onsite , Offsite (case-insensitive)Writeable? N / Nullable? N |
size | integer | Reach in absolute number of users (e.g., 150,300 users). Not returned if the user lacks permission to view it. Accepted values: size ≥ 0 (or null )Writeable? N / Nullable? Y |
relativeSize | decimal | Reach in number of users relative to the retailer’s total audience (e.g., 0.5523 = 55.23%). Accepted values: 0.0 ≤ relativeSize ≤ 1.0Writeable? N / Nullable? N |
(*) Required in body when requesting computation
Field Definitions
- Writeable (Y/N): Indicates if the field can be modified in requests.
- Nullable (Y/N): Indicates if the field can accept null/empty values.
- Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g.,
retailerId
,campaignId
,lineItemId
) and are usually required in the URL path.
Sample request
curl -L -X POST 'https://api.criteo.com/{version}/retail-media/campaigns/625702934721171442/audiences/compute-sizes' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
"data": {
"attributes": {
"ids": [
"1001",
"1002",
"1003"
],
"channel": "Onsite"
}
}
}'
import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
"data": {
"attributes": {
"ids": [
"1001",
"1002",
"1003"
],
"channel": "Onsite"
}
}
})
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}
conn.request("POST", "/preview/retail-media/accounts/625702934721171442/audiences/compute-sizes", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "\"data\":{\"attributes\":{\"ids\":[\"1001\",\"1002\",\"1003\"],\"channel\":\"Onsite\"}}");
Request request = new Request.Builder()
.url("https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/compute-sizes")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Accept", "application/json")
.addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
.build();
Response response = client.newCall(request).execute();
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/compute-sizes');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
$request->setBody('{"data":{"attributes":{"ids":["1001","1002","1003"],"channel":"Onsite"}}}');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status:' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error:' . $e->getMessage();
}
Sample response: audience size computations returned successfully
{
"data": [
{
"id": "1001",
"type": "RetailMediaAudience",
"attributes": {
"size": 194730,
"relativeSize" : 0.5523
}
},
{
"id": "1002",
"type": "RetailMediaAudience",
"attributes": {
"size": 4285,
"relativeSize" : 0.5523
}
},
{
"id": "1003",
"type": "RetailMediaAudience",
"attributes": {
"size": 978597,
"relativeSize" : 0.5523
}
}
],
"warnings": [],
"errors": []
}
Sample response: different errors at audience-level returned from response code 200
{
"data": [],
"warnings": [],
"errors": [
{
"type": "validation",
"code": "audience-not-found",
"instance": "@data/0",
// ...
},
{
"type": "validation",
"code": "audience-size-not-available",
"instance": "@data/1",
// ...
},
{
"type": "validation",
"code": "audience-size-not-supported",
"instance": "@data/2",
// ...
}
]
}
Estimate Audience size
Returns the size estimation for an audience (if available and if supported). If the size cannot be estimated, an error is returned.

https://api.criteo.com/preview/retail-media/accounts/{accountId}/audiences/estimate-size
Audience Size Estimation Attributes
Name | Format | Description |
---|---|---|
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, 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 |
channel * | enum | Channels associated to the Audience Accepted values: Onsite , Offsite (case-insensitive)Writeable? N / Nullable? N |
size | integer | Reach in absolute number of users (e.g., 150,300 users). Not returned if the user lacks permission to view it. Accepted values: size ≥ 0 (or null )Writeable? N / Nullable? Y |
relativeSize | decimal | Reach in number of users relative to the retailer’s total audience (e.g., 0.5523 = 55.23%). Accepted values: 0.0 ≤ relativeSize ≤ 1.0Writeable? N / Nullable? N |
(*) Required in body when requesting size estimation
Field Definitions
- Writeable (Y/N): Indicates if the field can be modified in requests.
- Nullable (Y/N): Indicates if the field can accept null/empty values.
- Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g.,
retailerId
,campaignId
,lineItemId
) and are usually required in the URL path.
Sample request
curl -L -X POST 'https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/estimate-size' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
"data": {
"attributes": {
"algebra": {
"audienceSegmentId": "731050100467716096"
},
"retailerId": "1234",
"channel": "Onsite"
}
}
}'
import http.client
import json
conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
"data": {
"attributes": {
"algebra": {
"audienceSegmentId": "731050100467716096"
},
"retailerId": "1234",
"channel": "Onsite"
}
}
})
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}
conn.request("POST", "/preview/retail-media/accounts/625702934721171442/audiences/estimate-size", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"data\":{\"attributes\":{\"algebra\":{\"audienceSegmentId\":\"731050100467716096\"},\"retailerId\":\"1234\",\"channel\":\"Onsite\"}}}");
Request request = new Request.Builder()
.url("https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/estimate-size")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Accept", "application/json")
.addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
.build();
Response response = client.newCall(request).execute();
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/estimate-size');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
));
$request->setBody('{"data":{"attributes":{"algebra":{"audienceSegmentId":"731050100467716096"},"retailerId":"1234","channel":"Onsite"}} }');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status:' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error:' . $e->getMessage();
}
Sample response: audience size estimation returned successfully
{
"data": {
"type": "ExternalRMAudienceSizeEstimationV1",
"attributes": {
"size": 194730,
"relativeSize": 0.01260
}
},
"warnings": [],
"errors": []
}
Sample response: estimation error returned from response code 200
{
"errors": [
{
"type": "validation",
"code": "audience-size-too-small",
"instance": "/accounts/625702934721171442/audiences/estimate-size",
// ...
}
],
"warnings": []
}
Responses
Response | Description |
---|---|
🟢 200 | Call completed successfully (or audience-level errors returned with specific details) |
🔴 400 | Retailer must be authorized in provided account. Review the retailer ID provided |
🔴 403 | One of the permission levels was not respected. Make sure that the respective API app has access to: - Read/Manage the domain "Audiences" (depending on the requested action). Review the Types of Permissions in Authorization Requests - the account or audience ID(s) provided in the request |
Updated 11 days ago