Update audience

put

https://api.delivr.ai/api/v1/audiences/{id}

Update audience name, description, filter, output path, or select clause. On a pixel audience you can also change any source_pixel_* setting; send only the fields you want to change. A change that alters the definition rebuilds the audience. Sending a source_pixel_* field to an audience of another type returns 400.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

integer

required

Audience ID.

Query Params

project_id

uuid

Project ID (UUID). Every audience operation except GET /api/v1/audiences/schema is scoped to a project: send this parameter or the X-Project-Id header. Without either the request returns 400 with project_id is required.

Body Params

audience_name

string

Updated audience name.

audience_description

string

Updated description.

filter

object

A group of filter rules joined by a logical operator. Groups can be nested to create complex expressions (e.g., AND of ORs).

The values in in, not in, include and exclude rules count together across the whole filter, and a filter holds at most 50,000 of them. Past that, create, update and estimate return 400. For larger value sets, upload a list and filter on it instead of passing the values inline.

sql_filter_statement

object

Updated SQL filter statement.

tier

string

enum

Defaults to intent

Intents audiences only. intent (the default) delivers intent records without trend columns and bills as Intent Signals. predictive_signals adds intent_trend and active_days_14d to every record and bills as Predictive Signals, twice the Intent Signals rate. Trend columns are included automatically at predictive_signals. Naming a trend column in select at intent returns 400 (intent_trend is a Predictive Signals field. Set tier to predictive_signals to include trends (billed as Predictive Signals).), and predictive_signals on a non-intents audience returns 400. Filtering on trend fields is allowed at either tier. Changing the tier rebuilds the audience.

Allowed:

select

string

Updated column projection clause.

source_pixel_ids

array of strings

length between 1 and 20

Replacement list of pixel IDs. Each must be a pixel in this project; an ID from another project, or one that does not exist, returns 400 with code pixel_not_in_project.

source_pixel_ids

source_pixel_window_days

integer

1 to 90

Defaults to 30

Lookback window in days (UTC), counted back from today. pixel audiences only.

source_pixel_include_urls

array of strings

length ≤ 20

Page patterns. A person qualifies only if they viewed at least one page whose URL contains at least one of these strings. Matching is a case-insensitive substring match on the full page URL, so /pricing matches https://example.com/Pricing?plan=pro. Empty or omitted means any page counts. pixel audiences only.

source_pixel_include_urls

source_pixel_exclude_urls

array of strings

length ≤ 20

Page patterns. A person is dropped if they viewed any page whose URL contains any of these strings, even if they also match source_pixel_include_urls. Same matching as source_pixel_include_urls. pixel audiences only.

source_pixel_exclude_urls

source_pixel_min_visit_days

integer

1 to 90

Defaults to 1

Minimum number of distinct days a person was seen. Cannot exceed source_pixel_window_days. pixel audiences only.

source_pixel_output

string

enum

Defaults to all

all returns everyone who qualifies. new returns only people who were not in the previous completed build, so each refresh yields just the people who newly qualified. The first build has no earlier build to compare with and returns everyone who qualifies. pixel audiences only.

Allowed:

output_path

string

Updated output path.

renew_frequency

string

enum

Update the refresh schedule.

daily: refreshes every day at 09:00 UTC.
weekly: refreshes every Saturday at 18:00 UTC.
manual: stops automatic refresh; manual /refresh calls still work.

Allowed:

record_limit

integer

0 to 10000000

Cap the audience at this many records, from 0 to 10,000,000; 0 removes the cap. Supported on intents, contact and list audiences. With a cap set, downloads and exports bill at most this many records. Changing it rebuilds the audience.

intent_window_days

integer

1 to 14

Updated lookback window (1-14). Changing this triggers reprocessing. Only for intents audiences.

Rejected when the audience is pinned to a fixed date range, because the pinned range takes precedence and the new window would have no effect.

row_grain

string

enum

Updated row grain. Only for intents audiences. Changing the grain in effect triggers reprocessing, since it changes the shape of every output row.

Setting it to the grain the audience already builds at, including one that was previously derived from the window, is accepted and persists the choice without forcing a rebuild.

Allowed:

Headers

X-Project-Id

uuid

Project ID (UUID). Equivalent to the project_id query parameter; send one or the other.

Responses

400

Invalid request body, or a filter with more than 50,000 inline values (filter contains N inline values (max 50000); use file-based filters for large lists).

401

Missing or invalid authentication.

403

Forbidden. Also returned when a filter or select uses a partner data field from a dataset that is not enabled for the project.

404

Audience not found.

200Updated audience.

409partner_price_not_accepted: a partner data field's dataset has no accepted price. partners lists the datasets to accept.

413The request body is larger than the 8 MiB (8,388,608 byte) limit. For large value lists, upload a list and filter on it instead of sending the values inline.