> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atako.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Grafana

> Connect Grafana to your Atako agents — 11 read and 3 write actions.

Let your agents work with your Grafana instance: search dashboards and folders, read a dashboard, list data sources, read and add annotations, review alert rules and firing alerts, create folders and silences, and list users and teams.

## Connection

* **Authentication**: API key (Grafana service account token).
* **Required settings**:
  * **Grafana instance domain** — The domain of your Grafana, without https\:// nor path (e.g. mystack.grafana.net or grafana.example.com). Grafana must be served over HTTPS at the root of this domain.

<Note>
  In Grafana (organization administrator required): Administration → Users and access → Service accounts → Add service account, enter a Display name, choose its role and click Create. Then open that service account → Add service account token → enter a name (optionally Set expiration date) → Generate token, and copy the token (it is shown only once). Role: Viewer covers searching and reading dashboards, folders, annotations and alerts; Editor adds creating folders, annotations and silences; listing data sources, organization users and teams requires Admin. On Grafana Cloud, also note the instance ID (grafana.com → your stack → Details of the Grafana instance): agents need it to read dashboards and folders.

  See [Grafana's documentation](https://grafana.com/docs/grafana/latest/administration/service-accounts/).
</Note>

## Read actions (11)

| Action | Description |
| - | - |
| `get_alert_rule` | Read the full definition of one alert rule by uid (from list\_alert\_rules): its group, folder, evaluation interval, queries, condition, for, labels, annotations and notification settings, in the provisioning export format (JSON). |
| `get_current_org` | Get the Grafana organization of the service account (id, name). On a self-hosted Grafana the id gives the namespace of the dashboard and folder actions: 1 → "default", otherwise "org-\<id>". |
| `get_dashboard` | Read a dashboard by uid (from search): metadata (name = uid, folder in annotations\["grafana.app/folder"]) and spec (title, panels with their queries, templating variables, time range). namespace: "default" on a self-hosted Grafana (organization 1), "org-\<id>" for another organization (id from get\_current\_org), "stacks-\<instance id>" on Grafana Cloud (grafana.com → your stack → Details of the Grafana instance; ask the user if unknown). A wrong namespace answers 403 "invalid namespace". |
| `list_alert_rules` | List Grafana-managed alert and recording rules with their state, by rule group: data.groups\[].rules\[] (uid, name, query, labels, annotations, state, health, lastError, active alerts). folder\_uid / dashboard\_uid: optional uids; rule\_name\_contains / group\_name\_contains: optional case-insensitive substrings; rule\_type: optional "alerting" or "recording"; state: optional array of "normal", "pending", "alerting", "nodata", "error", "recovering"; health: optional array of "ok", "error", "nodata"; limit\_alerts: optional integer, alert instances per rule; group\_limit: optional integer; group\_next\_token: optional token from data.groupNextToken of the previous page. |
| `list_alerts` | List the alert instances of the Grafana Alertmanager (labels, annotations, startsAt, status.state active / suppressed, status.silencedBy, fingerprint). active / silenced / inhibited: optional booleans to include those alerts (default true); filter: optional array of label matchers, e.g. alertname="HighCPU" or severity=\~"crit.\*"; receiver: optional regular expression on the contact point name. |
| `list_annotations` | List annotations, newest first (id, time and timeEnd in epoch milliseconds, text, tags, dashboardUID, panelId, alertId). from / to: optional epoch milliseconds; dashboardUID: optional dashboard uid; panelId: optional integer; alertUID: optional alert rule uid; userUID: optional author uid; type: optional "annotation" or "alert"; tags: optional array of tags (organization annotations); matchAny: optional boolean, true = any of the tags; limit: optional integer 1-5000. |
| `list_datasources` | List the data sources of the organization (uid, name, type, url, database, isDefault, jsonData settings). Passwords and encrypted settings are removed. Needs datasources:read (Admin role by default). |
| `list_folders` | List the folders the service account can see (items\[].metadata.name = folder uid, metadata.annotations\["grafana.app/folder"] = parent uid, spec.title). limit: optional integer 1-1000; continue: optional token from metadata.continue of the previous page. namespace: "default" on a self-hosted Grafana (organization 1), "org-\<id>" for another organization (id from get\_current\_org), "stacks-\<instance id>" on Grafana Cloud (grafana.com → your stack → Details of the Grafana instance; ask the user if unknown). A wrong namespace answers 403 "invalid namespace". |
| `list_org_users` | List the users of the organization (userId, uid, login, email, name, role, lastSeenAt). query: optional string matched against login, email and name; limit: optional integer 1-1000. Needs org.users:read (Admin role by default). |
| `search` | Search dashboards and folders the service account can see. Returns uid, title, type (dash-db or dash-folder), url, tags, folderUid, folderTitle. query: optional title substring; tag: optional array of tags (all must match); type: optional "dash-db" or "dash-folder"; dashboardUIDs / folderUIDs: optional arrays of uids (folderUIDs restricts to those folders); starred: optional boolean; sort: optional "alpha-asc" or "alpha-desc"; limit: optional integer 1-5000; page: optional integer from 1. |
| `search_teams` | Search the teams of the organization: \{ totalCount, teams: \[\{ id, uid, name, email, memberCount }], page, perPage }. query: optional substring of the team name; name: optional exact team name; page: optional integer from 1; perpage: optional integer 1-1000. Needs teams:read (Admin role by default, or team administrator). |

## Write actions (3)

| Action | Description |
| - | - |
| `create_annotation` | Add an annotation. Arguments: text: string (required, the annotation text); dashboardUID: optional dashboard uid string (omitted = organization annotation, visible through the Grafana annotations data source); panelId: optional integer panel id of that dashboard; time: optional integer, epoch milliseconds (default now); timeEnd: optional integer, epoch milliseconds, makes it a region; tags: optional array of strings. Needs the Editor role (annotations:create). Returns \{ id, message }. |
| `create_folder` | Create a folder. Arguments: namespace: string (see below); title: string (1-255 characters, required); description: optional string; parent\_uid: optional parent folder uid string (from list\_folders or search; needs nested folders enabled), omitted = root level; uid: optional uid string for the new folder (letters, digits, - or \_, max 40), omitted = generated by Grafana. Needs the Editor role (folders:create). Returns the folder; metadata.name is its uid. namespace: "default" on a self-hosted Grafana (organization 1), "org-\<id>" for another organization (id from get\_current\_org), "stacks-\<instance id>" on Grafana Cloud (grafana.com → your stack → Details of the Grafana instance; ask the user if unknown). A wrong namespace answers 403 "invalid namespace". |
| `create_silence` | Silence the Grafana alerts matching all the given matchers for a time window. Arguments: matchers: array of 1-20 objects \{ name: label name string, value: string, isRegex: boolean (required), isEqual: optional boolean, false = "not equal" }; startsAt / endsAt: ISO 8601 date-time strings with time zone (e.g. "2026-09-26T14:00:00Z"), endsAt after startsAt; createdBy: string, who asks for it; comment: string, why. Needs the Editor role (alert.silences:create). Returns \{ silenceID }. |

## Permissions

Every action above must be explicitly granted to an agent before it can be used. See [Permissions](/integrations/permissions) for the grant model and [Security](/integrations/security) for how credentials are protected.

***

*Last reviewed against the provider API: September 2026.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.