Vantage only reads data from the Usage Records API and never performs any write actions to your account. For least-privilege access, create a Restricted API key with only the
/twilio/billing/usage/read permission. This permission grants read access to the Usage Records endpoints and nothing else.Create the API key in Twilio’s United States (US1) region, even if your workloads run in another region. Twilio provides account-level usage records for all regions through US1 only, and Restricted API keys are available only in US1.Standard API keys also work with Vantage, but they have access to all Twilio API resources, except for API key and Account resources. Vantage recommends Restricted API keys instead.Connect Your Twilio Account
Prerequisites
- You must have a Vantage Organization Owner or Integration Owner role to add or remove this integration. See the Role-Based Access Control documentation for details.
- You must have an Administrator or Developer role in Twilio to create an API key.
- Create a free Vantage account, then follow the steps below to integrate Twilio costs.
Twilio Account Limitations
If you create an API key in your top-level main account, Vantage includes all cost data incurred in any subaccounts that roll up to the top-level main account. When you view usage on a report, it will appear as if the costs were incurred in the parent account. If you want to specifically capture the subaccount, you can create an API key specifically for that subaccount, and connect the subaccount as its own integration.Ideally, you could provide a single API key for an Organization, and Vantage could capture subaccount-level granularity, but this is unfortunately a limitation of Twilio’s APIs. Contact your Twilio CSM to ask for enhancements to the Billing and Usage APIs.
Twilio Usage Categories
Vantage ingests a default set of Twilio usage categories. The Usage Records API returns some categories that are totals of other, more specific categories. To avoid duplicate costs, Vantage does not ingest every category by default. For example,recordingstorage (recording storage) and calls-inbound-tollfree are not included by default.
To see which categories Vantage has ingested for your account, open a Twilio Cost Report and group by Category.
If a charge appears on your Twilio invoice but not in Vantage, contact support@vantage.sh with the name of the Twilio usage category. Support can add categories to, or exclude categories from, a specific Twilio integration and then re-import your data.
If your organization restricts access to the provider by IP address, add the following Vantage IP addresses to your provider’s allowlist:
54.87.66.453.95.43.13354.162.3.7244.199.143.633.218.103.23
Create the Connection
Follow the steps below to create a connection with Twilio.Step 1 - Create a Twilio API Key
1
Log in to the Twilio console. Ensure you are logged in to your main Twilio account. (See the section above for information on limitations between main and subaccounts.)
2
On the Account Dashboard, your Account SID is displayed in the Account Info section. Copy the Account SID to use in the next section when connecting to Vantage.

Click to view example image
Click to view example image

3
At the top of the console, click Admin > Account management.

Click to view example image
Click to view example image

4
On the left navigation menu, under Keys & Credentials, click API keys & tokens.
5
Click Create API key.

Click to view example image
Click to view example image

6
On the Create new API key page, add the following information:
- Enter a Friendly name, like vantage.
- For Region, select United States (US1).
- For Key type, select Restricted.
- Under Permissions, expand the Billing section and select Read for usage.
7
At the bottom, click Create.
8
Copy the SID (i.e., the string identifier for the API key) and Secret.
Step 2 - Add Credentials to Vantage
1
From the top navigation in Vantage, click Settings.
2
On the left navigation, select Integrations > Twilio.
3
The Twilio integrations page is displayed. Ensure you are on the Connect tab.
4
At the bottom of the page, click Add API Key:
For example, the account name here would be “My first Twilio account.”
- For API Key SID, paste the API key SID you just obtained in the last step.
- For API Secret, paste the API secret you just obtained in the last step.
- For Account SID, paste the Account SID you obtained in step 2 of the last section.
- For Account Name, add a name that will be used for the Billing Account filter in Cost Reports. It’s recommended that you use your account name as displayed in the Twilio console (see example image below). This name must be unique across all Twilio integrations in Vantage.
Click to view example image
Click to view example image
For example, the account name here would be “My first Twilio account.”- Optionally, add a Description to identify this integration.
5
Click Connect Account.
As soon as costs are processed, they will be available on your All Resources Cost Report. If you decide to remove your Twilio integration from Vantage, all costs associated with your Twilio API token will be removed from the Vantage console.
Next Steps - Manage Workspace Access
Once the import is complete and the integration status changes to Stable, you can select which workspaces this integration is associated with. See the Workspaces documentation for information.Update the API Key
If your Twilio API key is rotated or revoked, or you want to replace a Standard API key with a Restricted one, you can update the key on the existing integration. The Account SID, account name, imported costs, and workspace assignments stay the same.1
Create a new API key in the same Twilio account. Follow the key creation steps in Create the Connection. Use a Restricted key in the United States (US1) region, with Read selected for usage under Billing.
2
From the top navigation in Vantage, click Settings.
3
On the left navigation, select Integrations > Twilio. On the Manage tab, open the integration.
4
On the Manage Connection page, scroll to Update API Key. Paste the new key’s SID into API Key SID and the secret into API Secret, then click Update API Key.
Data Refresh
See the provider data refresh documentation for information on when data for each provider refreshes in Vantage.Twilio Reporting Dimensions
On Twilio Cost Reports, you can filter across several dimensions:- Billing Account (the name of Twilio account entered at time of integration)
- Account (account ID of the account your API key is created in)
- Service (e.g., SMS & MMS)
- Charge Type (e.g., Usage)
- Category (e.g., sms-messages-carrierfees). See Twilio Usage Categories for information on which categories Vantage ingests.
- Tags (Virtual Tags created in Vantage)