Refresh a member segment and this audience's composed metadata
const url = 'https://dev-api.infiniteaudience.ai/v1/audiences/example/refresh';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"segment_id":"example","hitl":false,"shard_count":1,"compression":"none"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://dev-api.infiniteaudience.ai/v1/audiences/example/refresh \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "segment_id": "example", "hitl": false, "shard_count": 1, "compression": "none" }'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 ‘purchase’ scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Audience document ID.
Request Bodyrequired
Section titled “Request Bodyrequired”object
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.
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).
(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.
(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.
Responses
Section titled “Responses”Audience refreshed. Inspect status to determine next steps. See next_step for a machine-readable hint.
Response of POST /v1/audiences/{id}/refresh. Deliberately lighter than the full Audience object: the handler returns only the version/lifecycle attributes it changed plus subtype-specific next-step hints. Fetch GET /v1/audiences/{id} for the full audience document.
object
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.
New snapshot version after the refresh.
New 90-day hard expiry.
Active = the refreshed segment’s subtype is filter, refreshed synchronously; pending = matched/similarity/propensity, awaiting re-upload or workflow completion.
Subtype of the refreshed segment.
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.
Human-readable hint for the calling agent on how to proceed (e.g. recount, upload to upload_url, or wait for the workflow).
Presigned GCS 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.
Presigned GCS 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 for this matched refresh upload.
Expiry for upload_url/upload_urls. Present only for the matched subtype.
Cloud Workflow execution ID. Present only for similarity and propensity subtypes.
Example
{ "audience_id": "aud_xyz123", "segment_id": "seg_abc123", "version": 2, "version_created_at": "2026-06-30T14:00:00Z", "expires_at": "2026-09-28T14:00:00Z", "status": "active", "subtype": "filter", "refreshed": true, "next_step": "Call recount_audience to refresh the record count before quoting or delivering."}SEGMENT_ID_REQUIRED — segment_id was omitted from the request body. SEGMENT_NOT_A_MEMBER — the given segment_id is not a member of this audience. UNKNOWN_SUBTYPE — the segment has an unrecognized subtype and cannot be refreshed. UNSUPPORTED_INPUT_COMPRESSION — compression=gzip was requested for an avro-format matched member segment.
object
Example
{ "error": "Bad Request", "code": "SEGMENT_ID_REQUIRED", "message": "segment_id is required — choose which member segment to refresh. GET /v1/audiences/:id to list this audience's segments."}Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "Unauthorized: Missing or invalid Authorization header"}{ "error": "Unauthorized", "code": "TOKEN_EXPIRED", "message": "Your session has expired. Please sign in again."}Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).
object
Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.
Human-readable explanation of the error.
Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.
Opaque support/debug identifier when available.
Examples
{ "error": "SCOPE_REQUIRED", "message": "This endpoint requires the purchase scope."}The audience does not exist (simple-tier body, no code), or the given segment_id does not resolve to any segment document (SEGMENT_NOT_FOUND) despite having passed the membership check (e.g. deleted concurrently).
object
“Audience not found”
object
Example
{ "code": "SEGMENT_NOT_FOUND"}The named segment cannot be refreshed. SEGMENT_ARCHIVED — the segment is archived; restore it first (PATCH status: active via PATCH /v1/segments/{id}). SHARED_SOURCE_DATA — matched duplicate that references another segment’s match data; refreshing it here would overwrite the source segment’s upload. The message names the source segment id to refresh instead.
object
Example
{ "code": "SEGMENT_ARCHIVED"}MISSING_POSITIVE_CLASS_ID — (propensity only) the segment predates positive_class_segment_id storage and cannot be auto-refreshed; delete and recreate it.
object
Example
{ "code": "MISSING_POSITIVE_CLASS_ID"}WORKFLOW_LAUNCH_FAILED — the similarity/propensity re-launch workflow call failed; retry. Presigned-URL generation failures for the matched subtype return a simple-tier body with no code.
object
object
“Failed to generate presigned upload URL”
Example
{ "code": "WORKFLOW_LAUNCH_FAILED"}