GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

Audience Segments size

Suggest Edits

Introduction

The "audience-segments sizes" endpoints allow estimating (estimate endpoint) and retrieving (computeendpoint) the size of one or more audience-segments.

⚠️

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

Comparative use of estimate VS compute endpoints

Featurecompute Segment Endpointestimate Segment Endpoint
PurposeComputes size for one or more previously saved segments by ID.Provides a quick size estimation for a specific segment.
Input DefinitionRequires a list of saved segment IDs.A single segment ID is provided inline.
Use CaseUsed for analyzing reach of known, existing segments.Ideal for testing or previewing a specific segment.
Segment SourceSegment definitions are already stored in the system.Segment reference is passed directly in the request payload.
Response FormatReturns an array of segment sizes, one per provided ID.Returns a single segment size object.
Channel SpecificationRequired in the request payload.Required in the request payload.

Endpoints

MethodPathDescription
POST/accounts/{accountId}/audience-segments/compute-sizesCompute audience segment(s) size
POST/accounts/{accountId}/audience-segments/estimate-sizeEstimate audience-segment size

Compute Audience Segment(s) sizes

This endpoint returns the size computation for an audience-segment (if available and if supported). If the size cannot be estimated, an error is returned.

https://api.criteo.com/preview/retail-media/accounts/{accountId}/audience-segments/compute-sizes

Audience Segment Size Computation Attributes

NameFormatDescription
id/ids*string / listAudience Segment 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 Segment, generated internally by Criteo

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

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/audience-segments/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/audience-segments/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/audience-segments/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/audience-segments/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": "RetailMediaAudienceSegment",
            "attributes": {
                "size": 194730,
                "relativeSize" : 0.5523
            }
        },
        {
            "id": "1002", 
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "size": 4285,
                "relativeSize" : 0.5523
            }
        },
        {
            "id": "1003", 
            "type": "RetailMediaAudienceSegment",
            "attributes": {
                "size": 978597,
                "relativeSize" : 0.5523
            }
        }
    ]
}

Sample response: different errors at audience-level returned from response code 200

{
    "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",
            // ...
        }
    ],
    "warnings": []
}

Estimate Audience Segment size

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

https://api.criteo.com/preview/retail-media/accounts/{accountId}/audience-segments/estimate-size

Audience Segment Size Estimation Attributes

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

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

Accepted values: string of int64
Writeable? N / Nullable? N
channelenumChannel associated to the Audience Segment

Accepted values: Onsite, Offsite (case-insensitive)
Writeable? N / Nullable? N
events*objectSettings to target users based on their events.

Accepted values: see below for more details
Writeable? N / Nullable? N
sizenumberReach in absolute number of users (e.g., 150,300 users). Not present when the user lacks permissions to view it.
relativeSizenumberReach relative to the retailer’s total user base (e.g., 0.5523 = 55.23%).

(*) Required in body when requesting size estimation

Events Segment Attributes

AttributeData TypeDescription
shopperActivityenumActivity type performed by the desired target users in the retailer's environment

Accepted values: View, Buy, AddToCart, Unknown
Writeable? N / Nullable? N
lookbackDaysenumTimeframe of the interaction performed by the desired target users in the retailer's environment

Accepted values: Last7Days, Last14Days, Last30Days, Last45Days, Last60Days, Last90Days, Last120Days, Last150Days, Last180Days
Writeable? N / Nullable? N
categoryIdslistDefine users interested in specific categories from retailer's Catalog.
Note, either one of categoryIds or brandIds must be included. Both can be included as well, but the request will fail if neither are included

Accepted values: array of strings/int64
Writeable? N / Nullable? Y
brandIdslistDefine users who performed the activity type above in specific brands from retailer's Catalog.
Note, either one of categoryIds or brandIds must be included. Both can be included as well, but the request will fail if neither are included

Accepted values: array of strings/int64
Writeable? N / Nullable? Y
minPricedecimalDefine users who interact with products whose prices are greater than minPrice

Accepted values: minPrice ≥ 0.0 (or null)
Writeable? N / Nullable? Y
maxPricedecimalDefine users who interact with products whose prices are smaller than maxPrice

Accepted values: maxPrice ≥ 0.0 (or null)
Writeable? N / Nullable? Y

Sample request

curl -L -X POST 'https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audience-segments/estimate-size' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
        "data": {
          "attributes": {
            "retailerId": "1234",
            "channel": "Onsite",
            "events": {
              "shopperActivity": "Buy",
              "lookbackDays": "Last14Days",
              "categoryIds": [
                  "123",
                  "456",
                  "789"
                ],
              "brandIds": [
                  "123456"
              ],
              "minPrice": 1,
              "maxPrice": 300
            }
          }
        }
      }' 

import http.client
import json

conn = http.client.HTTPSConnection("api.criteo.com")
payload = json.dumps({
  "data": {
    "attributes": {
      "retailerId": "1234",
      "channel": "Onsite",
      "events": {
        "shopperActivity": "Buy",
        "lookbackDays": "Last14Days",
        "categoryIds": [
            "123",
            "456",
            "789"
          ],
        "brandIds": [
            "123456"
        ],
        "minPrice": 1,
        "maxPrice": 300
      }
    }
  }
})
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
}
conn.request("POST", "/preview/retail-media/accounts/625702934721171442/audience-segments/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\":{\"retailerId\":\"1234\",\"channel\":\"Onsite\",\"events\":{\"shopperActivity\":\"Buy\",\"lookbackDays\":\"Last14Days\",\"categoryIds\":[\"123\",\"456\",\"789\"],\"brandIds\":[\"123456\"],\"minPrice\":1,\"maxPrice\":300}}}}");
Request request = new Request.Builder()
  .url("https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audience-segments/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/audience-segments/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":{"retailerId":"1234","channel":"Onsite","events":{"shopperActivity":"Buy","lookbackDays":"Last14Days","categoryIds":["123","456","789"],"brandIds":["123456"],"minPrice":1,"maxPrice":300}}}}');
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 segment size estimation returned successfully

{
    "data": {
        "type": "RetailMediaAudienceSegment",
        "attributes": {
            "size": 194730,
            "relativeSize": 0.01260
        }
    },
    "warnings": [],
    "errors": []
}

Sample response: estimation error returned from response code 200

{
    "errors": [
        {
            "type": "validation",
            "code": "audience-segment-size-too-small",
            "instance": "/accounts/625702934721171442/audience-segments/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

Updated 11 days ago

What’s Next