Audiences Size - Criteo Docs

Introduction

The “audiences sizes” endpoints allow estimating (estimate endpoint) and retrieving (computeendpoint) the size of one or more audiences.

Comparative use of `estimate` VS `compute` endpoints

Feature	`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.

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	AccountID 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.0 Writeable? 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

The Estimate endpoints are resource-intensive; therefore, bulk processing is not supported.

Returns the size estimation for an audience (if available and if supported). If the size cannot be estimated, an error is returned.

Audience Size Estimation Attributes

Name	Format	Description
`accountId`	string	AccountID associated with the Audience, generated internally by Criteo Accepted values: string of int64 Writeable? N / Nullable? N
`retailerId`*	string	RetailerID 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 to create the audience, using logical operators`and`,`or`and`not` Accepted values: seeAlgebra 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.0 Writeable? 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 inAuthorization Requests the account or audience ID(s) provided in the request

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 inAuthorization Requests
the account or audience ID(s) provided in the request

Errors and Warnings

`audience-size-not-available`

Error: Audience size not available
Message: The audience size is currently not available.

`audience-size-too-small`

Error: Audience size is too small
Message: Size is below the minimum: 20.

What’s next

Audience-segments size

​Introduction

​Comparative use of estimate VS compute endpoints

​Endpoints

​Compute Audience(s) sizes

​Audience Size Computation Attributes

​Estimate Audience size

​Audience Size Estimation Attributes

​Responses

​Errors and Warnings

​audience-size-not-available

​audience-size-too-small

​What’s next

Introduction

Comparative use of `estimate` VS `compute` endpoints

Endpoints

Compute Audience(s) sizes

Audience Size Computation Attributes

Estimate Audience size

Audience Size Estimation Attributes

Responses

Errors and Warnings

`audience-size-not-available`

`audience-size-too-small`

What’s next