Audiences

Refresh a member segment and this audience's composed metadata

Re-derives one member segment of this audience from the latest identity graph data, then bumps only this audience's own composed metadata (snapshot_version/expires_at/status; record_count is cleared and must be re-requested via POST /v1/audiences/{id}/count). An audience is a composition of N member segments (possibly mixed subtypes) — there is no "primary" segment. You must name exactly which member segment to refresh via the required segment_id body field (list an audience's segments via GET /v1/audiences/{id}). That segment's refresh delegates entirely to the same implementation POST /v1/segments/{id}/refresh uses, so behavior for the named segment is identical either way. This route never touches any OTHER segment in the composition, and — since segment refresh is deliberately non-cascading — never touches any OTHER audience that happens to reference the same segment. Behavior is driven by the refreshed segment's subtype:

filter — Synchronous refresh. The audience is immediately returned as status: active with an incremented version number and a new 90-day expires_at. The record_count is cleared and must be re-requested via POST /v1/audiences/{id}/count.

matched — Returns a fresh presigned upload_url (24 h expiry) — or upload_urls (an array, one per shard) when shard_count > 1, in which case upload_url is absent. The new upload may be raw or gzip. With hitl unset/false (default): returns status: pending immediately and the URL(s) target the canonical upload path — re-upload your identity list and identity resolution runs automatically once every declared shard has been uploaded. With hitl: true: the segment's status is left untouched and the URL(s) instead target a staging location — call POST /v1/match/{segment_id}/analyze to preview column mappings, then POST /v1/audiences/{id}/mappings to confirm (starts resolution) or POST /v1/audiences/{id}/mappings/cancel to abort.

similarity/propensity — Re-launches the generation workflow. Returns status: pending plus a workflow_run_id; poll GET /v1/workflows/{workflow_run_id} until completion.

Important: Delivery requests are rejected with 422 while constituent segments are still being processed.

To refresh a single segment without touching its audience wrappers, use POST /v1/segments/{id}/refresh — it updates only that segment and returns affected_audiences for follow-up. Requires 'creator' scope.

post/v1/audiences/{id}/refresh

Request

  • Base URL: https://api.infiniteaudience.ai
  • URL: https://api.infiniteaudience.ai/v1/audiences/{id}/refresh
  • Auth: HTTP bearer

Path parameters

idstring required

Audience document ID.

Request body

segment_idstring required

Required. ID of the member segment (within this audience's composition) to refresh. Rejected with 400 SEGMENT_ID_REQUIRED if omitted, or 400 SEGMENT_NOT_A_MEMBER if the segment is not a member of this audience. GET /v1/audiences/{id} to list this audience's segments.

hitlboolean

Requires an explicit confirmation step before the automated pipeline proceeds. (similarity / propensity) the refresh workflow pauses at a human-in-the-loop review gate — use POST /v1/workflows/{workflow_run_id}/resume with gate_id and response to submit answers and resume. (matched) the re-upload is staged instead of landing at the path that triggers automatic identity resolution — see the matched bullet above. Ignored for filter. Default: false (fully automated).

shard_countinteger

(matched only) Set > 1 for same-format shards. Every CSV shard must include the same header, and all shards must share schema and compression. Returns upload_urls instead of upload_url.

compression'none' | 'gzip'

(matched only) Compression for this new upload. It does not inherit the previous upload. Send raw gzip bytes without Content-Encoding. gzip is not supported for avro-format segments — rejected with 400 UNSUPPORTED_INPUT_COMPRESSION.

Response

Audience refreshed. Inspect status to determine next steps. See next_step for a machine-readable hint.

audience_idstring required
segment_idstring required

The caller-chosen member segment that was refreshed (echoed back from the request body). An audience is a composition of N member segments with no primary one — this is always present, identifying which member segment's refresh drove this response.

versioninteger required

New snapshot version after the refresh.

version_created_atstring date-time required
expires_atstring date-time required

New 90-day hard expiry.

status'active' | 'pending' required

active = the refreshed segment's subtype is filter, refreshed synchronously; pending = matched/similarity/propensity, awaiting re-upload or workflow completion.

subtype'filter' | 'matched' | 'similarity' | 'propensity' required

Subtype of the refreshed segment.

refreshedboolean required

true when the refreshed segment was re-derived; false only for the filter-subtype no-op path (segment already active, count already null, TTL already fresh) — this route always calls refreshSegmentCore without force, so that no-op path is reachable here exactly as it is on POST /v1/segments/{id}/refresh.

next_stepstring required

Human-readable hint for the calling agent on how to proceed (e.g. recount, upload to upload_url, or wait for the workflow).

upload_urlstring

Presigned upload URL (24 h expiry). Present only for the matched subtype, when shard_count was 1 (the default) — absent when sharded, use upload_urls instead.

upload_urlsstring[]

Presigned upload URLs (24 h expiry), one per shard, index-ordered. Present only for the matched subtype when shard_count > 1 was requested — upload_url is absent. Every CSV shard must include the same header row.

compression'none' | 'gzip'

Compression for this matched refresh upload.

upload_expires_atstring date-time

Expiry for upload_url/upload_urls. Present only for the matched subtype.

workflow_run_idstring

Cloud Workflow execution ID. Present only for similarity and propensity subtypes.

Changes

No recorded changes to this operation across all 1 revision of this API.