--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/data-destinations/destination/grafana-cloud#article headline: Grafana Cloud destination description: Learn how to send event data to Grafana Cloud Loki for log aggregation, search, and alerting. url: https://www.twilio.com/docs/data-destinations/destination/grafana-cloud inLanguage: en dateModified: 2026-11-04T17:24:28.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Grafana Cloud 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). [Grafana Cloud](https://grafana.com/products/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. ### Destination overview * **Category**: Analytics, Performance monitoring * **Release status**: Beta * **Authentication**: Basic authentication * **Regional availability**: US1 ## 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 You can send all [event types](/docs/events/event-types-overview) supported by Event Streams to Grafana Cloud. This destination has no user-identifier restriction. ## Get started ### Prerequisites 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:write` scope, 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. ## 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 Grafana Cloud destination in the Twilio Console: 1. From your Grafana Cloud 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 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](/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 | | ------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. ```json title="Example request body" { "destinationType": "grafana-cloud", "name": "My Grafana Cloud destination", "config": { "credentials": { "credentialType": "BASIC", "apiToken": "API_TOKEN", "userId": "USER_ID" }, "lokiUrl": "LOKI_URL" } } ``` ## Destination settings 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. ## Default mappings | Field | Grafana Cloud field | | ------------- | -------------------------------------------- | | Event type | Stream label `type` | | Event time | Log entry timestamp (Unix epoch nanoseconds) | | Event payload | Log line (full event, JSON) | ## Verification and troubleshooting 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. ### Common errors | 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](/docs/usage/troubleshooting/debugging-your-application) | Confirm your stack's Loki URL from Grafana Cloud stack details | | Grafana Cloud rate-limiting your account | Delivery errors reported in the [Debugger](/docs/usage/troubleshooting/debugging-your-application) | 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](/docs/usage/troubleshooting/debugging-your-application); 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](/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)