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:
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.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations
Request samples
Response samples
{
  • "data": {
    }
}

Create Destination Subscription

Creates a new Destination subscription.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
Request Body schema: application/vnd.segment.v1alpha+json
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.

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
{
  • "destinationId": "fP7qoQw2HTWt9WdMr718gn",
  • "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.

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

Pagination options.

This parameter exists in alpha.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations/{destinationId}/subscriptions
Request samples
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 ]
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

delete/destinations/{destinationId}
Request samples
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 ]
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations/{destinationId}
Request samples
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 ]
Request Body schema:
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
{
  • "destinationId": "fP7qoQw2HTWt9WdMr718gn",
  • "enabled": false
}
Response samples
{
  • "data": {
    }
}

Get Subscription from Destination

Gets a Destination subscription by id.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
id
required
string [ 1 .. 255 ]
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

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

Remove Subscription from Destination

Deletes an existing Destination subscription.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
id
required
string [ 1 .. 255 ]
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

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

Update Subscription for Destination

Updates an existing Destination subscription.

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
id
required
string [ 1 .. 255 ]
Request Body schema: application/vnd.segment.v1alpha+json
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
{
  • "id": "jur9cutEarKFw7fD65TCkq",
  • "destinationId": "fP7qoQw2HTWt9WdMr718gn",
  • "input": {
    }
}
Response samples
application/vnd.segment.v1alpha+json
{
  • "data": {
    }
}

List Delivery Metrics Summary from Destination

Get event delivery metrics summary from a Destination.

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

Minute Granularity:

  • Max time range: 4 hours

  • Oldest possible start time: 48 hours in the past

Hour Granularity:

  • Max Time range: 1 week

  • Oldest possible start time: 10 days in the past

Day Granularity:

  • Max time range: 60 days

  • Oldest possible start time: 60 days in the past

Securitytoken
Request
path Parameters
destinationId
required
string [ 1 .. 255 ]
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.

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.

endTime
string (endTime)

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

This parameter exists in beta.

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"
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/destinations/{destinationId}/delivery-metrics
Request samples
Response samples
{
  • "data": {
    }
}