Twilio
This page contains the setup guide and reference information for the Twilio source connector.
Prerequisites
- A Twilio Account SID and Auth Token. Find both in the Twilio Console.
- Use credentials for the Twilio account whose resources you want to sync. Main account credentials can access main account resources and v2010 REST API resources for subaccounts. Subaccount credentials can access only that subaccount.
- Resources on product-specific subdomains (Studio, Conversations, Verify) must be accessed with credentials for the account that owns those resources.
For more information, see the Twilio API authentication documentation.
Setup guide
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 and 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). - Optionally, configure the following fields:
- Lookback window: The number of minutes before the last cursor value to re-fetch on each incremental sync. Use this to catch late-arriving records. Defaults to
0. - Number of concurrent threads: The number of worker threads used during a sync. Defaults to
3. Maximum is40. - Slice Step Duration: The time window size used for each slice of an incremental stream. See Tuning the slice step duration. Defaults to 1 Month (
P1M).
- Lookback window: The number of minutes before the last cursor value to re-fetch on each incremental sync. Use this to catch late-arriving records. Defaults to
- Click Set up source.
For Airbyte Open Source:
- Navigate to the Airbyte Open Source dashboard.
- Set a name for your source.
- Enter your Account ID (Twilio Account SID).
- Enter your Auth Token.
- Enter a Replication Start Date in the format
YYYY-MM-DDTHH:MM:SSZ. - Optionally, set the 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 the following 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, then makes one additional request per country to fetch that country's prices, so a sync of these streams makes more API requests than there are supported countries. Prices are specific to the account you authenticate with: base_price is Twilio's list price and current_price includes any volume or custom discounts on your account. Each record is keyed by iso_country.
Upgrading 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 and clear data for those streams after upgrading. For the full list of schema changes and migration steps, see the migration guide.
Limitations
400-day data availability window
The messages, recordings, and message_media streams only sync data from the last 400 days, 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 (approximately 400 days). If your Replication Start Date is more than 400 days in the past, those streams begin from 400 days ago. Other streams respect the configured start date without this cap.
To retrieve records older than 400 days, use Twilio's Bulk Export API outside of this connector.
Conference participants cover only active conferences
The conference_participants stream returns participants only for conferences that are still active (init or in-progress). Twilio's Participants subresource manages only active participants of in-progress conferences, so participants of a conference that has already completed aren't returned and can't be synced. To capture participant activity for the full lifetime of a conference, subscribe to Twilio conference status callbacks in your own application and store the events as participants join and leave.
The conferences stream itself isn't affected by this limitation and syncs conferences in all statuses (init, in-progress, and completed).
Performance considerations
The Twilio connector gracefully handles rate limits using the Retry-After header with an exponential backoff 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 extra API traffic. If syncs are repeatedly rate limited, reduce the thread count. 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. When a time window contains more than 10,000 Alert records, the connector splits the window in half and reads each half, repeating up to 10 times. Twilio rejects a window only after the connector has read its first 10,000 records, so each split 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. Because splitting stops after 10 halvings, the smallest window depends on Slice Step Duration: 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 is already 1 Day, deselect the alerts stream.
Tuning the slice step duration
Incremental streams page the Twilio API in fixed-size time windows between the replication start date and now. The Slice Step Duration option controls the size of those windows and lets you trade request count against the amount of data each request returns.
| 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 the number of API requests and are more likely to be rate limited, but they reduce the amount of data Twilio must return per request. Larger windows reduce request count but can time out on busy accounts. If syncs of the calls, messages, recordings, message_media, conference_participants, usage_records, or alerts streams fail with timeouts, lower the slice step duration.
IP allow list
If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.
Reference
This connector uses REST APIs, including 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. |
Reference
Config fields reference
Changelog
Expand to review
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 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 |