---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/data-destinations/destination/amazon-kinesis#article
headline: Amazon Kinesis destination
description: Learn how to send event data to Amazon Kinesis Data Streams for real-time stream processing and analytics.
url: https://www.twilio.com/docs/data-destinations/destination/amazon-kinesis
inLanguage: en
dateModified: 2026-11-04T17:24:28.000Z
author:
"@type": Organization
name: Twilio Developer Education Team
publisher:
"@type": Organization
name: Twilio
---
# Amazon Kinesis destination
> \[!IMPORTANT]
>
> Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see [Private beta legal information](/docs/data-destinations#private-beta-legal-information).
[Amazon Kinesis](https://aws.amazon.com/kinesis/) is a fully managed,
real-time data streaming service that lets you ingest and process large
streams of records for analytics and downstream processing.
### Destination overview
* **Category**: Raw data
* **Release status**: Beta
* **Authentication**: AWS IAM role
* **Regional availability**: US1, IE1
## Join the Data Destinations private beta
[Sign up](https://airtable.com/appaJfyV6LiIFMxuP/pagIaOAtKsQVxTfdW/form)
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
## Eligible events
In the US1 region, you can send all event types to Amazon Kinesis. See [Event types](/docs/events/event-types-overview) for the full list.
In the IE1 region, only [Voice Insights](/docs/events/event-types-overview#voice-insights) events are eligible for delivery.
## Get started
### Prerequisites
Before you set up an Amazon Kinesis destination, make sure you have:
* An Amazon Web Services (AWS) account with:
* An existing Kinesis data stream. Twilio doesn't create the stream for
you.
* An identity and access management (IAM) role in your AWS account that Twilio can assume to write to the stream. This role must have a trust policy whose Principal is the intermediary role that Twilio assumes (`arn:aws:iam::177261743968:role/egress-domain-prod-isolated`).
* An **External ID** (2-1224 characters) that you choose and add to that role's trust policy `sts:ExternalId` condition, for cross-account security.
* The following AWS account information to create your Kinesis
destination:
* The Amazon Resource Name (ARN) of your IAM role.
* The Stream ARN of your Kinesis data stream.
* The External ID you added to your IAM role's trust policy.
## Create the destination
> \[!NOTE]
>
> See [Set up a destination](/docs/data-destinations/destination-setup) for the full UI and Destinations API setup flow common to every destination type.
### Twilio Console
To create a Kinesis destination in the Twilio Console:
1. From your AWS account, gather the settings listed in [Destination settings](#destination-settings).
2. In the Twilio Console, go to **Data** > **Data Destinations** > **Destinations** > **Add destination subscription**.
3. Complete the **Add destination subscription** wizard.
### Destinations API
To create an Amazon Kinesis destination through the Destinations API, send a `POST` request to the Destinations endpoint and set `destinationType` to `amazon-kinesis`. For authentication and the other request body fields, see [Create a destination](/docs/data-destinations/api-quickstart#create-a-destination).
```text title="Create a destination"
POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"
```
Set the `config` object in the request body as follows:
| Name | Type | Description |
| ------------------------------------------------- | ------ | -------------------------------------------------------------------- |
| `arn`
(**Required**) | string | The full ARN of the Amazon Kinesis Data Stream to deliver events to. |
| `credentials.credentialType`
(**Required**) | string | Set to `AWS_IAM`. |
| `credentials.externalId`
(**Required**) | string | The external ID in your IAM role's trust policy. |
| `credentials.roleArn`
(**Required**) | string | The ARN of the IAM role Twilio assumes in your AWS account. |
The following example shows a request body. Replace the uppercase placeholder values with your own.
```json title="Example request body"
{
"destinationType": "amazon-kinesis",
"name": "My Amazon Kinesis destination",
"config": {
"arn": "STREAM_ARN",
"credentials": {
"credentialType": "AWS_IAM",
"externalId": "EXTERNAL_ID",
"roleArn": "IAM_ROLE_ARN"
}
}
}
```
## Destination settings
Use `amazon-kinesis` as the `destinationType`.
| Field | Description | Required | Default |
| ------------ | -------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| Stream ARN | The full ARN of the Amazon Kinesis Data Stream to deliver events to. | Yes | None |
| IAM Role ARN | The ARN of the IAM role Twilio assumes in your AWS account to write to the stream. | Yes | None |
| External ID | External ID that must match the `sts:ExternalId` condition in your IAM role's trust policy. 2-1224 characters. | Yes | None |
Twilio authenticates to Kinesis by using AWS IAM role assumption rather than static credentials. You must set your role's trust policy Principal to the intermediary role Twilio assumes, not the Twilio AWS account.
Twilio assumes your IAM Role ARN in two steps. First, Twilio assumes an intermediary AWS role (`arn:aws:iam::177261743968:role/egress-domain-prod-isolated`).
Then that role assumes your IAM Role ARN and passes your **External ID** as the `sts:ExternalId` condition to obtain short-lived, rotated credentials scoped to your stream. Twilio doesn't store long-lived API keys.
## Default mappings
| Field | Kinesis field |
| ------------------- | ------------- |
| Event source | Partition Key |
| Full event envelope | Record data |
## Verification and troubleshooting
When you save an Amazon Kinesis destination, Twilio validates the connection by
assuming your IAM role and confirming it can read your stream's shard
information. If validation fails, check that:
* The **IAM Role ARN** is correct and its trust policy allows the intermediary role (`arn:aws:iam::177261743968:role/egress-domain-prod-isolated`), with an `sts:ExternalId` condition matching your **External ID**, to assume it.
* The role has permission to access the stream.
* The **Stream ARN** is correct and the stream exists in the expected region.
To trigger a test event, open the Console and go to the **Trigger Test Event** utility.
A corresponding record appears in your Kinesis stream shortly after.
### Common errors
| Cause | What you'll see | Fix |
| ---------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Role assumption denied or missing stream permissions | Validation fails with an auth error | Check the role's trust policy. Principal must be the intermediary role (`arn:aws:iam::177261743968:role/egress-domain-prod-isolated`), not just the Twilio AWS account, including the `sts:ExternalId` condition, and the role's stream permissions |
| Stream not found | Validation fails with a configuration error | Confirm the Stream ARN and that the stream exists in that region |
| Other AWS-side error | Validation fails with a resource error | Check the stream's status in the AWS Console and retry |
If Twilio can't deliver events to your stream, Twilio sends an error notification to the [Debugger](/docs/usage/troubleshooting/debugging-your-application) (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.
## Additional resources
* [Destinations overview](/docs/data-destinations/destinations-overview)
* [Set up a destination](/docs/data-destinations/destination-setup)
* [Event types reference](/docs/events/event-types-overview)