Twilio
Use this page to set up the Twilio source connector and review its reference information.
Prerequisites
- A Twilio Account SID and Auth Token. You can find both in the Twilio Console.
- Use credentials for the Twilio account containing the resources you want to sync. Main account credentials can access main account resources. They can also access v2010 REST API resources for subaccounts. Subaccount credentials can access only that subaccount.
- For resources on product-specific subdomains, use credentials for the account that owns them. These subdomains include Studio, Conversations and Verify.
For more information, see the Twilio API authentication documentation.
Set up Twilio
For Airbyte Cloud:
- Log into your Airbyte Cloud account.
- In the left navigation bar, click Sources. In the top-right corner, click +new source.
- On the Set up the source page, enter a name for the Twilio connector. Select Twilio from the source type dropdown.
- Enter your Account ID (Twilio Account SID).
- Enter your Auth Token.
- Enter a Replication Start Date. Records created before this UTC date and time aren’t synced. Use the format
YYYY-MM-DDTHH:MM:SSZ, for example,2020-10-01T00:00:00Z. - You can also configure these fields:
- Lookback window: The number of minutes before the last cursor value to re-fetch during each incremental sync. Use this field to capture late-arriving records. The default is
0. - Number of concurrent threads: The number of worker threads used during a sync. The default is
3. The maximum is40. - Slice Step Duration: The time window for each incremental stream slice. See Tuning the slice step duration. The default is 1 Month (
P1M).
- Lookback window: The number of minutes before the last cursor value to re-fetch during each incremental sync. Use this field to capture late-arriving records. The default is
- Click Set up source.
For Airbyte Open Source:
- Go to the Airbyte Open Source dashboard.
- Enter a name for your source.
- Enter your Account ID (Twilio Account SID).
- Enter your Auth Token.
- Enter a Replication Start Date using the format
YYYY-MM-DDTHH:MM:SSZ. - You can also set Lookback window, Number of concurrent threads and Slice Step Duration. See the Cloud instructions above for details.
- Click Set up source.
Supported sync modes
The Twilio source connector supports these sync modes:
| Feature | Supported? |
|---|---|
| Full Refresh Sync | Yes |
| Incremental Sync | Yes |
| Replicate Incremental Deletes | No |
| SSL connection | Yes |
| Namespaces | No |
Supported streams
Pricing streams
The voice_pricing_countries, messaging_pricing_countries and phone_number_pricing_countries streams return per-country price lists from Twilio’s Pricing API. Each stream first pages through the list of supported countries. It then makes one additional request per country to fetch that country’s prices. A sync therefore makes more API requests than the number of supported countries. Prices depend on the account you authenticate with. base_price is Twilio’s list price. current_price includes any volume or custom discounts on your account. Each record uses iso_country as its key.
Upgrade to 1.0.0
Version 1.0.0 moves the services and roles streams from the deprecated Programmable Chat API to the Conversations API. If your connections sync either stream, refresh the source schema after upgrading. Then clear the data for those streams. For the full schema changes and migration steps, see the migration guide.
Limitations
400-day data window
The messages, recordings and message_media streams sync only the last 400 days of data, regardless of the configured Replication Start Date. This matches Twilio’s default Message Log retention, which stores message records and media for up to 13 months, or approximately 400 days. If your Replication Start Date is over 400 days ago, these streams begin from 400 days ago. Other streams follow the configured start date without this limit.
To retrieve records older than 400 days, use Twilio’s Bulk Export API outside this connector.
Active conference participants
The conference_participants stream returns participants only for active conferences with init or in-progress status. Twilio’s Participants subresource manages only active participants in conferences that are still in progress. It doesn’t return participants from completed conferences, so the connector can’t sync them. To capture activity throughout a conference, subscribe to Twilio conference status callbacks in your application. Store the events as participants join and leave.
This limitation doesn’t affect the conferences stream. It syncs conferences in every status: init, in-progress and completed.
Performance
The Twilio connector handles rate limits using the Retry-After header, with exponential backoff as a fallback. For more information, see Twilio’s rate limit documentation.
By default, the connector syncs with 3 concurrent threads. Increase Number of concurrent threads only if your Twilio account can handle the additional API traffic. Reduce the thread count if syncs are repeatedly rate limited. If high-volume incremental streams time out, use a smaller slice step duration.
Alerts pagination limit
The Alerts API limits each request to 10,000 Alert resources. If a time window contains over 10,000 Alert records, the connector splits it in half and reads each half. It repeats this process up to 10 times. Twilio rejects a window only after the connector reads its first 10,000 records. Each split therefore re-emits up to 10,000 records. Sync modes that deduplicate by primary key (sid) remove these duplicates. Append and Overwrite sync modes keep them. Splitting stops after 10 halvings, so the smallest window depends on Slice Step Duration. It’s about 43 minutes with the default 1 Month and about 84 seconds with 1 Day. If the alerts stream still fails after splitting, decrease Slice Step Duration. If it’s already 1 Day, deselect the alerts stream.
Set the slice step duration
Incremental streams page the Twilio API using fixed time windows between the replication start date and now. The Slice Step Duration option controls each window’s size. It lets you balance the request count against the data returned by each request.
| Option | ISO 8601 value | When to use |
|---|---|---|
| 1 Day | P1D | Very high volume accounts where monthly or weekly windows trigger Twilio timeouts, or where alerts can’t split a window within 10 splits. |
| 1 Week | P1W | High volume accounts that still time out with monthly windows. |
| 1 Month | P1M | Default. Works well for most accounts and minimizes request count compared to shorter windows. |
| 1 Year | P1Y | Low volume accounts or short backfills where you want to minimize the number of slices per stream. |
Smaller windows increase API requests and the likelihood of rate limits. However, they reduce the data Twilio must return per request. Larger windows reduce the request count but can time out on busy accounts. Lower the slice step duration if the following streams time out: calls, messages, recordings, message_media, conference_participants, usage_records or alerts.
IP allow list
If you use Airbyte Cloud and restrict access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Reference
This connector uses REST APIs. These include the https://api.twilio.com/2010-04-01, https://monitor.twilio.com/v1, https://conversations.twilio.com/v1, https://studio.twilio.com/v1, https://trunking.twilio.com/v1, https://verify.twilio.com/v2, https://pricing.twilio.com/v1 and https://pricing.twilio.com/v2 API endpoints.
For programmatic configuration, use these parameter names:
| Field | Required | Description |
|---|---|---|
account_sid | Yes | Account identifier used as the HTTP Basic authentication username. |
auth_token | Yes | Auth Token used as the HTTP Basic authentication password. |
start_date | Yes | Date and time in YYYY-MM-DDTHH:MM:SSZ format. Records before this date aren’t replicated. |
lookback_window | No | Number of minutes before the last cursor value to re-fetch on each incremental sync. Defaults to 0. |
num_workers | No | Number of concurrent threads to use during a sync. Valid values are 1 through 40. Defaults to 3. |
slice_step_duration | No | Time window size for each incremental stream slice. Valid values are P1D, P1W, P1M, and P1Y. Defaults to P1M. |
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 1.1.10 | 2026-11-10 | 91752 | Update dependencies |
| 1.1.9 | 2026-11-03 | 90752 | Update dependencies |
| 1.1.8 | 2026-10-27 | 90064 | Update dependencies |
| 1.1.7 | 2026-10-20 | 89453 | Update dependencies |
| 1.1.6 | 2026-10-13 | 88836 | Update dependencies |
| 1.1.5 | 2026-10-06 | 88048 | Update dependencies |
| 1.1.4 | 2026-10-05 | 87049 | Automatically split Alerts time windows that exceed Twilio’s 10,000-result limit instead of failing the sync |
| 1.1.3 | 2026-09-29 | 87367 | Update dependencies |
| 1.1.2 | 2026-09-22 | 86857 | Update dependencies |
| 1.1.1 | 2026-09-15 | 84774 | Update dependencies |
| 1.1.0 | 2026-09-08 | 85748 | Promoting release candidate 1.1.0-rc.1 to a main version. |
| 1.1.0-rc.1 | 2026-08-13 | 84203 | Add voice, messaging, and phone number pricing country streams |
| 1.0.13 | 2026-08-11 | 84128 | Update dependencies |
| 1.0.12 | 2026-07-28 | 83194 | Update to CDK 7.23.8 (fixes AirbyteCustomCodeNotPermittedError for bundled custom components) and remove the temporary Cloud version override |
| 1.0.11 | 2026-07-28 | 1082 | Roll Cloud back to 1.0.9 — 1.0.10 is built on SDM 7.23.7, which breaks bundled custom components |
| 1.0.10 | 2026-07-28 | 83134 | Update dependencies |
| 1.0.9 | 2026-07-21 | 82618 | Update dependencies |
| 1.0.8 | 2026-07-14 | 82053 | Update dependencies |
| 1.0.7 | 2026-07-09 | 80330 | Add Status filter to conferences and conference_participants streams to retrieve conferences in all statuses (init, in-progress, completed) after Twilio’s July 2026 API default change |
| 1.0.6 | 2026-06-30 | 81294 | Update dependencies |
| 1.0.5 | 2026-06-23 | 80703 | Update dependencies |
| 1.0.4 | 2026-06-22 | 80282 | Fix messages and recordings incremental state getting stuck near the start date by aligning cursor_granularity with the second-precision datetime_format. |
| 1.0.3 | 2026-06-16 | 80075 | Update dependencies |
| 1.0.2 | 2026-06-09 | 79553 | Update dependencies |
| 1.0.1 | 2026-06-02 | 79027 | Update dependencies |
| 1.0.0 | 2026-05-21 | 76911 | Migrate services and roles streams from the deprecated Programmable Chat API to the Conversations API. See the migration guide. |
| 0.17.11 | 2026-05-21 | 78322 | Revert concurrency tuning rollout |
| 0.17.10 | 2026-05-12 | 77988 | Improve the Twilio Alerts pagination-limit error message. |
| 0.17.9 | 2026-04-30 | 77593 | Fix usage_records start_date schema format from date-time to date to prevent null primary key in Iceberg destination |
| 0.17.8 | 2026-04-28 | 77453 | Update dependencies |
| 0.17.7 | 2026-04-22 | 72494 | Add configurable slice step duration (default: 1 month) |
| 0.17.6 | 2026-04-21 | 76801 | Update dependencies |
| 0.17.5 | 2026-04-13 | 76276 | Rename “concurrent workers” to “concurrent threads” in connector spec |
| 0.17.4 | 2026-01-22 | 72260 | Update CDK version from 7.0.1 to 7.6.5 |
| 0.17.3 | 2025-11-06 | 68680 | Handle 404 errors gracefully for date ranges with no data |
| 0.17.2 | 2025-10-22 | 68591 | Add suggestedStreams |
| 0.17.1 | 2025-09-15 | 66090 | Update to CDK v7 |
| 0.17.0 | 2025-09-05 | 65955 | Promoting release candidate 0.17.0-rc.2 to a main version. |
| 0.17.0-rc.2 | 2025-09-04 | 65936 | Fix lookback window |
| 0.17.0-rc.1 | 2025-08-25 | 65072 | Migrate to manifest-only |
| 0.16.0 | 2025-08-28 | 65593 | Promoting release candidate 0.16.0-rc.1 to a main version. |
| 0.16.0-rc.1 | 2025-08-25 | 65072 | Migrate incremental streams |
| 0.15.0 | 2025-08-19 | 65085 | Promoting release candidate 0.15.0-rc.1 to a main version. |
| 0.15.0-rc.1 | 2025-08-18 | 64918 | Migrate nested full refresh streams |
| 0.14.0 | 2025-08-18 | 65066 | Promoting release candidate 0.14.0-rc.1 to a main version. |
| 0.14.0-rc.1 | 2025-08-14 | 64880 | Migrated all full refresh streams that have no parent streams |
| 0.13.0 | 2025-08-14 | 64929 | Promoting release candidate 0.13.0-rc.1 to a main version. |
| 0.13.0-rc.1 | 2025-08-12 | 64877 | Update CDK to v6 |
| 0.12.1 | 2025-06-16 | 56258 | Update dependencies |
| 0.12.0 | 2025-06-02 | 49097 | Fix per partition states for nested streams |
| 0.11.17 | 2025-02-23 | 54486 | Update dependencies |
| 0.11.16 | 2025-01-24 | 52089 | Fix typo to fix pagination for TwilioStream class |
| 0.11.15 | 2025-01-19 | 51966 | Update dependencies |
| 0.11.14 | 2024-12-29 | 50803 | Update dependencies |
| 0.11.13 | 2024-11-25 | 43769 | Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64 |
| 0.11.12 | 2024-08-04 | 43132 | Update dependencies |
| 0.11.11 | 2024-07-28 | 42593 | Update dependencies |
| 0.11.10 | 2024-07-21 | 42177 | Update dependencies |
| 0.11.9 | 2024-07-14 | 41845 | Update dependencies |
| 0.11.8 | 2024-07-11 | 41478 | Update dependencies |
| 0.11.7 | 2024-06-27 | 40527 | Update dependencies |
| 0.11.6 | 2024-06-23 | 40030 | Update dependencies |
| 0.11.5 | 2024-06-11 | 39252 | [autopull] Upgrade base image to v1.2.2 |
| 0.11.4 | 2024-05-22 | 38564 | Migrate authenticator to requests_native_auth package |
| 0.11.3 | 2024-05-20 | 38262 | Replace AirbyteLogger with logging.Logger |
| 0.11.2 | 2024-05-07 | 36666 | Updating to 0.80.0 CDK |
| 0.11.1 | 2024-05-07 | 36666 | Schema descriptions |
| 0.11.0 | 2024-03-21 | 36267 | Pin airbyte-cdk version to ^0 |
| 0.10.2 | 2024-02-12 | 35153 | Manage dependencies with Poetry |
| 0.10.1 | 2023-11-27 | 32718 | Base image migration: remove Dockerfile and use the python-connector-base image |
| 0.10.0 | 2023-07-27 | 27323 | Add new stream Step |
| 0.9.0 | 2023-07-13 | 27221 | Add new stream UserConversations with parent Users |
| 0.8.1 | 2023-07-12 | 28216 | Add property channel_metadata to ConversationMessages schema |
| 0.8.0 | 2023-06-27 | 27231 | Add new stream VerifyServices |
| 0.7.0 | 2023-05-23 | 25781 | Add new stream Trunks |
| 0.6.0 | 2023-05-23 | 25783 | Add new stream Roles with parent Services |
| 0.5.0 | 2023-04-13 | 23995 | Add new stream Conversation Participants |
| 0.4.0 | 2023-04-11 | 22875 | Add new stream Conversation Messages |
| 0.3.0 | 2023-04-10 | 22874 | Add new stream Executions with parent Flows |
| 0.2.0 | 2023-03-21 | 24320 | Add Conversations stream |
| 0.1.16 | 2023-03-02 | 22825 | Specified date formatting in specification |
| 0.1.15 | 2023-01-30 | 22025 | Set AvailabilityStrategy for streams explicitly to None |
| 0.1.14 | 2022-11-29 | 19479 | Fix date range slicing |
| 0.1.13 | 2022-10-26 | 18423 | Implement datetime slicing for streams supporting incremental syncs |
| 0.1.11 | 2022-09-30 | 17478 | Add lookback_window parameters |
| 0.1.10 | 2022-09-30 | 17410 | Migrate to per-stream states |
| 0.1.9 | 2022-09-26 | 17134 | Add test data for Message Media and Conferences |
| 0.1.8 | 2022-08-29 | 16110 | Add state checkpoint interval |
| 0.1.7 | 2022-08-29 | 15972 | Shift start date for stream if it exceeds 400 days |
| 0.1.6 | 2022-06-27 | 14000 | Update Records stream schema and align tests with connectors’ best practices |
| 0.1.5 | 2022-06-22 | 13896 | Add lookback window parameters to fetch messages with a rolling window and catch status updates |
| 0.1.4 | 2022-04-22 | 12157 | Use Retry-After header for backoff |
| 0.1.3 | 2022-04-21 | 12183 | Add new subresource on the call stream + declare a valid primary key for conference_participants stream |
| 0.1.2 | 2021-12-27 | 9092 | Correct specification doc URL |
| 0.1.1 | 2021-10-18 | 7034 | Update schemas and transform data types according to the API schema |
| 0.1.0 | 2021-07-03 | 4070 | Native Twilio connector implemented |