Delivery Overview

Delivery Overview enables users to troubleshoot a destination’s activity & performance, from the source, through Segment, and to the delivery attempt at the destination.

With Delivery Overview Public API, customers can query their data directly instead of going through the Segment app. They can inspect their data with more granularity by specifying custom time periods, and grouping or filtering their data by discard reasons, event names, event types, app versions, and subscriptionIDs.

Get Egress Failed Metrics from Delivery Overview

Get events that failed to be delivered to Destination.

Securitytoken
Request
query Parameters
sourceId
required
string (sourceId)

The sourceId for the Workspace.

This parameter exists in beta.

Example: sourceId=rh5BDZp6QDHvXFCkibm1pR
destinationConfigId
required
string (destinationConfigId)

The id tied to a Workspace Destination.

This parameter exists in beta.

Example: destinationConfigId=fP7qoQw2HTWt9WdMr718gn
startTime
required
string (startTime)

The ISO8601 formatted timestamp corresponding to the beginning of the requested timeframe, inclusive.

This parameter exists in beta.

Example: startTime=2024-01-01T00:00:00Z
endTime
required
string (endTime)

The ISO8601 formatted timestamp corresponding to the end of the requested timeframe, noninclusive.

This parameter exists in beta.

Example: endTime=2024-01-03T00:00:00Z
groupBy
Array of strings (groupBy)

A comma-delimited list of strings representing one or more dimensions to group the result by. Valid options are: eventName, eventType, discardReason, appVersion, and subscriptionId.

This parameter exists in beta.

Example: groupBy=groupBy.0=eventName
granularity
required
string (granularity)

The size of each bucket in the requested window.

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: 14 days
  • Oldest possible start time: 30 days in the past

Day:

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

This parameter exists in beta.

Enum: "DAY" "HOUR" "MINUTE"
Example: granularity=DAY
object (DeliveryOverviewDestinationFilterBy)

An optional filter for eventName, eventType, discardReason, appVersion, and/or subscriptionId that can be applied in addition to a groupBy.

This parameter exists in beta.

Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track
required
object (PaginationInput)

Params to specify the page cursor and count.

This parameter exists in beta.

Example: pagination=pagination.cursor=MA%3D%3D&pagination.count=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/failed-delivery
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.deliveryOverview.getEgressFailedMetricsFromDeliveryOverview(
      'rh5BDZp6QDHvXFCkibm1pR',
      'fP7qoQw2HTWt9WdMr718gn',
      '2024-01-01T00:00:00Z',
      '2024-01-03T00:00:00Z',
      'DAY',
      'pagination.cursor=MA%3D%3D&pagination.count=1'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1beta+json
{
  • "data": {
    }
}

Get Egress Success Metrics from Delivery Overview

Get events successfully delivered to Destination.

Securitytoken
Request
query Parameters
sourceId
required
string (sourceId)

The sourceId for the Workspace.

This parameter exists in beta.

Example: sourceId=rh5BDZp6QDHvXFCkibm1pR
destinationConfigId
required
string (destinationConfigId)

The id tied to a Workspace Destination.

This parameter exists in beta.

Example: destinationConfigId=fP7qoQw2HTWt9WdMr718gn
startTime
required
string (startTime)

The ISO8601 formatted timestamp corresponding to the beginning of the requested timeframe, inclusive.

This parameter exists in beta.

Example: startTime=2024-01-01T00:00:00Z
endTime
required
string (endTime)

The ISO8601 formatted timestamp corresponding to the end of the requested timeframe, noninclusive.

This parameter exists in beta.

Example: endTime=2024-01-03T00:00:00Z
groupBy
Array of strings (groupBy)

A comma-delimited list of strings representing one or more dimensions to group the result by. Valid options are: eventName, eventType, discardReason, appVersion, and subscriptionId.

This parameter exists in beta.

Example: groupBy=groupBy.0=eventName
granularity
required
string (granularity)

The size of each bucket in the requested window.

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: 14 days
  • Oldest possible start time: 30 days in the past

Day:

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

This parameter exists in beta.

Enum: "DAY" "HOUR" "MINUTE"
Example: granularity=DAY
object (DeliveryOverviewDestinationFilterBy)

An optional filter for eventName, eventType, discardReason, appVersion, and/or subscriptionId that can be applied in addition to a groupBy. If you would like to view retry attempts for a successful delivery, you can filter discardReason from successes.attempt.1 through successes.attempt.10.

This parameter exists in beta.

Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track
required
object (PaginationInput)

Params to specify the page cursor and count.

This parameter exists in beta.

Example: pagination=pagination.cursor=MA%3D%3D&pagination.count=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/successful-delivery
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.deliveryOverview.getEgressSuccessMetricsFromDeliveryOverview(
      'rh5BDZp6QDHvXFCkibm1pR',
      'fP7qoQw2HTWt9WdMr718gn',
      '2024-01-01T00:00:00Z',
      '2024-01-03T00:00:00Z',
      'DAY',
      'pagination.cursor=MA%3D%3D&pagination.count=1'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1beta+json
{
  • "data": {
    }
}

Get Filtered At Destination Metrics from Delivery Overview

Get events that were filtered at Destination.

Securitytoken
Request
query Parameters
sourceId
required
string (sourceId)

The sourceId for the Workspace.

This parameter exists in beta.

Example: sourceId=rh5BDZp6QDHvXFCkibm1pR
destinationConfigId
required
string (destinationConfigId)

The id tied to a Workspace Destination.

This parameter exists in beta.

Example: destinationConfigId=fP7qoQw2HTWt9WdMr718gn
startTime
required
string (startTime)

The ISO8601 formatted timestamp corresponding to the beginning of the requested timeframe, inclusive.

This parameter exists in beta.

Example: startTime=2024-01-01T00:00:00Z
endTime
required
string (endTime)

The ISO8601 formatted timestamp corresponding to the end of the requested timeframe, noninclusive.

This parameter exists in beta.

Example: endTime=2024-01-03T00:00:00Z
groupBy
Array of strings (groupBy)

A comma-delimited list of strings representing one or more dimensions to group the result by. Valid options are: eventName, eventType, discardReason, appVersion, and subscriptionId.

This parameter exists in beta.

Example: groupBy=groupBy.0=eventName
granularity
required
string (granularity)

The size of each bucket in the requested window.

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: 14 days
  • Oldest possible start time: 30 days in the past

Day:

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

This parameter exists in beta.

Enum: "DAY" "HOUR" "MINUTE"
Example: granularity=DAY
object (DeliveryOverviewDestinationFilterBy)

An optional filter for eventName, eventType, discardReason, appVersion, and/or subscriptionId that can be applied in addition to a groupBy.

This parameter exists in beta.

Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track&filter.subscriptionId=sub-id
required
object (PaginationInput)

Params to specify the page cursor and count.

This parameter exists in beta.

Example: pagination=pagination.cursor=MA%3D%3D&pagination.count=1
subscriptionId
string (subscriptionId)

An optional filter for actions destinations, to filter by a specific action.

This parameter exists in beta.

Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/filtered-at-destination
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.deliveryOverview.getFilteredAtDestinationMetricsFromDeliveryOverview(
      'rh5BDZp6QDHvXFCkibm1pR',
      'fP7qoQw2HTWt9WdMr718gn',
      '2024-01-01T00:00:00Z',
      '2024-01-03T00:00:00Z',
      'DAY',
      'pagination.cursor=MA%3D%3D&pagination.count=1'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1beta+json
{
  • "data": {
    }
}

Get Filtered At Source Metrics from Delivery Overview

Get events that were filtered at Source.

Securitytoken
Request
query Parameters
sourceId
required
string (sourceId)

The sourceId for the Workspace.

This parameter exists in beta.

Example: sourceId=rh5BDZp6QDHvXFCkibm1pR
startTime
required
string (startTime)

The ISO8601 formatted timestamp corresponding to the beginning of the requested timeframe, inclusive.

This parameter exists in beta.

Example: startTime=2024-01-01T00:00:00Z
endTime
required
string (endTime)

The ISO8601 formatted timestamp corresponding to the end of the requested timeframe, noninclusive.

This parameter exists in beta.

Example: endTime=2024-01-03T00:00:00Z
groupBy
Array of strings (groupBy)

A comma-delimited list of strings representing one or more dimensions to group the result by. Valid options are: eventName, eventType, discardReason, and appVersion.

This parameter exists in beta.

Example: groupBy=groupBy.0=eventName
granularity
required
string (granularity)

The size of each bucket in the requested window.

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: 14 days
  • Oldest possible start time: 30 days in the past

Day:

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

This parameter exists in beta.

Enum: "DAY" "HOUR" "MINUTE"
Example: granularity=DAY
object (DeliveryOverviewSourceFilterBy)

An optional filter for eventName, eventType, discardReason, and/or appVersion that can be applied in addition to a groupBy.

This parameter exists in beta.

Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track
required
object (PaginationInput)

Optional params to specify the page cursor and count.

This parameter exists in beta.

Example: pagination=pagination.cursor=MA%3D%3D&pagination.count=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/filtered-at-source
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.deliveryOverview.getFilteredAtSourceMetricsFromDeliveryOverview(
      'rh5BDZp6QDHvXFCkibm1pR',
      '2024-01-01T00:00:00Z',
      '2024-01-03T00:00:00Z',
      'DAY',
      'pagination.cursor=MA%3D%3D&pagination.count=1'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1beta+json
{
  • "data": {
    }
}

Get Ingress Failed Metrics from Delivery Overview

Get events that failed on ingest.

Securitytoken
Request
query Parameters
sourceId
required
string (sourceId)

The sourceId for the Workspace.

This parameter exists in beta.

Example: sourceId=rh5BDZp6QDHvXFCkibm1pR
startTime
required
string (startTime)

The ISO8601 formatted timestamp corresponding to the beginning of the requested timeframe, inclusive.

This parameter exists in beta.

Example: startTime=2024-01-01T00:00:00Z
endTime
required
string (endTime)

The ISO8601 formatted timestamp corresponding to the end of the requested timeframe, noninclusive.

This parameter exists in beta.

Example: endTime=2024-01-03T00:00:00Z
groupBy
Array of strings (groupBy)

A comma-delimited list of strings representing one or more dimensions to group the result by. Valid options are: eventName, eventType, discardReason, and appVersion.

This parameter exists in beta.

Example: groupBy=groupBy.0=eventName
granularity
required
string (granularity)

The size of each bucket in the requested window.

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: 14 days
  • Oldest possible start time: 30 days in the past

Day:

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

This parameter exists in beta.

Enum: "DAY" "HOUR" "MINUTE"
Example: granularity=DAY
object (DeliveryOverviewSourceFilterBy)

An optional filter for eventName, eventType, discardReason, and/or appVersion that can be applied in addition to a groupBy.

This parameter exists in beta.

Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track
required
object (PaginationInput)

Optional params to specify the page cursor and count.

This parameter exists in beta.

Example: pagination=pagination.cursor=MA%3D%3D&pagination.count=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/failed-on-ingest
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.deliveryOverview.getIngressFailedMetricsFromDeliveryOverview(
      'rh5BDZp6QDHvXFCkibm1pR',
      '2024-01-01T00:00:00Z',
      '2024-01-03T00:00:00Z',
      'DAY',
      'pagination.cursor=MA%3D%3D&pagination.count=1'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1beta+json
{
  • "data": {
    }
}

Get Ingress Success Metrics from Delivery Overview

Get events that were successfully received by Segment.

Securitytoken
Request
query Parameters
sourceId
required
string (sourceId)

The sourceId for the Workspace.

This parameter exists in beta.

Example: sourceId=rh5BDZp6QDHvXFCkibm1pR
startTime
required
string (startTime)

The ISO8601 formatted timestamp corresponding to the beginning of the requested timeframe, inclusive.

This parameter exists in beta.

Example: startTime=2024-01-01T00:00:00Z
endTime
required
string (endTime)

The ISO8601 formatted timestamp corresponding to the end of the requested timeframe, noninclusive.

This parameter exists in beta.

Example: endTime=2024-01-03T00:00:00Z
groupBy
Array of strings (groupBy)

A comma-delimited list of strings representing one or more dimensions to group the result by. Valid options are: eventName, eventType, and appVersion.

This parameter exists in beta.

Example: groupBy=groupBy.0=eventName
granularity
required
string (granularity)

The size of each bucket in the requested window.

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: 14 days
  • Oldest possible start time: 30 days in the past

Day:

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

This parameter exists in beta.

Enum: "DAY" "HOUR" "MINUTE"
Example: granularity=DAY
object (DeliveryOverviewSuccessfullyReceivedFilterBy)

An optional filter for eventName, eventType, and/or appVersion that can be applied in addition to a groupBy.

This parameter exists in beta.

Example: filter=filter.eventName=name1%2Cname2&filter.eventType=track
required
object (PaginationInput)

Optional params to specify the page cursor and count.

This parameter exists in beta.

Example: pagination=pagination.cursor=MA%3D%3D&pagination.count=1
Responses
200

OK

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/successfully-received
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.deliveryOverview.getIngressSuccessMetricsFromDeliveryOverview(
      'rh5BDZp6QDHvXFCkibm1pR',
      '2024-01-01T00:00:00Z',
      '2024-01-03T00:00:00Z',
      'DAY',
      'pagination.cursor=MA%3D%3D&pagination.count=1'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}
Response samples
application/vnd.segment.v1beta+json
{
  • "data": {
    }
}