Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Grafana

Scalekit connector
Open markdown

The Grafana connector lets your AI agent act in each user's Grafana account. Each user connects their own Grafana access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 36 tools.

Tools
36
What they doRead · write · destructive
28 · 8 · 028 read8 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Grafana connection

    In AgentKit > Connections, create a Grafana connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'grafana'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Grafana:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'grafana_current_user_get',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Grafana credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • grafana_alert_group_listList Grafana Alertmanager alerts grouped the way notification policies group them.Read-only

    List Alert Groups

    List Grafana Alertmanager alerts grouped the way notification policies group them. Returns an array of groups, each with its group labels, receiver and the alerts in it. Use grafana_alert_group_list to see alerts as they are batched into notifications. Use grafana_alert_list for a flat list of alerts.

    Inputs

    activeboolean
    Include active alerts. Defaults to true.default true
    filterarray
    Label matchers to filter alerts, each in Prometheus matcher syntax. Example: ["severity=\"critical\"", "team=~\"api|web\""].
    inhibitedboolean
    Include inhibited alerts. Defaults to true.default true
    receiverstring
    Regular expression matching the contact point (receiver) name to filter alerts by. Example: oncall-.*.
    silencedboolean
    Include silenced alerts. Defaults to true.default true
  • grafana_alert_listList alert instances currently held by Grafana's built-in Alertmanager, filtered by state, labels or contact point.Read-only

    List Alerts

    List alert instances currently held by Grafana's built-in Alertmanager, filtered by state, labels or contact point. Returns an array of alerts with labels, annotations (such as summary), startsAt, endsAt, status (state, silencedBy, inhibitedBy), receivers and generatorURL. Use grafana_alert_list to see what is firing right now. Use grafana_alert_group_list for the same alerts grouped by notification policy, and grafana_alert_rule_status_list for rule-level state including pending rules.

    Inputs

    activeboolean
    Include active alerts. Defaults to true.default true
    filterarray
    Label matchers to filter alerts, each in Prometheus matcher syntax. Example: ["severity=\"critical\"", "team=~\"api|web\""].
    inhibitedboolean
    Include inhibited alerts. Defaults to true.default true
    receiverstring
    Regular expression matching the contact point (receiver) name to filter alerts by. Example: oncall-.*.
    silencedboolean
    Include silenced alerts. Defaults to true.default true
  • grafana_alert_rule_getGet the full definition of one Grafana-managed alert rule by UID.Read-only

    Get Alert Rule

    Get the full definition of one Grafana-managed alert rule by UID. Returns the rule with its title, condition, queries (data), for duration, labels, annotations, folder and rule group, and notification settings. Use grafana_alert_rule_get to read how a rule is built. Use grafana_alert_rule_status_list to find rule UIDs and see their current state.

    Inputs

    rule_uidstringrequired
    UID of the alert rule, from grafana_alert_rule_status_list or the rule's URL in Grafana. Example: ddbhspyaw3k00e.
  • grafana_alert_rule_status_listList Grafana-managed alert rules with their current evaluation state, health and alert instances, grouped by folder and rule group.Read-only

    List Alert Rule Statuses

    List Grafana-managed alert rules with their current evaluation state, health and alert instances, grouped by folder and rule group. Returns data.groups, each with its rules (name, uid, state, health, lastEvaluation, labels, annotations and alerts), plus totals and groupNextToken for paging. Use grafana_alert_rule_status_list to see which rules are firing, pending or erroring. Use grafana_alert_rule_get for one rule's full definition and grafana_alert_list for the Alertmanager's view of firing alerts.

    Inputs

    dashboard_uidstring
    Only return rules linked to this dashboard UID. Example: cIBgcSjkk.
    folder_uidstring
    Only return rules in this folder UID. Example: nErXDvCkzz.
    group_limitinteger
    Maximum number of rule groups to return in this page. Example: 50.
    group_next_tokenstring
    Pagination token from the previous response's groupNextToken. Example: eyJmIjoibkVyWER2Q2t6eiJ9.
    healtharray
    Only return rules with this health: ok, error or nodata. Example: ["error"].
    limit_alertsinteger
    Maximum number of alert instances returned per rule. Example: 10.
    panel_idinteger
    Only return rules linked to this panel ID; requires Dashboard UID. Example: 2.
    receiver_namestring
    Only return rules that notify this contact point. Example: oncall-email.
    rule_grouparray
    Only return rules in these rule groups. Example: ["api-alerts"].
    rule_name_searchstring
    Case-insensitive substring to match against rule titles. Example: latency.
    rule_typestring
    Only return alerting or recording rules.one of alertingrecording
    statearray
    Only return rules in these states: normal (or inactive), pending, alerting (or firing), nodata, error, recovering. Example: ["firing", "pending"].
  • grafana_annotation_getGet one Grafana annotation by ID.Read-only

    Get Annotation

    Get one Grafana annotation by ID. Returns the annotation's id, dashboardUID, panelId, time, timeEnd, text, tags and author. Use grafana_annotation_get to read a single annotation. Use grafana_annotation_list to search annotations by time, dashboard or tag.

    Inputs

    annotation_idstringrequired
    ID of the annotation to retrieve, from grafana_annotation_list. Example: 1234.
  • grafana_annotation_listList Grafana annotations, filtered by time range, dashboard, panel, alert rule, user, type or tags.Read-only

    List Annotations

    List Grafana annotations, filtered by time range, dashboard, panel, alert rule, user, type or tags. Returns an array of annotations with id, dashboardUID, panelId, time, timeEnd, text, tags and the user who created them. Use grafana_annotation_list to find deployment markers, incidents or alert events in a time window. Use grafana_annotation_get for one annotation and grafana_annotation_tag_list to discover tags.

    Inputs

    alert_uidstring
    Only return annotations created by the alert rule with this UID. Example: ddbhspyaw3k00e.
    dashboard_uidstring
    Only return annotations on this dashboard UID. Example: cIBgcSjkk.
    frominteger
    Only return annotations after this time, in epoch milliseconds. Example: 1735689600000.
    limitinteger
    Maximum number of annotations to return. Example: 100.
    match_anyboolean
    If true, match annotations with any of the tags; if false, they must have all of them.
    panel_idinteger
    Only return annotations on this panel ID (use with Dashboard UID). Example: 2.
    tagsarray
    Only return organization annotations with these tags. Example: ["deploy", "api"].
    tointeger
    Only return annotations before this time, in epoch milliseconds. Example: 1735776000000.
    typestring
    Return only alert annotations (alert) or only user-created annotations (annotation).one of alertannotation
    user_uidstring
    Only return annotations created by the user with this UID. Example: fdbhrt9dgknpcb.
  • grafana_annotation_tag_listList the tags used on Grafana annotations, with how often each is used, optionally filtered by text.Read-only

    List Annotation Tags

    List the tags used on Grafana annotations, with how often each is used, optionally filtered by text. Returns result.tags, an array of tag and count pairs. Use grafana_annotation_tag_list to discover tags before filtering grafana_annotation_list.

    Inputs

    limitinteger
    Maximum number of tags to return. Defaults to 100.
    tagstring
    Text to filter tag names by. Example: deploy.
  • grafana_current_user_getGet the Grafana user or service account that the connection's token authenticates as.Read-only

    Get Current User

    Get the Grafana user or service account that the connection's token authenticates as. Returns id, uid, login, email, name, orgId, isGrafanaAdmin and theme. Use grafana_current_user_get to check which identity and organization the connection uses. Use grafana_org_get for organization details.

    Inputs

    This tool takes no inputs.

All 29 in Monitoring