Grafana

Read access to a Grafana instance, cloud or self-hosted, via the Grafana HTTP API. Reads alert instances that are currently firing, the alert rule definitions behind them, dashboards and folders, configured data sources, and metric queries against a Prometheus-compatible data source.

The tool is read-only. It creates, updates, and deletes nothing.

Actions

Alerts vs alert rules

These are different things and the distinction matters when investigating an incident. list_alerts returns alert instances: what is actually firing right now, with labels, annotations, and start times. list_alert_rules returns the definitions: the queries and thresholds that decide when an instance fires. Start from list_alerts for "what is broken", and get_alert_rule for "why did this fire".

filter on list_alerts takes Alertmanager label matchers, one per entry:

{
  "action": "list_alerts",
  "filter": ["severity=critical", "namespace=rpc"]
}

Querying metrics

query_metrics targets a Prometheus-compatible data source. Call list_datasources first to get the datasource_uid; expr is PromQL, and from and to accept Grafana relative times such as now-6h or epoch milliseconds.

{
  "action": "query_metrics",
  "datasource_uid": "abc123",
  "expr": "sum(rate(http_requests_total[5m])) by (status)",
  "from": "now-6h",
  "to": "now"
}

Incremental reads

fetch_since is the only genuine time-ranged surface Grafana offers. It reads /api/annotations, which is where Grafana records alert state transitions, so it answers "what happened between these two instants" rather than "what is true now".

{ "action": "fetch_since", "from_epoch_ms": 1754000000000, "kind": "alert", "limit": 100 }

Bounds are epoch milliseconds. Persist the newest annotation time you processed and pass it back as from_epoch_ms. Omitting to_epoch_ms reads up to the present; supplying one that does not advance past from_epoch_ms is rejected rather than silently returning an empty window.

Alert rules, dashboards, and data sources carry no cursor of any kind. For those, a full read is the only option.

Target hostname

The tool works against Grafana Cloud and self-hosted Grafana. The hostname is pinned per installation, in two places that must agree.

1. The capabilities file, edited before install. Replace YOUR_GRAFANA_HOST in both allowlist.host and the credential's host_patterns:

"host": "grafana.example.com"

This is the security boundary. It is enforced host-side, outside the sandbox, and a request to any other host is refused before it leaves the runtime. That is why it is one concrete host per install rather than a wildcard.

2. The workspace file grafana/host, which is what the tool reads to build request URLs. Bare hostname, no scheme, no path; append a port if your instance uses one:

grafana.example.com:3000

Self-hosted instances must be reachable over HTTPS with a certificate the IronClaw host trusts. For Grafana Cloud, use your stack hostname, myorg.grafana.net.

Auth

Create a service account in Grafana under Administration > Users and access > Service accounts, give it the Viewer role, and add a token. Viewer covers every action here; nothing in this tool needs write permission.

export GRAFANA_SERVICE_ACCOUNT_TOKEN=<service account token>

The host injects the token as an Authorization: Bearer header on requests to *.grafana.net. The token is never visible to the tool.

Limits

• One host per installation. The allowlist is pinned to a single hostname, so an agent that needs to read two Grafana instances needs two installs.
• Assumes Grafana is served at the root of its host. An instance behind a sub-path such as example.com/grafana/ needs the path_prefix in the capabilities file widened to match.
• search_dashboards caps at 5000 results per call; page with limit and page.
• get_dashboard returns the complete dashboard JSON, which can be large for dashboards with many panels.
• query_metrics sends a single PromQL query per call and assumes a Prometheus-compatible data source. Non-Prometheus data sources take different query fields and are not supported.
• /api/dashboards/uid/{uid} is the legacy dashboard route. Grafana 13 introduces /apis/dashboard.grafana.app/ alongside it and keeps the legacy route operative.