GuidesAPI ReferenceChangelogDiscussions
GuidesAPI ReferenceChangelogLog In

API Response

  • Our APIs respond with data, errors, and metadata blocks where appropriate

  • For example, metadata appears only for paginated responses

  • A response expected to return multiple entities may contain both data and errors blocks

  • Entity IDs are unique across all Retail Media entities

    "data": [
            "type": "{entityType}",
            "id": "{entityId}",
            "attributes": {
                "{fieldName}": {numericValue},
                "{fieldName}": "{stringValue}",
                // ...
        // ...
    "errors": [
            "traceId": "{traceId}",
            "type": "{errorType}",
            "code": "{errorCode}",
            "instance": "{uri}",
            "title": "{errorTitle}",
            "detail": "{errorDetail}",
            "source": {
                "{fieldName}": "{fieldPath}",
                // ...
        // ...
    "metadata": {
        "totalItemsAcrossAllPages": {numberOfEntities},
        "currentPageSize": {pageSize},
        "currentPageIndex": {pageIndex},
        "totalPages": {numberOfPages},
        "nextPage": "https://{endpoint}?pageIndex={pageIndex}&pageSize={pageSize}",
        "previousPage": "https://{endpoint}?pageIndex={pageIndex}&pageSize={pageSize}"

Data Attributes

id stringUnique ID for the entity; entity IDs are unique across all Retail Media entities
type stringType of entity
attributes objectEntity attributes; may be omitted entirely if an entity does not have additional attributes

Error Attributes

traceId stringUnique ID for the error response
type stringType of error; machine-readable (eg. validation)
code stringShort machine-readable string for the error (eg. required-field)
instance stringURI referencing the endpoint that caused the error
title stringShort human-readable string that summarizes the issue
detail stringHuman-readable explanation of the issue
source objectObject referencing the field that caused the error


  • Pagination is supported via query parameters for a subset of endpoints that list multiple entities

  • Results are returned in ascending order by id

  1. List all Accounts associated with your API credentials

  2. List all Brands associated with the Account

  3. List all Retailers associated with the Account

  4. List all Campaigns within the Account

  5. List all Line Items within the Campaign

  6. List all Promoted Products on the Line Item

  7. List all Balances on the Account

  8. List all Campaigns on the Balance

Query ParametersDescription
pageIndex integerReturns the specified page of results given a pageSize; pages are 0-indexed
pageSize integerSpecifies the maximum number of entities returned in a single page; defaults to 25 entities per page
limitToId integerLimits results to the entity IDs specified; parameter key is repeated, eg. limitToId=1&limitToId=2

HTTP Response Codes

:large-blue-circle: 200 OKRequest successful
:large-blue-circle: 201 CreatedThe new entity was successfully created.
:circl 207 Multi-StatusThis may occur when operating on multiple entities, such as the call resulting in some successes but also some failures
:red-circle: 400 Bad RequestFor improper syntax, check your call structure.
:red-circle: 401 UnauthorizedIf unauthenticated, refresh your access token.
:red-circle: 403 ForbiddenInsufficient rights to perform this action
:red-circle: 404 Not FoundResource not found, check your entity IDs in the call.
:red-circle: 408 TimeoutRequest timed out
:red-circle: 409 ConflictRequest conflicts with something, such as a campaign name that already exists
:red-circle: 429 Too Many RequestsToo many requests
:red-circle: 5xxSomething's wrong on Criteo's end...