Search for Creatives

Introduction

In our stable versions, we currently offer three different endpoints to fetch information on creatives:

/retail-media/accounts/:account-id/creativesdocumented here,
/retail-media/accounts/:account-id/creatives/:creative-iddocumented here,
/retail-media/accounts/:account-id/creatives/search?creative-ids=<string>&creative-ids=<string>documented here.

To modernize pagination and make creative retrieval more efficient, we are consolidating these endpoints into a single endpoint, described on this page. This simplifies the workflow by reducing both the number of API calls and the steps needed to reach the desired result.

Endpoint

Verb	Endpoint	Description
`POST`	`/retail-media/accounts/{externalAccountId}/creatives/search`	Search for creatives by external account ID

Attributes

Attribute	Data Type	Description
`creativeName`	`string`	The name of the creative. Accepted values: string Default: all Writeable? Y / Nullable? Y
`creativeIds`	`list`	Creative ID, generated internally by Criteo. Accepted values: int64 Default: all Writeable? Y / Nullable? Y
`creativeTypes`	`list`	The types of creatives available, there are four acceptable values that can be used in combination or a single one if desired: `Commerce Video`- When the ad unit contains a video & SKUs. `Standard Video`- When the ad unit contains a video only `Commerce Display`- When the ad unit contains a static image & SKUs. `Standard Display`- When the ad unit contains a static image only. Accepted values are case-insensitive. Accepted values: string Default: all Writeable? Y / Nullable? Y
`brandIds`	`list`	Brand ID, generated internally by Criteo and originated from brand name provided in retailer’s Catalog Accepted values: int64 Default: all Writeable? Y / Nullable? Y
`templateIds`	`list`	The unique ID of the Creative template. Accepted values: int64 Default: all Writeable? Y / Nullable? Y
`retailerIds`	`list`	List of Retailer IDs, to use as filter in the search or returned as containing the specific brand Accepted values: list of strings of int32 Default: all Writeable? Y / Nullable? Y
`pageTypes`	`list`	Type page type the creative is designed for. There are eleven acceptable values that can be used in combination or a single one if desired: `Search` `Home` `Checkout` `Category` `ProductDetail` `Confirmation` `Merchandising` `Deals` `Favorites` `SearchBar` `CategoryMenu` Accepted values are case-insensitive Accepted Values: string Default: all Writeable? N / Nullable? N

All of the filters are optional and do not need to be input to run a successful request. In the query parameter there is a limit that can be applied as well:

The default limit is 50 if it is not included in the request.
The maximum that a user can input is 500 in the request. A user will run into a 400 error in the event they attempt to go beyond this limit.

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.

This endpoint returns a list of creatives based on the provided filters. When more than one filter is supplied, all filters must be satisfied (logical AND expression). You can also search for creatives by external account ID. Request example

{
    "data": {
        "attributes": {
            "CreativeName": "test"
            "CreativeIds": ["758332652442947584","641313640540434432"],
            "CreativeTypes":["CommerceVideo","StandardVideo","CommerceDisplay","StandardDisplay"],
            "BrandIds": [88092],
            "TemplateIds": [7,357],
            "RetailerIds": [1209,1290],
            "PageTypes": ["Search","Home","Browse","Checkout","Category","ProductDetail","Confirmation","Merchandising","Deals","Favorites","SearchBar","CategoryMenu"]                    
        }
    }
}

Response example

{
    "metadata": {
        "count": 1,
        "offset": 0,
        "limit": 50
    },
    "data": [
        {
            "id": "773514522353370000",
            "type": "CreativeSearchResponse",
            "attributes": {
                "name": "test",
                "status": "Ready",
                "lineItems": [],
                "retailerId": "1234",
                "modifiedAt": "2025-11-04T11:50:33.3237295+00:00",
                "createdAt": "2025-11-04T11:50:33.3237295+00:00",
                "brandId": "900",
                "creativeType": "CommerceVideo",
                "pageType": [],
                "preview": "https://retailmedia-static.criteo.com/creativeassets-live/cd8d6ef2de9407b2c5721425e938e7c715dfafca12eaff932fd9f7e38a632789.jpg",
                "templateId": "123"
            }
        }
    ],
    "warnings": [],
    "errors": []
}

Responses

Code	Reason	Client Exposed Message
🔴`400`	Validation issue: provided invalid offset and limit (either negative numbers or limit above the maximum).	Offset and limit should be non-negative OR Limit exceeds the maximum
🔴`403`	`access forbidden`: the user doesn’t have access to the account they are searching for.

Code

Reason

Client Exposed Message

🔴400

Validation issue: provided invalid offset and limit (either negative numbers or limit above the maximum).

Offset and limit should be non-negative

Limit exceeds the maximum

🔴403

access forbidden: the user doesn’t have access to the account they are searching for.

​Introduction

​Endpoint

​Attributes