Segments

Partially update a segment

Applies a partial update to a segment. Only provided attributes are updated.

Allowed updates by subtype:

  • filter — name, filters, filter_groups, record_limit, status (archived/active), ephemeral
  • matched — name, column_mappings, status (archived/active), ephemeral promotion
  • similarity / propensity — name, status (archived/active)

Standalone promotion: ephemeral: false promotes a scratch (ephemeral) segment to persistent in-place — resets its expiry to the standard 90-day TTL and reactivates it if it had lazily expired. Only false is honored; true (demoting a persistent segment back to scratch) is not supported and is silently ignored.

Count invalidation: updating filter criteria does NOT automatically recompute record counts on audiences referencing this segment. Call POST /v1/segments/{id}/count to recompute.

The update itself emits no billable usage. Requires 'creator' scope.

When filters/filter_groups are provided, they're validated against the live Field Catalog before the update is applied — an unknown field, a disallowed operator, or an invalid enum value returns 400 INVALID_FILTER. If the Field Catalog is temporarily unreachable, returns 502 FILTER_CATALOG_UNAVAILABLE rather than applying an unvalidated update. record_limit on a non-filter segment returns 400 RECORD_LIMIT_UNSUPPORTED.

patch/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

Request body

namestring

Rename the segment.

status'archived' | 'active'

Valid user-settable transitions: archived or active (restore from archived). System-managed statuses (pending, failed, expired) cannot be set via this endpoint.

Archiving is always safe and reversible: it never affects audiences that already reference this segment (see the SegmentObject status attribute docs for why). Archived segments are excluded from the default GET /v1/segments list (pass ?include_archived=true to include them) and from new audience compositions, but remain fully readable via GET /v1/segments/{id} and can be restored with status: active at any time.

record_limitinteger nullable

filter subtype only. Sets or replaces the cap; null removes it; a cap requires State, City, or ZIP Code filters narrowing every OR branch to at most 100 ZIP3 regions (400 CAP_GEOGRAPHY_REQUIRED); omit to leave it unchanged. A change versions the segment like a filter edit (current_version increments).

count_snapshotnumber

filter subtype only. Verified count of the new definition, stored with a filters/filter_groups/record_limit change (clamped to the cap). Any definition change resets record_count; without count_snapshot it stays null until recounted (POST /v1/segments/{id}/count). Every audience that references the segment also has its record_count cleared and is recounted in the background.

column_mappingsobject

matched subtype only. Update column-to-identity-attribute mappings.

ephemeralboolean

Standalone "save this scratch segment" promotion for any ephemeral segment subtype — see the endpoint description above. Only false is honored.

Response

Updated segment.

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.