Segments

Duplicate a segment with lineage tracking

Creates a new segment pre-populated from the source segment. Core and subtype-specific attributes are carried; underlying computed data (match results, lookalike/propensity scores) is referenced, never recomputed. Records parent_segment_id, derived_from (root ancestor — propagates through duplicate-of-duplicate chains), and parent_segment_version for lineage. The duplicate gets fresh created_at/updated_at and a fresh 90-day expires_at. No audience wrapper is created.

Per-subtype behavior:

filter — status active, record_count reset to null (recount via POST /v1/segments/{id}/count), version history restarts at current_version: 1. A filter segment's record_limit is copied; the duplicate's seeded selection differs from the source's.
matched — record_count and match_count carried. The duplicate references the source's stored match results, so it stays deliverable without re-running the match. Sources with expired/failed status or incomplete match data are rejected with 409 SOURCE_MATCH_UNAVAILABLE.
similarity/propensity — seed/model references and record_count carried; the duplicate points at the same generated scores.

Pending or failed sources are rejected with 409 SOURCE_NOT_READY. Requires 'creator' scope.

post/v1/segments/{id}/duplicate

Request

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

Path parameters

idstring required

Source segment document ID.

Request body

namestring

Display name for the duplicate. Defaults to "<source name> (copy)".

Response

Duplicated segment created.

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

Changes

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