> For the complete documentation index, see [llms.txt](https://docs.helix.voodoo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helix.voodoo.io/user-acquisition/audience-management.md).

# Audience Management

Create and manage device ID audiences, then use them to target your user acquisition campaigns.

Audiences let you define a list of users, identified by their device IDs, and include or exclude them in your user acquisition campaigns. For example, you can retarget lapsed players from a list built in your MMP, or exclude your existing users with a suppression list.

All your audiences are created and managed from the **Audiences** page, without any help from the Helix team. Once an audience is created, you can link it to your campaigns from the **Targeting** section. See [Create Campaigns](https://docs.helix.voodoo.io/user-acquisition/create-campaigns.md#audience).

## View your audiences

From the left menu, navigate to **User Acquisition → Audiences**.

The list shows the following information for each audience:

| Column           | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| **Name**         | The audience name. The icon next to it shows its status.      |
| **Type**         | The identifier type used by the audience, such as Device IDs. |
| **Source**       | Where the list comes from, such as an API URL or a CSV file.  |
| **Size**         | The number of IDs in the audience.                            |
| **Refresh mode** | Whether the list is fetched once or refreshed daily.          |
| **Last Updated** | The last time the audience was updated.                       |

Use the **Name** search field to find an audience, or click **Add filter** to narrow down the list.

Click the **three-dot menu** at the end of a row to **Edit** the audience or view its **History**.

### Audience status

| Status         | Description                                                    |
| -------------- | -------------------------------------------------------------- |
| **Processing** | The audience was just created and its IDs are being processed. |
| **Active**     | The audience is fully processed and available for delivery.    |
| **Failed**     | An error occurred while processing the audience.               |

## Create an audience

{% stepper %}
{% step %}
**Start a new audience**

On the **Audiences** page, click **New audience** in the top-right corner.
{% endstep %}

{% step %}
**Name your audience**

In the **General** section, enter a clear and descriptive **Name**. This is the name you'll search for when you add the audience to a campaign.
{% endstep %}

{% step %}
**Select the type**

Select **Device IDs** to target users by their device identifiers (IDFA on iOS, GAID on Android).
{% endstep %}

{% step %}
**Select the source**

In the **Source** section, choose how Helix receives the list of IDs:

* **From URL**: Helix fetches the IDs from an API URL. See [From URL](#from-url).
* **Upload CSV**: You upload a CSV file of IDs. See [Upload CSV](#upload-csv).
  {% endstep %}

{% step %}
**Save the audience**

Click **Save**. Your audience is added to the list with the **Processing** status. Processing starts right away and can take up to 2 hours. The status changes to **Active** once the audience is ready for delivery.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
Once an audience is created, only its name can be changed. Choose the type and source carefully.
{% endhint %}

{% hint style="info" %}
**CSV format**\
Both sources use the same CSV format: one device ID per line. A header line at the top is optional.
{% endhint %}

### From URL

Use this source when your list is hosted by an external service, such as the audience builder of your MMP. The URL must return a CSV of device IDs.

* **Source URL**: Enter the URL Helix should download the IDs from, for example an Adjust Audience Builder URL.
* **Refresh**: Choose how often Helix downloads the list:
  * **No refresh**: The list is downloaded once, when the audience is created. Use it for a fixed list.
  * **Daily refresh**: The list is downloaded again every day, as long as at least one active campaign uses the audience. Use it when your target list changes daily.

### Upload CSV

Use this source when you already have your list of IDs as a file.

Click **Upload a CSV file** and select a CSV file of device IDs. Files can be up to **500 MB**.

A CSV audience is a fixed list. To update it, create a new audience with the new file.

## View audience details

Click an audience name in the list to open its details panel.

The panel shows the audience status, size, type, source, refresh mode, and creation and last updated dates. You can copy the **Source URL** and the **Audience ID** using the copy icons.

## Rename an audience

Once an audience is created, only its name can be changed. To use a different type or source, create a new audience.

{% stepper %}
{% step %}
**Open the audience**

In the audience list, click the **three-dot menu** next to the audience and select **Edit**. You can also click the audience name, then click **Edit** at the bottom of the details panel.
{% endstep %}

{% step %}
**Update the name**

Enter the new **Name** for the audience.
{% endstep %}

{% step %}
**Save your changes**

Click **Save**.
{% endstep %}
{% endstepper %}

## View audience history

The audience history lists the changes made to an audience over time.

In the audience list, click the **three-dot menu** next to the audience and select **History**.

For each entry, the panel shows:

* **Date**: When the change happened.
* **Operation**: The type of change, such as **Update**.
* **User**: The ID of the user or service that made the change.

## Target audiences in a campaign

You can link any number of audiences to a campaign, and choose for each one whether to include or exclude it:

* **Include**: The campaign delivers only to users in the audience.
* **Exclude**: The campaign doesn't deliver to users in the audience, for example a suppression list of your existing users.

You can mix included and excluded audiences in the same campaign.

{% stepper %}
{% step %}
**Open the campaign**

Go to **User Acquisition → Campaigns** and create a new campaign or edit an existing one.
{% endstep %}

{% step %}
**Select the audiences**

In the **Targeting** section, open the audience field and search for your audience by name. Select it from the list, then choose whether to include or exclude it. Repeat for each audience you want to link.
{% endstep %}

{% step %}
**Save the campaign**

Click **Save**.
{% endstep %}
{% endstepper %}

For the other campaign settings, see [Create Campaigns](https://docs.helix.voodoo.io/user-acquisition/create-campaigns.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.helix.voodoo.io/user-acquisition/audience-management.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
