> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Arvo-AI/aurora/llms.txt
> Use this file to discover all available pages before exploring further.

# Grafana Integration

> Connect Grafana Cloud or self-hosted Grafana to Aurora for alert management and observability insights

Integrate Aurora with Grafana to receive alerts, manage incidents, and perform AI-driven root cause analysis on your monitoring data.

## Authentication

Grafana uses **API Token** (Bearer token) authentication.

### Prerequisites

* Grafana Cloud account or self-hosted Grafana instance
* Permissions to create service accounts (Grafana Cloud) or API tokens (self-hosted)

### Setup Steps

<Steps>
  <Step title="Create Service Account (Grafana Cloud)">
    1. Go to [Grafana Cloud](https://grafana.com/) and select your stack
    2. Navigate to **Administration** > **Service accounts**
    3. Click **Add service account**
    4. Name: `Aurora`, Role: `Viewer`
    5. Click **Add service account token**
    6. Copy the generated token (you won't see it again)
  </Step>

  <Step title="Create API Token (Self-Hosted)">
    For self-hosted Grafana:

    1. Go to **Configuration** > **API Keys**
    2. Click **Add API key**
    3. Name: `Aurora`, Role: `Viewer`
    4. Copy the generated token
  </Step>

  <Step title="Connect to Aurora">
    1. In Aurora, navigate to **Integrations** > **Grafana**
    2. Enter your Grafana base URL (e.g., `https://your-stack.grafana.net`)
    3. Paste your API token
    4. Click **Connect**
  </Step>
</Steps>

## Configuration

No environment variables are required. API tokens are entered through the Aurora UI.

### Self-Hosted Grafana

For self-hosted instances, provide your Grafana URL during connection:

```
https://grafana.yourcompany.com
```

The URL will be automatically normalized (protocol added if missing, trailing slashes removed).

## Webhook Setup (Optional)

Receive real-time alerts from Grafana Alerting:

<Steps>
  <Step title="Get Webhook URL">
    In Aurora's Grafana integration page, copy your unique webhook URL:

    ```
    https://your-aurora-domain/grafana/alerts/webhook/{user_id}
    ```
  </Step>

  <Step title="Create Contact Point">
    1. In Grafana, go to **Alerting** > **Contact points**
    2. Click **+ Add contact point**
    3. Name: `Aurora`
    4. Type: `Webhook`
    5. URL: Paste your Aurora webhook URL
    6. Click **Test** to verify connectivity
    7. Save the contact point
  </Step>

  <Step title="Configure Notification Policy">
    1. Go to **Alerting** > **Notification policies**
    2. Edit the default policy or create a new one
    3. Add the Aurora contact point to receive alerts
    4. Save the policy
  </Step>
</Steps>

### Development with ngrok

For local development:

```bash .env theme={null}
NGROK_URL=https://your-ngrok-url.ngrok-free.app
```

Start ngrok:

```bash theme={null}
ngrok http 5080
```

## What Aurora Can Query

Once connected, Aurora can:

### Organization Info

* Retrieve organization details
* Verify connection status
* Access user profile information

**API Endpoint:** `GET /grafana/status`

**Response:**

```json theme={null}
{
  "connected": true,
  "org": {
    "id": 1,
    "name": "Your Organization"
  },
  "user": {
    "email": "service-account@example.com",
    "name": "Aurora"
  },
  "baseUrl": "https://your-stack.grafana.net"
}
```

### Webhook Alerts

* Receive real-time alerts from Grafana
* Auto-create incidents from firing alerts
* Track alert state transitions (firing, resolved)
* Correlate related alerts
* Generate AI-powered root cause analysis

**Ingested Data:**

* Alert UID and title
* Alert state (alerting, resolved, no\_data)
* Rule name and URL
* Dashboard and panel URLs
* Labels and annotations
* Alert values and evaluation info

**API Endpoint:** `GET /grafana/alerts`

**Parameters:**

* `limit` - Number of alerts (default: 50)
* `offset` - Pagination offset (default: 0)
* `state` - Filter by state (alerting, resolved, no\_data)

**Response:**

```json theme={null}
{
  "alerts": [
    {
      "id": 123,
      "alertUid": "abc123",
      "title": "High CPU Usage",
      "state": "alerting",
      "ruleName": "CPU Alert",
      "ruleUrl": "https://grafana.example.com/...",
      "dashboardUrl": "https://grafana.example.com/d/...",
      "panelUrl": "https://grafana.example.com/d/.../...",
      "receivedAt": "2026-03-03T10:30:00Z",
      "payload": {...}
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}
```

## Troubleshooting

**Connection Failed**

* Verify API token is valid and not expired
* Check base URL is correct and accessible
* Ensure service account has at least `Viewer` role
* For self-hosted: verify Aurora can reach your Grafana instance

**Webhook Not Receiving Alerts**

* Verify `NGROK_URL` is set correctly (for local development)
* Ensure ngrok tunnel is running
* Check contact point is configured with correct webhook URL
* Send a test notification from Grafana contact point settings
* Verify notification policy routes alerts to Aurora contact point

**Invalid Base URL Error**

* Use format: `https://your-stack.grafana.net`
* Do not include `/api` or other paths
* Ensure URL uses HTTPS (HTTP will be auto-upgraded)

## API Reference

**Base Path:** `/grafana`

| Method | Endpoint                    | Description               |
| ------ | --------------------------- | ------------------------- |
| POST   | `/connect`                  | Connect Grafana account   |
| GET    | `/status`                   | Check connection status   |
| DELETE | `/disconnect`               | Remove Grafana connection |
| GET    | `/alerts`                   | List webhook alerts       |
| POST   | `/alerts/webhook/{user_id}` | Receive webhooks          |
| GET    | `/alerts/webhook-url`       | Get webhook URL           |

For detailed information about Grafana APIs, see:

* [Grafana HTTP API](https://grafana.com/docs/grafana/latest/developers/http_api/)
* [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/)