Refresh a segment against the latest data
const url = 'https://dev-api.infiniteaudience.ai/v1/segments/example/refresh';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"hitl":false,"force":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/segments/example/refresh \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "hitl": false, "force": false, "shard_count": 1, "compression": "none" }'Re-derives a single segment from the latest identity graph data. This is the segment-native counterpart of POST /v1/audiences/{id}/refresh — it updates ONLY this segment. Referencing audiences are never touched; their IDs are returned in affected_audiences so you can recount or refresh them as needed (use the audience-level refresh for a whole-composition refresh).
Per-subtype behavior:
-
filter — Synchronous. Bumps
current_versionand appends a version history entry (sharing the same counter as PATCH filter edits), clearsrecord_count, resets the 90-day TTL, and returnsstatus: active. If nothing would change (already active, count already null, TTL already fresh today) andforceis not set, the call is a no-op returning the current segment withrefreshed: false. -
matched — Returns a fresh presigned
upload_url(24 h expiry) — orupload_urls(an array, one per shard) whenshard_count> 1, in which caseupload_urlis absent. The new upload may be raw or gzip. Withhitlunset/false (default): targets the segment’s existing upload path directly, resets mapping state (column_mappings,mapping_confirmed) and counts, and returnsstatus: pending— re-upload your identity list and identity resolution runs automatically once every declared shard has been uploaded. Withhitl: true: the URL(s) instead target a staging location and the segment’s status/mapping state is left untouched until you confirm — see thehitlfield description below. Matched duplicates that reference another segment’s data (source_data_segment_idset) are rejected with 409 SHARED_SOURCE_DATA — refresh the source segment instead. -
similarity — Re-launches the lookalike generation workflow with the stored seed parameters. Returns
status: pending; the segment’sworkflow_run_idis updated to the new run. PollGET /v1/workflows/{workflow_run_id}until completion. -
propensity — Re-launches the scoring model workflow using the stored
positive_class_segment_id. Returnsstatus: pendingplus the newworkflow_run_id. 422 MISSING_POSITIVE_CLASS_ID for legacy segments that predatepositive_class_segment_idstorage — those must be recreated.
Archived segments are rejected with 409 SEGMENT_ARCHIVED — restore first via PATCH /v1/segments/{id} with status: active.
Requires ‘purchase’ scope.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Segment document ID.
Request Body
Section titled “Request Body”object
Requires an explicit confirmation step before the automated pipeline proceeds. (similarity / propensity) the re-launched workflow pauses at a human-in-the-loop review gate — use POST /v1/workflows/{workflow_run_id}/resume to submit answers and resume. (matched) the re-upload is staged instead of landing at the path that triggers automatic identity resolution — call POST /v1/match/{id}/analyze to preview column mappings against the staged file, then POST /v1/segments/{id}/mappings to confirm (moves the file into place and starts resolution) or POST /v1/segments/{id}/mappings/cancel to abort (the segment is left completely untouched). Ignored for filter.
(filter only) Bump the version and invalidate the count even when the segment already looks fresh (skips the no-op short-circuit).
(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’s setting. 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”Segment refreshed (or no-op — inspect refreshed). Shape varies by subtype: matched adds upload_url/upload_expires_at (or upload_urls when shard_count > 1); similarity/propensity carry the new workflow_run_id. See next_step for a machine-readable hint.
Response of POST /v1/segments/{id}/refresh — the full updated segment document plus refresh metadata. For the matched subtype the response additionally carries upload_url / upload_expires_at (24 h presign) — or upload_urls (an array, one per shard) when shard_count > 1 was requested, in which case upload_url is absent; for similarity/propensity the segment’s workflow_run_id points at the newly launched run.
object
Unique segment identifier
Display name of the segment
Segment subtype. Determines which additional attributes are present. filter = saved filter criteria; matched = customer list upload with identity resolution; similarity = lookalike model; propensity = ML scoring model.
Pending = computation in progress (matched/similarity/propensity during creation); active = fully ready; failed = workflow or enrichment error (see error_message); archived = hidden from the default segment catalog and new audience compositions, but otherwise fully functional — audiences that already reference an archived segment are unaffected, and it can be restored with PATCH status:active at any time. Distinct from DELETE, which is not reversible and does change referencing audiences’ composition; expired = past 90-day TTL.
Total matched/qualified records. Null while pending or if count has not been run.
Date-only ISO string (90-day hard expiry from creation) for a persistent segment; a full ISO datetime (short, hour-granular TTL) while ephemeral is true.
True for a scratch/free/auto-expiring filter-subtype segment. Absent/false reads as persistent. Promote to persistent via PATCH /v1/segments/{id} {ephemeral: false}, or implicitly by composing it into an audience.
ISO datetime the segment was promoted from ephemeral to persistent. Absent until promotion happens.
How the segment was promoted to persistent — explicit_save (a direct ephemeral: false PATCH) or composition (referenced by an audience create/update). Absent until promotion happens.
Org (default) — visible to all members of the org. private — visible only to the creating user.
Filter subtype only. Current version counter.
Filter subtype only. Legacy flat filter array.
A single filter condition for audience discovery or job execution
Filter subtype only. Grouped filter conditions.
A group of Filter conditions. All filters within a single group are always ANDed together — there is no per-group intra-operator. The combinator attribute is an inter-group operator: it controls how this group is joined to the immediately preceding group in the array. The combinator on the first group (index 0) is always ignored.
Example — (city = "NYC" AND state = "NY") OR (state = "CA"):
{ "id": "g1", "filters": [{"field":"city","op":"=","value":"NYC"},
{"field":"state","op":"=","value":"NY"}],
"combinator": "AND" },
{ "id": "g2", "filters": [{"field":"state","op":"=","value":"CA"}],
"combinator": "OR" }
] ```
Group g1's `combinator` is irrelevant (it is the first group). Group g2's `combinator: "OR"` means the result is `(g1) OR (g2)`.object
Stable identifier (UUID or NanoID). Used to track groups across edits.
One or more filter conditions. All conditions in this array are combined with AND. Provide at least one filter per group.
A single filter condition for audience discovery or job execution
Inter-group operator. Joins this group to the previous group in the array. AND narrows the result; OR broadens it. Ignored on the first group (index 0) — that group has no predecessor to join.
Matched subtype only. Input file format.
Matched subtype only. Input artifact compression, normalized to none by current handlers.
Matched subtype only. Number of same-format input objects, normalized to 1 for unsharded uploads.
Matched subtype only. Source column name → standard identity attribute mappings. Populated after the analyze-and-store workflow gate runs.
Matched subtype only. True once column mappings have been confirmed.
Matched subtype only. Number of rows in the original upload.
Matched subtype only. Rows that resolved to a known identity after enrichment.
Matched subtype only. match_count / input_record_count.
Matched subtype only. 30-min presigned GCS PUT URL. Present on create and refresh responses only, when shard_count was 1 (the default) — absent when sharded, use upload_urls instead.
Matched subtype only. N presigned GCS PUT URLs (index-ordered). Present on create and refresh responses only when shard_count > 1 was requested — upload_url is absent. Every CSV shard must include the same header row.
Matched subtype only. Expiry of upload_url/upload_urls.
Present when status is failed. Describes the reason for failure.
Matched duplicates only. ID of the segment that owns the underlying match-result data (the root data owner). Set when the segment was created via POST /v1/segments/{id}/duplicate; propagates unchanged through duplicate-of-duplicate chains. Null on segments that own their own data.
Similarity subtype only. Natural language ICP persona description used as seed.
Similarity subtype only. ID of an existing segment used as the lookalike seed.
Similarity/propensity subtype. References the lookalike run or propensity model ID.
Similarity and propensity subtypes. The workflow run ID. Poll GET /v1/workflows/{workflow_run_id} to monitor progress.
Propensity subtype only. ID of the segment whose members are the positive training class.
ID of the segment this was duplicated or derived from, if applicable.
Root ancestor segment ID. Stable across duplicate-of-duplicate chains — always points at the original segment, never an intermediate duplicate.
Version of the parent segment pinned at duplicate time (current_version for filter parents; snapshot_version otherwise). Null on segments that are not duplicates.
ID of the campaign whose chat session first produced this segment. Metadata only — does not restrict the segment to that campaign. Present only when the segment was created via POST /v1/segments with a campaign_id.
Cross-campaign usage stats. Only present on GET /v1/segments/{id} — not included on list responses. Useful for understanding impact before archiving.
object
Number of active audiences that reference this segment.
Number of distinct campaigns those audiences belong to.
True when the segment was re-derived; false when the filter no-op path returned the current object unchanged (already active, count already null, TTL already fresh — pass force: true to bump anyway).
IDs of non-deleted audiences that reference this segment. They are NOT auto-refreshed — their status, record_count, and expiry may now be stale. Recount or refresh them as needed, or use POST /v1/audiences/{id}/refresh for a whole-composition refresh.
Human-readable hint for the calling agent on how to proceed (recount, upload to upload_url, or wait for the workflow).
Example
{ "segment_id": "seg_abc123", "name": "West Coast Adults 25-44", "subtype": "filter", "status": "active", "record_count": null, "expires_at": "2026-10-03", "ephemeral": false, "visibility": "org", "current_version": 4, "filters": [], "filter_groups": [ { "id": "g1", "filters": [ { "field": "state", "op": "IN", "value": [ "CA", "OR", "WA" ] } ], "combinator": "AND" } ], "created_at": "2026-04-01T12:00:00Z", "updated_at": "2026-07-05T18:00:00Z", "refreshed": true, "affected_audiences": [ "aud_123", "aud_456" ], "next_step": "Call POST /v1/segments/{id}/count (recount) to refresh the record count. Referencing audiences are NOT auto-refreshed — recount or refresh the audiences listed in affected_audiences as needed."}Invalid request — malformed body, missing required attribute, or failed validation. See error and message for details.
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": "Bad Request", "code": "MISSING_SEGMENTS", "message": "segment_ids is required for filter audiences."}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."}Resource not found or not accessible to the calling org.
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": "Audience not found"}The segment cannot be refreshed. SEGMENT_ARCHIVED — the segment is archived; restore it first (PATCH status: active). 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
{ "error": "Conflict", "code": "SHARED_SOURCE_DATA", "message": "This matched segment is a duplicate that references segment 'seg_root1' for its match data — refreshing it here would overwrite that source segment's upload. Refresh the source segment instead: POST /v1/segments/seg_root1/refresh."}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"}