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
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/{account-id}/audiences/compute-sizes | Compute audiences sizes |
| POST | accounts/{account-id}/audiences/estimate-size | Estimate audiences sizes |
Compute audience(s) sizes
This endpoint 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/{account-id}/audiences/compute-sizes
Parameters
| Name | Location | Format | Description |
|---|---|---|---|
account-id | path | string | The account ID for which the audience sizes are being computed. |
ids | body | string[] | List of audience IDs to compute their sizes. These must reference existing, saved audience definitions. |
channel | body | Channel | The channel (Onsite or Offsite) to compute the audience’s size. |
id | response | string | The ID of the audience for which size has been computed. |
size | response | number | Reach in absolute number of users (e.g., 150,300 users). Not returned if the user lacks permission to view it. |
relativeSize | response | number | Reach in number of users relative to the retailer’s total audience (e.g., 0.5523 = 55.23%). |
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
{
"data": {
"attributes":
{
"ids": ["1001", "1002", 1003"],
"channel": "Onsite" // or Offsite
}
}
}
Sample response - success
{
"data": [
{
"id": "1001",
"type": "AudienceSize",
"attributes": {
"size": 194730,
"relativeSize" : 0.5523
}
},
{
"id": "1002",
"type": "AudienceSize",
"attributes": {
"size": 4285,
"relativeSize" : 0.5523
}
},
{
"id": "1003",
"type": "AudienceSize",
"attributes": {
"size": 978597,
"relativeSize" : 0.5523
}
}
]
}
Sample response - error
{
"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": [ /* omitted if no warnings */
...
]
}
Estimate audience(s) 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/{account-id}/audiences/estimate-size
Parameters
| Name | Location | Format | Description |
|---|---|---|---|
account-id | path | string | The accountId of the audience. |
retailerId | body | string | Retailer associated with the audience. |
algebra | body | AlgebraNode | Algebra definition with the precise combination of segments to target |
channel | body | Channel | The channel (Onsite or Offsite) to estimate the audience’s size. |
size | response | number | Reach in absolute number of users (e.g., 150,300 users). Not present when the user lacks permissions to view it. |
relativeSize | response | number | Reach in number of users relative to the total users of a retailer (e.g., 0.5523, which is equivalent to 55.23% users). |
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
{
"data": {
"type": "Audience",
"attributes": {
"retailerId": "12",
"algebra": {
"and": [
"string"
],
"or": [
"string"
],
"not": "string",
"audienceSegmentId": "string"
},
"channel": "Onsite" // Values : Onsite,Offsite
}
}
}
Sample response - success
{
"data": {
"type": "AudienceSize",
"attributes": {
"size": 194730,
"relativeSize": 0.01260
}
}
}
Sample response - error
{
"errors": [
{
"type": "validation",
"code": "audience-size-too-small",
"instance": "/accounts/{account-id}/audiences/estimate-size",
...
}
],
"warnings": [ /* omitted if no warnings */
...
]
}
Errors and Warnings
The following errors and warnings are returned for the sizing endpoints. Additionally, for the estimation size endpoints, the payloads are validated through our API validation rules, similar to the create endpoints.
| Error Code | Description |
|---|---|
audience-not-found | The audience was not found. |
audience-size-not-available | The audience size is currently being calculated. It will be available soon. |
audience-size-not-supported | The size cannot be calculated for this audience. |
audience-segment-size-too-small | Size is below the minimum: 5000. |
Updated 12 days ago
What’s Next