Segments

Get a segment by ID

Returns the full segment document including subtype-specific attributes, current record count, and lifecycle status. Also includes a usage object with audience_count and campaign_count showing how many audiences and campaigns currently reference this segment. Reading the segment emits no billable usage. Requires 'discovery' scope.

get/v1/segments/{id}

Request

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

Path parameters

idstring required

Response

Segment document.

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.