Refresh Audience
refresh_audienceRefresh one named member segment of an audience against the current IAG, then refresh the audience's own version/expiry. An audience is a composition of one or more member segments, possibly of different subtypes — there is no "primary" segment, so segment_id is required (400 SEGMENT_ID_REQUIRED if omitted, 400 SEGMENT_NOT_A_MEMBER if it is not part of this audience). Behaviour is specific to the chosen segment's subtype:
filter: synchronous — returns status: active immediately. record_count is null; call recount_audience if a fresh count is needed before quoting.
matched: with hitl false/unset (default): returns status: pending + upload_url. Instruct the user to upload their identity list to upload_url (same or updated file). After upload, call wait_for_segment(segment_id) to block until identity resolution completes. With hitl: true: the upload is staged instead — follow the analyze_audience_upload -> confirm_column_mappings / cancel_matched_upload -> wait_for_segment sequence documented on create_segment(subtype=matched) (confirm_column_mappings/cancel_matched_upload take this segment_id, not audience_id).
custom: immutable snapshot; returns 409 CUSTOM_REGENERATION_REQUIRED. Request a new internal data-team publication. Always call get_audience first to see the member segments and their subtypes, so you can pick (or have the user pick) the right segment_id. Async build completion or failure may notify configured external webhooks and opted-in users by email. Requires 'creator' scope.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"audience_id": "<audience_id>",
"segment_id": "<segment_id>"
},
"name": "refresh_audience"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hitl | No | If true: stages a matched segment's re-upload instead of resolving automatically. Defaults to false. | |
| segment_id | Yes | Which member segment of this audience to refresh. Required — there is no default/primary segment. | |
| audience_id | Yes | The audience ID to refresh | |
| compression | No | Matched subtype: replacement upload compression. | none |
| shard_count | No | Matched subtype: number of same-format shards. Every CSV shard must include its own header row. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| subtype | Yes | ||
| version | Yes | ||
| guidance | No | Interpretation or recovery guidance for this result | |
| next_step | Yes | ||
| refreshed | Yes | ||
| count_unit | No | ||
| page_count | No | Number of objects on this page, not the organization total | |
| segment_id | Yes | ||
| upload_url | No | ||
| audience_id | Yes | ||
| count_state | No | Unknown means no count; available does not guarantee freshness. Recount for a current value. | |
| upload_urls | No | ||
| next_actions | No | Suggested next calls using returned IDs and available scopes. Not executed and not user consent. | |
| workflow_run_id | No | ||
| population_input | No | Population input used for the preview; IDs refer to their current saved definitions |