Audience-segments size

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

Feature	`compute` Segment Endpoint	`estimate` Segment Endpoint
Purpose	Computes size for one or more previously saved segments by ID.	Provides a quick size estimation for a specific segment.
Input Definition	Requires a list of saved segment IDs.	A single segment ID is provided inline.
Use Case	Used for analyzing reach of known, existing segments.	Ideal for testing or previewing a specific segment.
Segment Source	Segment definitions are already stored in the system.	Segment reference is passed directly in the request payload.
Response Format	Returns an array of segment sizes, one per provided ID.	Returns a single segment size object.
Channel Specification	Required in the request payload.	Required in the request payload.

Endpoints

Method	Path	Description
POST	`accounts/{account-id}/audience-segments/compute-sizes`	Compute audience-segments size
POST	`accounts/{account-id}/audience-segments/estimate-size`	Estimate audience-segments size

Compute audience(s) sizes

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

accounts/{account-id}/audience-segments/compute-sizes\`

Parameters

Name	Location	Format	Description
`account-id`	path	`string`	The account ID of the audience segment.
`ids`	body	`string[]`	The audience segment IDs to compute their sizes. These must reference existing, saved segment definitions.
`channel`	body	`Channel`	The channel (`Onsite` or `Offsite`) to compute the audience segment’s size.
`id`	response	`string`	The ID of the audience segment for which size has been computed.
`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 = 55.23% users).

Sample request

{
  "data": {
    "attributes":
	{
	  "ids": ["1001", "1002", 1003"],
	  "channel": "Onsite" // or Offsite
	}
  }
}

Sample response - success

{
    "data": [
        {
            "id": "1001", 
            "type": "AudienceSegmentSize",
            "attributes": {
                "size": 194730,
                "relativeSize" : 0.5523
            }
        },
        {
            "id": "1002", 
            "type": "AudienceSegmentSize",
            "attributes": {
                "size": 4285,
                "relativeSize" : 0.5523
            }
        },
        {
            "id": "1003", 
            "type": "AudienceSegmentSize",
            "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-segment(s) size

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

accounts/{account-id}/audience-segments/estimate-size

Parameters

Name	Location	Format	Description
`account-id`	path	`string`	The account ID of the audience segment.
`retailerId`	body	`string`	Retailer associated with the audience segment.
`channel`	body	`Channel`	The channel (`Onsite` or `Offsite`) to estimate the audience segment’s size.
`events`	body	`EventSetting`	Settings to target users based on shopping events.
`shopperActivity`	body	`ShopperActivity`	Reach people who performed a specific action.
`lookbackDays`	body	`LookbackDays`	Reach people who interacted with the website within the defined timeframe.
`categoryIds`	body	`string[]` (optional)	Reach people interested in the list of categories defined.
`brandIds`	body	`string[]` (optional)	Reach people interested in the list of brands defined.
`minPrice`	body	`decimal` (optional)	Reach people who interacted with products costing more than this value.
`maxPrice`	body	`decimal` (optional)	Reach people who interacted with products costing less than this value.
`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 relative to the retailer’s total user base (e.g., 0.5523 = 55.23%).

Sample request

{
  "data": {
    "type": "AudienceSegment",
    "attributes": {
      "retailerId": "12",
      "channel": "Onsite", // Values : Onsite OR Offsite
      "events": {
        "shopperActivity": "Buy",
        "lookbackDays": "Last14Days",
        "categoryIds": [
          "12"
        ],
        "brandIds": [
          "123"
        ],
        "minPrice": 1,
        "maxPrice": 300
      }
    }
  }
}

Sample response - success

{
    "data": {
        "type": "AudienceSegmentSize",
        "attributes": {
            "size": 194730,
            "relativeSize": 0.01260
        }
    }
}

Sample response - error

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

Introduction

⚠️

Comparative use of estimate VS compute endpoints

Endpoints

Compute audience(s) sizes

Parameters

Sample request

Sample response - success

Sample response - error

Estimate audience-segment(s) size

Parameters

Sample request

Sample response - success

Sample response - error

Errors and Warnings

Comparative use of `estimate` VS `compute` endpoints