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

# Audience Search

> Search the audience catalog by name and meaning, with optional geo, provider, size and CPM filters.

> [!WARNING]
>
> Maximum 100 audiences per request

> [!NOTE]
>
> This endpoint is protected and requires an agency API key for access.

```bash Request theme={null}
  curl --request GET \
    --url 'https://api.growthchannel.io/audiences/search?search=Protein%20bar' \
    --header 'X-Api-Key: YOUR_API_KEY'
```

```bash With filters theme={null}
  curl --request GET \
    --url 'https://api.growthchannel.io/audiences/search?search=Protein%20bar&limit=50&geo=US&min_size=10000&max_size=5000000' \
    --header 'X-Api-Key: YOUR_API_KEY'
```

> **Method**
>
> `GET`

> **Endpoint**
>
> `/audiences/search`

## Ranking

Results are returned in three tiers:

1. **Phrase matches**: the audience name contains the search words in the same order, for example "Protein Bar Buyers" or "Protein-Bar Lovers".
2. **Word matches**: the audience name contains all search words in any order, for example "Bar Protein Fans".
3. **Similar audiences**: audiences close in meaning, for example "Energy Snacks".

Name matching ignores case and word forms: `bars` matches "Bar", `buyer` matches "Buyers". Within each tier the most relevant audiences come first. Each audience appears only once.

## Headers

**X-Api-Key** `string` *required*

The agency's API key for authorization. Contact an admin to get one.

## Parameters

**search** `string` *required*

Text to search for, for example `Protein bar`.

**limit** `integer` (default: 20)

Maximum number of audiences to return, from `20` to `100`. Values below `20` are treated as `20`, values above `100` as `100`.

**geo** `string`

Return only audiences for this geo, for example `US`. Exact match. See [Audience Filters](https://docs.growthchannel.com/api-reference/audience-filters) for available values.

**provider** `string`

Return only audiences from this data provider. Exact match. See [Audience Filters](https://docs.growthchannel.com/api-reference/audience-filters) for available values.

**min\_size** `integer`

Minimum audience size. Applied only together with `max_size`.

**max\_size** `integer`

Maximum audience size. Applied only together with `min_size`.

**min\_cpm** `number`

Minimum CPM, for example `1.5`. Applied only together with `max_cpm`.

**max\_cpm** `number`

Maximum CPM. Applied only together with `min_cpm`.

## Responses

**200 OK**

```json theme={null}
{
  "data": [
    {
      "audience_id": "101",
      "name": "Protein Bar Buyers",
      "taxonomy_path": "Food > Snacks > Protein Bars",
      "description": "Shoppers who bought protein bars in the last 90 days.",
      "geo": "US",
      "size": 1250000,
      "cpm": 1.5
    },
    {
      "audience_id": "102",
      "name": "Bar Protein Fans",
      "taxonomy_path": "Health & Fitness > Nutrition",
      "description": "Fitness enthusiasts interested in protein snacks.",
      "geo": "US",
      "size": 830000,
      "cpm": 1.25
    }
  ]
}
```

**data** `array`

An array of audience objects in ranked order. Contains at most `limit` items, or fewer when the filters leave fewer audiences.

**object**

**audience\_id** `string`

The audience identifier.

**name** `string`

The audience name.

**taxonomy\_path** `string`

The category path of the audience, for example `Food > Snacks`.

**description** `string`

The audience description.

**geo** `string`

The geo of the audience, for example `US`.

**size** `integer`

The audience size.

**cpm** `number`

The audience CPM.

**400 Bad Request**

Returned if `search` is missing.

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "search parameter is required.",
    "details": {},
    "request_id": "..."
  }
}
```

Returned if `min_size`, `max_size`, `min_cpm` or `max_cpm` is not a number.

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Size and CPM params must be numbers.",
    "details": {},
    "request_id": "..."
  }
}
```

Returned if `limit` is not an integer.

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "limit param must be a number.",
    "details": {},
    "request_id": "..."
  }
}
```

**401 Unauthorized**

Returned if the `X-Api-Key` header is missing or invalid.

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "details": {
      "field": "X-Api-Key",
      "issue": "invalid"
    },
    "request_id": "..."
  }
}
```

**500 Internal Server Error**

Returned if there is an unexpected error on the server while searching audiences.

```json theme={null}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to search audiences",
    "details": {},
    "request_id": "..."
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.