Segments

Refresh a segment against the latest data

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_version and appends a version history entry (sharing the same counter as PATCH filter edits), clears record_count, resets the 90-day TTL, and returns status: active. If nothing would change (already active, count already null, TTL already fresh today) and force is not set, the call is a no-op returning the current segment with refreshed: false.

  • 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): targets the segment's existing upload path directly, resets mapping state (column_mappings, mapping_confirmed) and counts, and returns status: pending — re-upload your identity list and identity resolution runs automatically once every declared shard has been uploaded. With hitl: true: the URL(s) instead target a staging location and the segment's status/mapping state is left untouched until you confirm — see the hitl field description below. Matched duplicates that share another segment's data are rejected with 409 SHARED_SOURCE_DATA — refresh the source segment instead. A saved integration-match segment owns its own lifecycle and remains refreshable.

  • similarity — Re-launches the lookalike generation workflow with the stored seed parameters. Returns status: pending; the segment's workflow_run_id is updated to the new run. Poll GET /v1/workflows/{workflow_run_id} until completion.

  • propensity — Re-launches the scoring model workflow using the stored positive_class_segment_id. Returns status: pending plus the new workflow_run_id. 422 MISSING_POSITIVE_CLASS_ID for legacy segments that predate positive_class_segment_id storage — those must be recreated.

Archived segments are rejected with 409 SEGMENT_ARCHIVED — restore first via PATCH /v1/segments/{id} with status: active. Requires 'creator' scope.

post/v1/segments/{id}/refresh

Request

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

Path parameters

idstring required

Segment document ID.

Request body

hitlboolean

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.

forceboolean

(filter only) Bump the version and invalidate the count even when the segment already looks fresh (skips the no-op short-circuit).

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's setting. Send raw gzip bytes without Content-Encoding. gzip is not supported for avro-format segments — rejected with 400 UNSUPPORTED_INPUT_COMPRESSION.

Response

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.

segment_idstring required

Unique segment identifier

namestring required

Display name of the segment

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

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.

status'pending' | 'active' | 'failed' | 'archived' | 'expired' required

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.

record_countinteger nullable required

Total matched/qualified records. Null while pending or if count has not been run.

expires_atstring required

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.

visibility'org' | 'private'

org (default) — visible to all members of the org. private — visible only to the creating user.

current_versioninteger nullable

filter subtype only. Current version counter.

record_limitinteger nullable

filter subtype only — membership cap; null when uncapped (see POST /v1/segments)

file_format'csv' | 'avro' | 'json' | 'jsonl' nullable

matched subtype only. Input file format.

compression'none' | 'gzip' | 'null' nullable

matched subtype only. Input artifact compression, normalized to none by current handlers.

shard_countinteger nullable

matched subtype only. Number of same-format input objects, normalized to 1 for unsharded uploads.

column_mappingsobject nullable

matched subtype only. Source column name → standard identity attribute mappings. Populated after the analyze-and-store workflow gate runs.

mapping_confirmedboolean nullable

matched subtype only. True once column mappings have been confirmed.

input_record_countinteger nullable

matched subtype only. Number of rows in the original upload.

match_countinteger nullable

matched subtype only. Rows that resolved to a known identity after enrichment.

match_ratenumber nullable

matched subtype only. match_count / input_record_count.

upload_urlstring nullable

matched subtype only. 30-minute signed upload URL. Present on create and refresh responses only, when shard_count was 1 (the default) — absent when sharded, use upload_urls instead.

upload_urlsstring[] nullable

matched subtype only. N signed upload 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.

upload_expires_atstring date-time nullable

matched subtype only. Expiry of upload_url/upload_urls.

error_messagestring nullable

Present when status is failed. Describes the reason for failure.

source_data_segment_idstring nullable

matched subtype only. Opaque, read-only reference to stored match results when they are shared or versioned independently from the segment metadata. Null when no separate result reference is needed.

seed_descriptionstring nullable

similarity subtype only. Natural language ICP persona description used as seed.

seed_segment_idstring nullable

similarity subtype only. ID of an existing segment used as the lookalike seed.

workflow_run_idstring nullable

similarity and propensity subtypes. The workflow run ID. Poll GET /v1/workflows/{workflow_run_id} to monitor progress.

positive_class_segment_idstring nullable

propensity subtype only. ID of the segment whose members are the positive training class.

parent_segment_idstring nullable

ID of the segment this was duplicated or derived from, if applicable.

derived_fromstring nullable

Root ancestor segment ID. Stable across duplicate-of-duplicate chains — always points at the original segment, never an intermediate duplicate.

parent_segment_versioninteger nullable

Version of the parent segment pinned at duplicate time (current_version for filter parents; snapshot_version otherwise). Null on segments that are not duplicates.

origin_campaign_idstring nullable

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.

created_atstring date-time required
updated_atstring date-time required
refreshedboolean required

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).

affected_audiencesstring[] required

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.

next_stepstring required

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

Changes

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