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.

Get Audience

Returns the Audience by id and spaceId.

• This endpoint is in Alpha testing. Please submit any feedback by sending 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 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 enabled status for an audience

• This endpoint is in Alpha testing. Please submit any feedback by sending 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.

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
required
boolean (enabled)

Enabled/disabled status for the audience.

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": {
    }
}

List Audiences

Returns Audiences by spaceId.

• This endpoint is in Alpha testing. Please submit any feedback by sending 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
required
object (PaginationInput)

Information about the pagination of this response.

This parameter exists in alpha.

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": {
    }
}
➔ Next to Testing