GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In
Guides

Audiences size

Suggest Edits

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
POSTaccounts/{account-id}/audiences/compute-sizesCompute audiences sizes
POSTaccounts/{account-id}/audiences/estimate-sizeEstimate 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.

accounts/{account-id}/audiences/compute-sizes

Parameters

NameLocationFormatDescription
account-idpathstringThe account ID for which the audience sizes are being computed.
idsbodystring[]List of audience IDs to compute their sizes. These must reference existing, saved audience definitions.
channelbodyChannelThe channel (Onsite or Offsite) to compute the audience’s size.
idresponsestringThe ID of the audience for which size has been computed.
sizeresponsenumberReach in absolute number of users (e.g., 150,300 users). Not returned if the user lacks permission to view it.
relativeSizeresponsenumberReach in number of users relative to the retailer’s total audience (e.g., 0.5523 = 55.23%).

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.

accounts/{account-id}/audiences/estimate-size

Parameters

NameLocationFormatDescription
account-idpathstringThe accountId of the audience.
retailerIdbodystringRetailer associated with the audience.
algebrabodyAlgebraNodeAlgebra definition with the precise combination of segments to target
channelbodyChannelThe channel (Onsite or Offsite) to estimate the audience’s size.
sizeresponsenumberReach in absolute number of users (e.g., 150,300 users). Not present when the user lacks permissions to view it.
relativeSizeresponsenumberReach in number of users relative to the total users of a retailer (e.g., 0.5523, which is equivalent to 55.23% users).

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 CodeDescription
audience-not-foundThe audience was not found.
audience-size-not-availableThe audience size is currently being calculated. It will be available soon.
audience-size-not-supportedThe size cannot be calculated for this audience.
audience-segment-size-too-smallSize is below the minimum: 5000.

Updated about 16 hours ago

What’s Next