Twilio Segment logo

Destinations

Destinations receive data from Segment.

In the Segment Public API, you can manipulate Destinations and the connections between Sources and Destinations, as well as list and inspect their relationships.

Migrate from the Config API

Like Segment Public API, Config API allows creating, retrieving, updating and deleting Destination objects. See the table below for some key differences:

Config API Public API
catalogId Not returned
config settings
connectionMode Not returned
createTime Not returned
displayName name
enabled enabled
name See note on names vs IDs in the migration guide
parent sourceId (prefix removed)
updateTime Not returned

To migrate, replace any use of the Config API endpoints with the Segment Public API counterparts, using the field mappings in the table above.

Create Destination

Creates a new Destination.

• When called, this endpoint may generate the Integration Created event in the audit trail.

Securitytoken
Request
Request Body schema:
required
sourceId
required
string (sourceId)

The id of the Source to connect to this Destination instance.

Config API note: analogous to parent.

metadataId
required
string (metadataId)

The id of the metadata to link to the new Destination.

enabled
boolean (enabled)

Whether this Destination should receive data.

name
string (name)

Defines the display name of the Destination.

Config API note: equal to displayName.

required
object (settings)

An object that contains settings for the Destination based on the "required" and "advanced" settings present in the Destination metadata.

Config API note: equal to config.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/destinations
Request samples
{
  • "sourceId": "rh5BDZp6QDHvXFCkibm1pR",
  • "metadataId": "547610a5db31d978f14a5c4e",
  • "name": "my destination v1",
  • "settings": {
    }
}
Response samples
{
  • "data": {
    }
}

List Destinations

Returns a list of Destinations.

Securitytoken
Request
query Parameters
required
object (PaginationInput)

Required pagination params for the request.

This parameter exists in v1.

Example: pagination[count]=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations
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.destinations.listDestinations({ count: 1 }))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Create Destination Subscription

Creates a new Destination subscription.

• 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 Destination Subscriptions feature enabled. Please reach out to your customer success manager for more information.

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

A user-defined name for the subscription.

actionId
required
string (actionId)

The associated action id the subscription should trigger.

trigger
required
string (trigger)

The FQL statement.

enabled
required
boolean (enabled)

Is the subscription enabled.

object (settings)

The fields used for configuring this action.

modelId
string (modelId)

When creating a Reverse ETL connection, indicates the Model being used to extract data.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

post/destinations/{destinationId}/subscriptions
Request samples
application/vnd.segment.v1alpha+json
{
  • "name": "Example Subscription",
  • "actionId": "jiMz7MfHNeHmUckzRnUGkU",
  • "trigger": "type = \"track\"",
  • "enabled": false
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

List Subscriptions from Destination

Lists subscriptions for a Destination.

• 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 Destination Subscriptions feature enabled. Please reach out to your customer success manager for more information.

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

Pagination options.

This parameter exists in alpha.

Example: pagination[count]=3
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations/{destinationId}/subscriptions
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.destinations.listSubscriptionsFromDestination('fP7qoQw2HTWt9WdMr718gn', { count: 3 }))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

Delete Destination

Deletes an existing Destination.

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

Config API omitted fields:

  • catalogId
Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
Example: 6424a4a5b03b3d8fe288f000
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/destinations/{destinationId}
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.destinations.deleteDestination('6424a4a5b03b3d8fe288f000'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Get Destination

Returns a Destination by its id.

  Config API omitted fields:
  • catalogId
Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
Example: fP7qoQw2HTWt9WdMr718gn
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations/{destinationId}
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.destinations.getDestination('fP7qoQw2HTWt9WdMr718gn'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}

Update Destination

Updates an existing Destination.

Note: if you attempt to update read-only settings for your destination you'll encounter the following behavior:

  • If only read-only properties are being updated, the endpoint will return an HTTP 400 error.
  • If there's a mix of writable and read-only properties in the payload, the request will be accepted, the writable properties will be updated and the read-only properties ignored.

• When called, this endpoint may generate the Integration Disabled event in the audit trail.

Config API omitted fields:

  • updateMask
Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
Example: fP7qoQw2HTWt9WdMr718gn
Request Body schema:
required
name
string or null (name)

Defines the display name of the Destination.

Config API note: equal to displayName.

enabled
boolean (enabled)

Whether this Destination should receive data.

object (settings)

An optional object that contains settings for the Destination based on the "required" and "advanced" settings present in the Destination metadata.

Config API note: equal to config.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/destinations/{destinationId}
Request samples
{
  • "enabled": false
}
Response samples
{
  • "data": {
    }
}

Get Subscription from Destination

Gets a Destination subscription by id.

• 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 Destination Subscriptions feature enabled. Please reach out to your customer success manager for more information.

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

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations/{destinationId}/subscriptions/{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.destinations.getSubscriptionFromDestination('fP7qoQw2HTWt9WdMr718gn', 'iUyx2UdPSvp4uJtYAhjTup'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

Remove Subscription from Destination

Deletes an existing Destination subscription.

• 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 Destination Subscriptions feature enabled. Please reach out to your customer success manager for more information.

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

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/destinations/{destinationId}/subscriptions/{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.destinations.removeSubscriptionFromDestination('fP7qoQw2HTWt9WdMr718gn', 'bXbWrgh8vAeWioqx6Kg5vb'))
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

Update Subscription for Destination

Updates an existing Destination subscription.

• 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 Destination Subscriptions feature enabled. Please reach out to your customer success manager for more information.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
Example: fP7qoQw2HTWt9WdMr718gn
id
required
string [ 1 .. 255 ]
Example: mAdhWCVCmFadguoGcqP3vN
Request Body schema: application/vnd.segment.v1alpha+json
required
required
object (input)

A set of valid Destination input params required for updating.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

patch/destinations/{destinationId}/subscriptions/{id}
Request samples
application/vnd.segment.v1alpha+json
{
  • "input": {
    }
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

List Delivery Metrics Summary from Destination

Get an event delivery metrics summary from a Destination.

Based on the granularity chosen, there are restrictions on the time range you can query:

Minute:

  • Max time range: 4 hours
  • Oldest possible start time: 48 hours in the past

Hour:

  • Max Time range: 7 days
  • Oldest possible start time: 7 days in the past

Day:

  • Max time range: 14 days
  • Oldest possible start time: 14 days in the past

The rate limit for this endpoint is 60 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
destinationId
required
string [ 1 .. 255 ]
Example: fP7qoQw2HTWt9WdMr718gn
query Parameters
sourceId
required
string (sourceId)

The id of the Source linked to the Destination.

Config API note: analogous to parent.

This parameter exists in beta.

Example:
startTime
string (startTime)

Filter events that happened after this time.

Defaults to:

  • 1 hour ago if granularity is MINUTE.
  • 7 days ago if granularity is HOUR.
  • 30 days ago if granularity is DAY.

This parameter exists in beta.

Example:
endTime
string (endTime)

Filter events that happened before this time. Defaults to now if not set.

This parameter exists in beta.

Example:
granularity
string (granularity)

The granularity to filter metrics to. Either MINUTE, HOUR or DAY.

Defaults to MINUTE if not set.

This parameter exists in beta.

Enum: "DAY" "HOUR" "MINUTE"
Example:
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations/{destinationId}/delivery-metrics
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.destinations.listDeliveryMetricsSummaryFromDestination('fP7qoQw2HTWt9WdMr718gn', 'rh5BDZp6QDHvXFCkibm1pR')
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
{
  • "data": {
    }
}
➔ Next to Edge Functions