Permanently remove a segment

DELETE

/v1/segments/{id}

const url = 'https://api.infiniteaudience.ai/v1/segments/example';
const options = {method: 'DELETE', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request DELETE \
  --url https://api.infiniteaudience.ai/v1/segments/example \
  --header 'Authorization: Bearer <token>'

Removes the segment from every read surface: GET /v1/segments/{id} returns 404 afterward, and GET /v1/segments always excludes it (there is no override, unlike archived segments). There is no restore endpoint — this is a one-way operation from the API’s perspective, even though the underlying record is retained internally rather than hard-deleted.

Effect on audiences: unlike archiving, deleting a segment that’s referenced by one or more audiences changes those audiences’ composition — the segment is dropped from their resolved segment list and record count. This is the reason for the impact check below; archiving has no such check because it never has this effect.

Impact check: if the segment is referenced by one or more active audiences, the server returns a 409 with audience_count, campaign_count, and an audiences list. Re-submit with ?confirm_impact=true to proceed anyway.

Not idempotent: calling this twice returns 404 on the second call, since the segment is already excluded from lookup after the first delete. No credits are debited. Requires ‘creator’ scope.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

Query Parameters

confirm_impact

boolean

Pass true to delete a segment that is referenced by active audiences. Omitting this parameter on an in-use segment returns a 409 with impact details.

Responses

204

Segment successfully deleted (archived).

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

missing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the creator scope."
}

404

Resource not found or not accessible to the calling org.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

not_found

{
  "error": "Audience not found"
}

409

Segment is referenced by one or more active audiences. Response body includes impact details. Re-submit with ?confirm_impact=true to delete anyway.

application/json

object

error

required

string

code

required

string

Allowed values: SEGMENT_IN_USE

message

required

string

audience_count

required

integer

campaign_count

required

integer

audiences

Array<object>

object

required

string

name

required

string

campaign_id

required

The campaign the audience belongs to, or null.

string | null

Example

{
  "code": "SEGMENT_IN_USE"
}