Twilio Segment logo

Audiences

Audiences play a key role in gaining a deeper understanding of your users. Audiences allow you to group users or profiles based on shared characteristics, behaviors, and attributes. Using events passed into Segment, traits, and computed traits you can create Audiences which can help unlock more relevant engagement and communication.

Note: The Audience API is currently in a Private Beta. If you are interested in joining the Private Beta, then please reach out to your customer success manager.

Create Audience

Creates Audience.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Audience Created event in the audit trail. Note: The definition for an Audience created using the API is not editable through the Segment App.

The rate limit for this endpoint is 10 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
spaceId
required
string [ 1 .. 255 ]
Example: spaceId
Request Body schema: application/vnd.segment.v1alpha+json
required
name
required
string (name)

Name of the audience.

enabled
boolean (enabled)

Determines whether a computation is enabled.

description
string (description)

Description of the audience.

required
object (definition)

Query language definition and type.

object (options)

Represents the options of Including Anonymous users and Historical Data.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/spaces/{spaceId}/audiences
Request samples
application/vnd.segment.v1alpha+json
{
  • "name": "name",
  • "description": "description",
  • "enabled": false,
  • "definition": {
    },
  • "options": {
    }
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

List Audiences

Returns Audiences by spaceId.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

The rate limit for this endpoint is 25 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
spaceId
required
string [ 1 .. 255 ]
Example: spaceId
query Parameters
object (PaginationInput)

Information about the pagination of this response.

See pagination for more info.

This parameter exists in alpha.

Example: pagination=pagination.count=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/spaces/{spaceId}/audiences
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.audiences.listAudiences('spaceId'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

Get Audience

Returns the Audience by id and spaceId.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

The rate limit for this endpoint is 100 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
spaceId
required
string [ 1 .. 255 ]
Example: spaceId
id
required
string [ 1 .. 255 ]
Example: id
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/spaces/{spaceId}/audiences/{id}
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.audiences.getAudience('spaceId', 'id'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

Remove Audience from Space

Deletes an Audience by id and spaceId.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Audience Deleted event in the audit trail.

The rate limit for this endpoint is 20 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
spaceId
required
string [ 1 .. 255 ]
Example: spaceId
id
required
string [ 1 .. 255 ]
Example: id
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/spaces/{spaceId}/audiences/{id}
Request samples 
import { configureApis, unwrap } from '@segment/public-api-sdk-typescript'

const api = configureApis('/* Insert your Public API token here */')

try {
  const result = await unwrap(api.audiences.removeAudienceFromSpace('spaceId', 'id'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

Update Audience for Space

Updates the Audience.

• This endpoint is in Alpha testing. Please submit any feedback by sending an email to friends@segment.com.

• In order to successfully call this endpoint, the specified Workspace needs to have the Audience feature enabled. Please reach out to your customer success manager for more information.

• When called, this endpoint may generate the Audience Modified event in the audit trail.

• Note that when an Audience is updated, the Audience will be locked from future edits until the changes have been incorporated. You can find more information in the Segment docs. Note: The definition for an Audience updated using the API is not editable through the Segment App.

The rate limit for this endpoint is 10 requests per minute, which is lower than the default due to access pattern restrictions. Once reached, this endpoint will respond with the 429 HTTP status code with headers indicating the limit parameters. See Rate Limiting for more information.

Securitytoken
Request
path Parameters
spaceId
required
string [ 1 .. 255 ]
Example: spaceId
id
required
string [ 1 .. 255 ]
Example: id
Request Body schema: application/vnd.segment.v1alpha+json
required
enabled
boolean (enabled)

Enabled/disabled status for the audience.

name
string (name)

The name of the computation.

description
string (description)

The description of the computation.

object (definition)

Represents the Compute Query Language definition of the computation and type of computation. Note: The definition for an Audience updated using the API is not editable through the Segment App.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/spaces/{spaceId}/audiences/{id}
Request samples
application/vnd.segment.v1alpha+json
{
  • "enabled": false
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}
➔ Next to Computed Traits