Refresh Segment
refresh_segmentRe-derive a single stale or expired segment from the current IAG. Updates ONLY the segment — referencing audiences are never touched; the response lists them in affected_audiences so you can recount or refresh them (use refresh_audience for a whole-composition refresh). Behaviour is subtype-specific:
filter: synchronous — bumps current_version, nulls record_count, resets the 90-day TTL, returns status: active. If the segment is already fresh the call is a no-op (refreshed: false); pass force: true to bump anyway. Call count_segment afterwards for a fresh count.
matched: with hitl false/unset (default): returns status: pending + upload_url (24 h presign) targeting the canonical upload path — or upload_urls (an array) when shard_count > 1 — instruct the user to re-upload their identity list (one same-format file per URL for a sharded upload; every CSV shard needs its own header); identity resolution runs automatically once all shards are uploaded. Then call wait_for_segment(segment_id). With hitl: true: the upload is staged instead — after upload, follow the analyze_audience_upload -> confirm_column_mappings / cancel_matched_upload -> wait_for_segment sequence documented on create_segment(subtype=matched). Returns 409 SHARED_SOURCE_DATA for matched duplicates that reference another segment's data — the message names the source segment to refresh instead.
similarity: returns status: pending + workflow_run_id (re-launched scoring workflow). Call wait_for_workflow(workflow_run_id).
propensity: returns status: pending + workflow_run_id. 422 MISSING_POSITIVE_CLASS_ID for legacy segments that predate positive_class_segment_id storage — archive those with archive_segment and create a replacement. Returns 409 SEGMENT_ARCHIVED for archived segments — restore them first with archive_segment(restore=true). Requires 'creator' scope.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hitl | No | If true: pauses re-launched similarity/propensity workflows at human-in-the-loop gates; stages a matched segment's re-upload instead of resolving automatically. Defaults to false. | |
| force | No | Filter subtype only: bump the version even when the segment already looks fresh. Defaults to false. | |
| segment_id | Yes | The segment ID to refresh | |
| compression | No | Matched subtype: replacement upload compression. | none |
| shard_count | No | Matched subtype: set > 1 for multiple same-format shards. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| status | Yes | ||
| subtype | Yes | ||
| guidance | No | Interpretation or recovery guidance for this result | |
| next_step | Yes | ||
| refreshed | Yes | ||
| count_unit | No | ||
| page_count | No | Number of objects on this page, not the organization total | |
| segment_id | Yes | ||
| upload_url | No | ||
| audience_id | No | ||
| count_state | No | Unknown means no count; available does not guarantee freshness. Recount for a current value. | |
| upload_urls | No | ||
| next_actions | No | Suggested next calls using returned IDs and available scopes. Not executed and not user consent. | |
| record_count | No | Stored count; null means unknown. Call count_segment for a current count. | |
| record_limit | No | Maximum members; null means no explicit cap | |
| filter_groups | No | Complete saved filter definition; one AND group also represents a simple flat filter list | |
| money_display | No | Currency amounts formatted once from source paths ending in _cents. Use verbatim; do not divide again. Null/missing source amounts are omitted, not zero. | |
| current_version | No | ||
| workflow_run_id | No | ||
| population_input | No | Population input used for the preview; IDs refer to their current saved definitions | |
| upload_expires_at | No | ||
| affected_audiences | Yes |