Grafana Cloud destination
Beta
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.
Grafana Cloud provides hosted log aggregation, search, and alerting built on Grafana Loki, letting you turn Twilio events into searchable log streams for real-time visibility. This destination supports only the hosted Grafana Cloud Loki endpoint. A self-hosted Grafana or Loki deployment on a private network isn't supported.
- Category: Analytics, Performance monitoring
- Release status: Beta
- Authentication: Basic authentication
- Regional availability: US1
Get early access to native destinations for data warehouses, observability tools, and event pipelines.
You can send all event types supported by Event Streams to Grafana Cloud. This destination has no user-identifier restriction.
Before you set up a Grafana Cloud destination, make sure you have:
- A Grafana Cloud account with a Loki-enabled stack.
- Your Grafana Cloud Instance ID (Loki tenant ID), found in your Grafana Cloud stack details, in the Loki section.
- A Grafana Cloud Access Policy Token with the
logs:writescope, created under Access Policies in your Grafana Cloud account. - Your stack's Loki URL (region-specific, for example,
https://logs-prod-us-central1.grafana.net), also found in your stack details.
Info
See Set up a destination for the full UI and Destinations API setup flow common to every destination type.
To create a Grafana Cloud destination in the Twilio Console:
- From your Grafana Cloud account, gather the settings listed in Destination settings.
- In the Twilio Console, go to Data > Data Destinations > Destinations > Add destination subscription.
- Complete the Add destination subscription wizard.
To create a Grafana Cloud destination through the Destinations API, send a POST request to the Destinations endpoint and set destinationType to grafana-cloud. For authentication and the other request body fields, see Create a destination.
POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"
Set the config object in the request body as follows:
| Name | Type | Description |
|---|---|---|
credentials.credentialType (Required) | string | Set to BASIC. |
credentials.apiToken (Required) | string | The Grafana Cloud access policy token that authenticates requests to Loki. |
credentials.userId (Required) | string | Your Grafana Cloud Loki instance ID (log tenant ID). Twilio uses it as the HTTP Basic authentication username. |
lokiUrl (Required) | string | Your Grafana Cloud Loki base URL, for example https://logs-prod-us-central1.grafana.net. The URL is region-specific and has no trailing slash. Twilio appends the push path automatically. |
The following example shows a request body. Replace the uppercase placeholder values with your own.
1{2"destinationType": "grafana-cloud",3"name": "My Grafana Cloud destination",4"config": {5"credentials": {6"credentialType": "BASIC",7"apiToken": "API_TOKEN",8"userId": "USER_ID"9},10"lokiUrl": "LOKI_URL"11}12}
Use grafana-cloud as the destinationType.
| Field | Description | Required | Default or choices |
|---|---|---|---|
| Instance ID | Your Grafana Cloud Loki instance ID (log tenant ID), used as the HTTP Basic Auth username. Found in your Grafana Cloud stack details, Loki section. | Yes | None |
| Access Policy Token | Your Grafana Cloud access policy token, used as the HTTP Basic Auth password. Needs the logs:write scope. Sensitive: entered once and stored encrypted. | Yes | None |
| Loki URL | Your Grafana Cloud Loki base URL (region-specific, for example, https://logs-prod-us-central1.grafana.net). No trailing slash. | Yes | None |
Twilio authenticates to Grafana Cloud Loki by using HTTP Basic Auth, with your Instance ID as the username and your Access Policy Token as the password. Twilio stores these credentials encrypted, and they never appear in event payloads.
| Field | Grafana Cloud field |
|---|---|
| Event type | Stream label type |
| Event time | Log entry timestamp (Unix epoch nanoseconds) |
| Event payload | Log line (full event, JSON) |
When you save a Grafana Cloud destination, Twilio validates your Instance ID and Access Policy Token with a test write to Grafana Cloud Loki. This validation write ingests no data, so it doesn't appear in your logs.
Twilio doesn't currently offer a way to manually trigger a test event for this destination, from either the Console or the CLI. To confirm delivery works, wait for a real event of a subscribed type to occur.
| Cause | What you'll see | Fix |
|---|---|---|
| Invalid Instance ID or Access Policy Token | Validation fails with an auth error | Re-check your credentials in Grafana Cloud and update the destination |
Access Policy Token missing logs:write scope | Validation fails with an auth error | Create or update the token to include logs:write |
| Wrong or unreachable Loki URL | Validation fails, or delivery errors reported in the Debugger | Confirm your stack's Loki URL from Grafana Cloud stack details |
| Grafana Cloud rate-limiting your account | Delivery errors reported in the Debugger | Reduce volume or ask Grafana Support to raise your ingestion rate limit |
Grafana Cloud returns a custom 260 status (tenant ingestion blocked) | Delivery errors reported in the Debugger; not retried | This is a permanent, account-level block. Contact Grafana Support to turn ingestion back on for your tenant |
If Twilio can't deliver events to your destination, Twilio sends an error notification to the Debugger (available in US1 region only). If Twilio continues to encounter delivery errors, Twilio notifies you every 20 minutes after the initial error.