Delivery Overview

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 other fields specific to Streaming Destinations, Actions Destinations, or Linked Audiences.

Public API support for Storage Destinations and RETL is currently in development.

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 time frame, 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 time frame, 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: `event Name`, `event Type`, `discard Reason`, `app Version`, `subscription Id`, `activationId`, `audienceId`, and `spaceId`. 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 `event Name`, `event Type`, `discard Reason`, `app Version`, `subscription Id`, `activationId`, `audienceId`, and/or `spaceId` that can be applied in addition to a `group By`. This parameter exists in beta. Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track&filter.spaceId=spa_123&filter.audienceId=aud_123
	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

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/failed-delivery

Request samples

TypeScript
Java
Python
Go
curl

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'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

application/vnd.segment.v1beta+json

{"data": {"total": 32504644,
"dataset": [{"eventName": "event-name",
"total": 32504644,
"series": [{"time": "2024-01-01T00:00:00Z",
"count": 15637145
},
{"time": "2024-01-02T00:00:00Z",
"count": 16867499
}
]
}
],
"pagination": {"current": "MA==",
"totalEntries": 1
}
}
}

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 time frame, 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 time frame, 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: `event Name`, `event Type`, `discard Reason`, `app Version`, `subscription Id`, `activationId`, `audienceId`, and `spaceId`. 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 `event Name`, `event Type`, `discard Reason`, `appVersion`, `subscription Id`, `activationId`, `audienceId`, or `spaceId` that can be applied in addition to a `group By`. If you would like to view retry attempts for a successful delivery, you can filter `discard Reason` 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&filter.spaceId=spa_123&filter.activationId=ee_123
	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

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/successful-delivery

Request samples

TypeScript
Java
Python
Go
curl

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'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

application/vnd.segment.v1beta+json

{"data": {"total": 32504644,
"dataset": [{"eventName": "event-name",
"total": 32504644,
"series": [{"time": "2024-01-01T00:00:00Z",
"count": 15637145
},
{"time": "2024-01-02T00:00:00Z",
"count": 16867499
}
]
}
],
"pagination": {"current": "MA==",
"totalEntries": 1
}
}
}

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 time frame, 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 time frame, 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: `event Name`, `event Type`, `discard Reason`, `app Version`, `subscription Id`, `activationId`, `audienceId`, and `spaceId`. This parameter exists in beta. Example: groupBy=groupBy.0=eventName&groupBy.1=subscriptionId
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 `event Name`, `event Type`, `discard Reason`, `app Version`, `subscription Id`, `activationId`, `audienceId`, and/or `spaceId` that can be applied in addition to a `group By`. This parameter exists in beta. Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track&filter.subscriptionId=sub&filter.spaceId=spa_123&filter.activationId=ee_123
	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

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/filtered-at-destination

Request samples

TypeScript
Java
Python
Go
curl

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'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

application/vnd.segment.v1beta+json

{"data": {"total": 32504644,
"dataset": [{"eventName": "event-name",
"spaceId": "spa_123",
"subscriptionId": "sub-id",
"total": 32504644,
"series": [{"time": "2024-01-01T00:00:00Z",
"count": 15637145
},
{"time": "2024-01-02T00:00:00Z",
"count": 16867499
}
]
}
],
"pagination": {"current": "MA==",
"totalEntries": 1
}
}
}

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 time frame, 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 time frame, 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: `event Name`, `event Type`, `discard Reason`, and `app Version`. 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 `event Name`, `event Type`, `discard Reason`, and/or `app Version` that can be applied in addition to a `group By`. This parameter exists in beta. Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track
	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

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/filtered-at-source

Request samples

TypeScript
Java
Python
Go
curl

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'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

application/vnd.segment.v1beta+json

{"data": {"total": 32504644,
"dataset": [{"eventName": "event-name",
"spaceId": "spa_123",
"subscriptionId": "sub-id",
"total": 32504644,
"series": [{"time": "2024-01-01T00:00:00Z",
"count": 15637145
},
{"time": "2024-01-02T00:00:00Z",
"count": 16867499
}
]
}
],
"pagination": {"current": "MA==",
"totalEntries": 1
}
}
}

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 time frame, 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 time frame, 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: `event Name`, `event Type`, `discard Reason`, and/or `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 `event Name`, `event Type`, `discard Reason`, and/or `app Version` that can be applied in addition to a `group By`. This parameter exists in beta. Example: filter=filter.discardReason=discard1&filter.eventName=name1%2Cname2&filter.eventType=track
	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

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/failed-on-ingest

Request samples

TypeScript
Java
Python
Go
curl

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'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

application/vnd.segment.v1beta+json

{"data": {"total": 32504644,
"dataset": [{"eventName": "event-name",
"total": 32504644,
"series": [{"time": "2024-01-01T00:00:00Z",
"count": 15637145
},
{"time": "2024-01-02T00:00:00Z",
"count": 16867499
}
]
}
],
"pagination": {"current": "MA==",
"totalEntries": 1
}
}
}

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 time frame, 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 time frame, 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: `event Name`, `event Type`, and/or `app Version`. 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 `event Name`, `event Type`, and/or `app Version` that can be applied in addition to a `group By`. This parameter exists in beta. Example: filter=filter.eventName=name1%2Cname2&filter.eventType=track
	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

404

Resource not found

422

Validation failure

429

Too many requests

get/delivery-overview/successfully-received

Request samples

TypeScript
Java
Python
Go
curl

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'
    )
  )
  console.log(JSON.stringify(result))
} catch (e) {
  console.log('ERROR:', e)
}

Response samples

application/vnd.segment.v1beta+json

{"data": {"total": 32504644,
"dataset": [{"eventName": "event-name",
"total": 32504644,
"series": [{"time": "2024-01-01T00:00:00Z",
"count": 15637145
},
{"time": "2024-01-02T00:00:00Z",
"count": 16867499
}
]
}
],
"pagination": {"current": "MA==",
"totalEntries": 1
}
}
}

➔ Next to IAM Users