> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audience Endpoints

## **Endpoints**

| Verb     | Endpoint                                               | Description                                                                                                                                                                                       |
| -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **POST** | `/retail-media/accounts/{account-id}/audiences/search` | Returns a list of audiences that match the provided filters. If present, the filters are AND'ed together when applied. You can search audiences by audience IDs, retailer IDs and/or segment IDs. |

 

## **Audience Attributes**

| Attribute      | Data Type | Description                                                                                                                                                                                                                                                                   |
| -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | string    | Audience ID, generated internally by CriteoAccepted values: string of int64 Writeable? N / Nullable? N                                                                                                                                                                        |
| `name`         | string    | Audience nameAccepted values: string Writeable? Y / Nullable? N                                                                                                                                                                                                               |
| `description`  | string    | Description of the AudienceAccepted values: string Writeable? Y / Nullable? N                                                                                                                                                                                                 |
| `accountId`    | string    | [Account](/retail-media/v2025.04/docs/account) ID associated with the Audience, generated internally by CriteoAccepted values: string of int64 Writeable? N / Nullable? N                                                                                                     |
| `retailerId`\* | string    | [Retailer](/retail-media/v2025.04/docs/retailers) ID, associated with the Audience Segment, generated internally by CriteoAccepted values: string of int64 Writeable? N / Nullable? N                                                                                         |
| `algebra`      | object    | Algebra node with the definition of how the different audience segments are combined together to create the audience, using logical operators `and`, `or` and `not`Accepted values: see [Algebra Nodes](/retail-media/v2025.04/docs/algebra-nodes) Writeable? N / Nullable? N |
| `createdAt`    | timestamp | Timestamp of Audience creation, in UTCAccepted values: `yyyy-mm-ddThh:mm:ss.msZ` (in [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) ) Writeable? N / Nullable? N                                                                                          |
| `createdById`  | string    | User ID who created the Audience (`null` if created by a service)Accepted values: string Writeable? N / Nullable? Y                                                                                                                                                           |
| `updatedAt`    | timestamp | Timestamp of last Audience update, in UTCAccepted values: `yyyy-mm-ddThh:mm:ss.msZ`(in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601)) Writeable? N / Nullable? N                                                                                                         |

*\*Required at create operation*

## **Search Audiences**

This endpoint returns a list of audiences that match the provided filters. If present, the filters are AND'ed together when applied. You can search audiences by audience IDs, retailer IDs and/or segment IDs.

Results are paginated using `offset` and `limit` query parameters; if omitted, defaults to `0` and `500`, respectively - see [API Response](/retail-media/docs/api-response#/pagination)

**Sample Request: searching by Retailer ID only**

<CodeGroup>
  ```bash cURL theme={null}
  curl -L -X POST 'https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/search' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
  -d '{
    "data": {
      "type": "Audience",
      "attributes": {
        "audienceIds": null,
        "retailerIds": [
          "12"
        ],
        "audienceSegmentIds": null
      }
    }
  }
  ```
</CodeGroup>

**Sample Response**

<CodeGroup>
  ```json JSON expandable theme={null}
  {
      "meta": {
          "totalItems": 400,
          "limit": 50,
          "offset": 0
      },
      "data": [
          {
              "attributes": {
                  "name": "My audience A",
                  "description": null,
                  "createdAt": "2024-01-12T11:46:13.77Z",
                  "updatedAt": "2024-02-12T11:46:13.77Z",
                  "accountId": "625702934721171442",
                  "retailerId": "12",
                  "algebra": {
                      "audienceSegmentId": "56159923678901880"
                  },
                  "createdById": "j.doe"
              },
              "id": "258216562069631686",
              "type": "RetailMediaAudience"
          },
          // ...
          {
              "attributes": {
                  "name": "My audience B",
                  "description": null,
                  "createdAt": "2024-01-22T14:41:32.489Z",
                  "updatedAt": "2024-01-22T14:41:32.489Z",
                  "accountId": "625702934721171442",
                  "retailerId": "12",
                  "algebra": {
                      "audienceSegmentId": "225702933721195672"
                  },
                  "createdById": "a.jack"
              },
              "id": "920472839472539402",
              "type": "RetailMediaAudience"
          }
      ],
      /* omitted if no errors */
      "errors": [],
      /* omitted if no warnings */
      "warnings": []
  }
  ```
</CodeGroup>

**Sample Request: searching by multiple filters**

<CodeGroup>
  ```bash cURL theme={null}
  curl -L -X POST 'https://api.criteo.com/preview/retail-media/accounts/625702934721171442/audiences/search' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
  -d '{
    "data": {
      "type": "Audience",
      "attributes": {
        "audienceIds": ["920472839472539402"],
        "retailerIds": [
          "12"
        ],
        "audienceSegmentIds": ["225702933721195672"]
      }
    }
  }
  ```
</CodeGroup>

**Sample Response**

<CodeGroup>
  ```json JSON theme={null}
  {
      "meta": {
          "totalItems": 400,
          "limit": 50,
          "offset": 0
      },
      "data": [
          {
              "attributes": {
                  "name": "My audience",
                  "description": null,
                  "createdAt": "2024-01-22T14:41:32.489Z",
                  "updatedAt": "2024-01-22T14:41:32.489Z",
                  "accountId": "625702934721171442",
                  "retailerId": "12",
                  "algebra": {
                      "audienceSegmentId": "225702933721195672"
                  },
                  "createdById": "a.jack"
              },
              "id": "920472839472539402",
              "type": "RetailMediaAudience"
          }
      ],
      /* omitted if no errors */
      "errors": [],
      /* omitted if no warnings */
      "warnings": []
  }
  ```
</CodeGroup>