Audiences size

Introduction

The "audiences sizes" endpoints allow estimating (estimate endpoint) and retrieving (computeendpoint) 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

Featurecompute Audience Endpointestimate Audience Endpoint
PurposeComputes size for one or more previously saved audiences by ID.Provides a quick size estimation for a dynamically defined audience.
Input DefinitionRequires a list of saved audience IDs.Audience is defined inline using logical structure (algebra).
Use CaseUsed for analyzing reach of known, existing audience resources.Ideal for previewing potential audience reach during design.
Audience CompositionAudience composition is already stored in the system.Expressed directly in the request payload using and, or, not.
Response FormatReturns an array of audience sizes, one per provided ID.Returns a single audience size object.
Channel SpecificationRequired in the request payload.Required in the request payload.

Endpoints

MethodPathDescription
POST/accounts/{accountId}/audiences/compute-sizesCompute audience(s) sizes
POST/accounts/{accountId}/audiences/estimate-sizeEstimate 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

NameFormatDescription
id/ids*string / listAudience 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
accountIdstringAccount ID associated with the Audience, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
channel*enumChannels associated to the audience

Accepted values: Onsite, Offsite (case-insensitive)
Writeable? N / Nullable? N
sizeintegerReach 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
relativeSizedecimalReach 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

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

NameFormatDescription
accountIdstringAccount ID associated with the Audience, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
retailerId*stringRetailer ID associated with the Audience, generated internally by Criteo

Accepted values: string of int64
Writeable? N / Nullable? N
algebra*objectAlgebra 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*enumChannels associated to the Audience

Accepted values: Onsite, Offsite (case-insensitive)
Writeable? N / Nullable? N
sizeintegerReach 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
relativeSizedecimalReach 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

ResponseDescription
🟢 200Call completed successfully (or audience-level errors returned with specific details)
🔴 400Retailer must be authorized in provided account. Review the retailer ID provided
🔴 403One 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