How to connect Grafana Cloud MCP with Codex

Add a note (userNote activity) to an existing incident's timeline using its ID. The note body can include URLs which will be attached as context. Use this to add context to an incident.

Read the agent catalog of Grafana Agent Observability (the grafana-agento11y-app plugin): which agents send telemetry, what their system prompts and tools are, how their prompt versions evolved, and how each version scored. The catalog is derived from ingested telemetry, not from a registration step: an agent exists here once its generations have been seen. It answers "what is this agent", not "what did it do". Operations: - 'list': agents in this tenant, newest activity first. Each row carries the latest effective version, first and latest seen times, generation and version counts, tool count, a system prompt prefix, and token_estimate. Paginated via limit and cursor - 'get': one agent version in full: the complete system prompt, every tool with its JSON schema, and the models it ran on. Returns the latest version unless 'version' is set - 'list_versions': the version history of one agent, one row per effective version with its seen window, generation count, tool count, and token_estimate. Paginated - 'list_version_scores': evaluation score aggregates per version, with per-evaluator score_key, pass and fail counts, and mean_score. Use it to compare how versions scored Versions: an effective version is always 'sha256:<64 lowercase hex>', and only that form is accepted by 'get'; a declared version such as '1.4.2' is reported in the declared_version fields but cannot be looked up. The plugin derives the effective version from the first of these the telemetry carries: the version the SDK reported, a hash of the declared version, a hash of the system prompt. Adding, removing, or editing a tool never mints a new version. Editing the prompt mints one only for an agent that reports neither its own effective version nor a declared version, so an agent that declares '1.4.2' keeps one effective version across prompt edits. Response size: 'get' returns the whole system prompt plus every tool schema, which can be tens of thousands of tokens. Check token_estimate.total from 'list' or 'list_versions' before fetching, and prefer the system_prompt_prefix in those rows when a prefix is enough. Cross-referencing: an agent name from 'list' is the value of the agent = "<name>" filter in conversation search. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. For 'list', also repeat the same name_prefix, start_time, and end_time using absolute RFC3339 times; the cursor is bound to those filters and a relative value such as now-7d or 7d re-resolves and is rejected. Permissions: every operation is a read and needs grafana-agento11y-app.data:read (Agento11y Editor or Admin). This tool performs no writes. When to use: - Discovering which agent names exist before filtering conversations or generations by agent - Reading the system prompt or tool inventory an agent ran with, or how they changed between versions - Checking whether a new prompt version scores worse than the previous one When NOT to use: - Reading individual conversations, generations, or their scores - Inspecting evaluators or the rules that schedule them

List, search, and fetch LLM conversations from Grafana Agent Observability (the grafana-agento11y-app plugin). Operations: - 'list': recent conversations (lightweight; id, title, generation count, timestamps), paginated via limit and cursor - 'search': search conversations by filter expression and time range; results include models, agents, error counts, rating and eval summaries, and trace IDs - 'get': one conversation by ID with all its generations, including full prompts and outputs (can be large) Filter syntax for 'search': key operator value, with the value in double quotes; multiple filters are separated by spaces and combined with AND. Filter keys (trace): model, provider, agent, agent.version, status, error.type, error.category, duration, tool.name, operation, namespace, cluster, service Filter keys (metadata): generation_count, eval.passed, eval.evaluator_id, eval.score_key, eval.score Operators: =, !=, >, <, >=, <=, =~ (regex) Example: status = "error" agent = "claude-code" Pagination: when a response has next_cursor, fetch the next page by calling the same operation again with cursor set to next_cursor. For 'search', also repeat the same filters, start_time, and end_time as the first call, using absolute RFC3339 times; relative ranges like now-24h shift between calls and the cursor will be rejected. When to use: - Debugging an AI application: find failing or low-rated conversations, then inspect their generations - Reviewing evaluation results and user ratings across conversations When NOT to use: - Fetching a single generation or its evaluation scores

Manage the curated conversations of Grafana Agent Observability (the grafana-agento11y-app plugin): bookmark conversations as saved conversations and group them into collections. Two linked resources: - A saved conversation (/eval/saved-conversations) is a bookmark on one conversation, keyed by a saved_id you choose. It gives that conversation a stable ID, a name, and tags a collection can reference. It does not preserve the conversation: retention deletes the bookmark and its collection memberships together with the conversation it points at. - A collection (/eval/collections) is a named group of saved conversations, used as the source material for offline evaluation. Collections hold saved conversations, never raw conversation IDs, so a conversation must already be bookmarked before a collection accepts it. Operations: - 'list_saved_conversations': bookmarked conversations in this tenant, filterable by source ('telemetry' for bookmarked production traffic, 'manual' for hand-built ones). Also reports total_count for the whole filtered set, not just the page - 'get_saved_conversation': one bookmark by ID - 'list_collections_for_saved_conversation': the collections one bookmark belongs to (unpaginated) - 'list_collections': collections in this tenant, each with its member_count - 'get_collection': one collection by ID - 'list_collection_members': the saved conversations in a collection - 'save_conversation': bookmark a live conversation by conversation_id. saved_id is optional and defaults to 'saved-<conversation_id>'; a conversation can only be saved once, so a repeat returns 409 naming the existing saved_id - 'delete_saved_conversation': delete a bookmark by saved_id. Idempotent, and it also removes the bookmark from every collection it belonged to, with no separate membership cleanup. On a source='manual' bookmark the backend goes further and deletes the underlying conversation and its generations, so the content itself is gone - 'create_collection': create an empty collection from a name and optional description. The response carries the server-assigned collection_id needed by the membership operations - 'update_collection': patch a collection's name or description. Omitted fields are left unchanged, and an explicitly empty description clears it - 'delete_collection': delete a collection and its memberships in one transaction. Idempotent, and the saved conversations themselves are kept - 'add_collection_members': add saved_ids to a collection. Every ID must already be a saved conversation (a missing one returns 400 naming it), and re-adding an existing member is a no-op - 'remove_collection_member': drop one saved conversation from a collection. Idempotent, and the bookmark itself is kept Identifiers: saved_id is caller-chosen and accepts letters, digits, '_', '.', ':', and '-' (looser than the evaluator and rule IDs, which reject hyphens). collection_id is a UUID assigned by the server when a collection is created; it cannot be chosen. List rows are already enriched: every saved conversation in 'list_saved_conversations' and 'list_collection_members' embeds the collections it belongs to plus generation_count, total_tokens, agent_names, models, model_providers, and tags. Read those fields instead of calling 'list_collections_for_saved_conversation' per row, which is one request per result. An absent collections field means the row was not enriched; an empty array means the row genuinely belongs to no collection. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. Echo the value back exactly; never construct or increment one. 'list_saved_conversations' returns an opaque numeric value while 'list_collections' and 'list_collection_members' return the last row ID, so a cursor from one operation passed to another fails or silently skips rows. Keep the same source filter across pages. Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403. When to use: - Reading what is already curated: which collections exist, how large they are, and what is in them - Turning a triaged failure into a regression collection: 'save_conversation', then 'create_collection' or 'add_collection_members' - Bookmarking a live conversation so a collection can reference it by a stable ID - Collection hygiene: renaming a collection, or removing a conversation that no longer belongs in it When NOT to use: - Searching or reading live conversations and generations - Inspecting evaluators or the rules that schedule them

Manage the evaluation rules and guards of Grafana Agent Observability (the grafana-agento11y-app plugin): the configuration that decides when evaluators run. Two different resources with different runtime behavior: - Eval rules (/eval/rules) are asynchronous. A rule selects production traffic (selector, match filters, sample_rate) and schedules its evaluator_ids to score matching generations after the fact. Rules only observe; they never change a request. - Guards (/eval/hook-rules; there is no /eval/guards path) run inline on the request path and can deny it, redact content, or block tool calls. A guard is inert until the agent application calls the hooks endpoint (POST /eval/hooks:evaluate) itself: a stored guard on its own changes nothing. Operations: - 'list_rules': asynchronous eval rules in this tenant (paginated) - 'get_rule': one eval rule by ID - 'list_guards': guards, read from /eval/hook-rules (paginated) - 'get_guard': one guard by ID - 'create_rule': create an asynchronous eval rule from an inline 'definition' - 'update_rule': patch an existing rule; send only the fields to change (rule_id is taken from the 'rule_id' parameter and must not appear in the definition) - 'delete_rule': delete a rule by ID - 'preview_rule': dry-run a selector, match, and sample_rate against recent traffic and return how many generations would match and be sampled, plus example generations. Run this before creating a rule that spends judge tokens - 'create_guard': create an inline guard (stored as a hook rule) - 'update_guard': full replace of a guard (PUT, not PATCH) — omitted fields reset to server defaults, so send the complete definition, normally a 'get_guard' result with your edits applied - 'delete_guard': delete a guard by ID Identifiers (rule_id) accept only letters, digits, '_', and '.'; hyphens are rejected by the API. Rule selectors: user_visible_turn, all_assistant_generations, tool_call_steps, errored_generations, conversation (guards also accept 'all'). Match keys are arrays and include agent_name, agent_version, operation_name, model.provider, model.name, mode, error.type, error.category, and tags.<key>. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write, plus 'preview_rule' (which persists nothing), needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403. When to use: - A score names an evaluator and you need to know which rule scheduled it and on what traffic - Auditing which guards are live and whether they warn or deny - Binding a new evaluator to production traffic with 'create_rule', after checking the blast radius with 'preview_rule' - Adding a guard, or promoting one from warn to deny after watching its false-positive rate When NOT to use: - Inspecting what an evaluator checks, or the template it came from - Listing conversations, generations, or scores

Manage the evaluator catalog of Grafana Agent Observability (the grafana-agento11y-app plugin): read evaluators, evaluator templates, and the judge model catalog, and create, test, or delete evaluators. An evaluator is a scoring function (kind: llm_judge, json_schema, regex, or heuristic) that scores generations. Generation scores name the evaluator that produced them. Templates are versioned starting points for evaluators. Judge providers and models are the LLM backends an llm_judge evaluator can use. Operations: - 'list_evaluators': evaluators in this tenant (paginated) - 'get_evaluator': one evaluator by ID, with its kind, config, and output_keys - 'list_templates': evaluator templates, filterable by scope ('global' for built-ins, 'tenant' for locally created ones) - 'get_template': one template with its config, output_keys, and version list - 'list_template_versions': version history of a template, each version with its config and output_keys - 'list_judge_providers': judge providers configured on this stack - 'list_judge_models': judge models, optionally filtered by provider - 'upsert_evaluator': create or update an evaluator from an inline 'definition'. POST is create-or-update keyed on definition.evaluator_id; there is no separate update operation, and re-using an existing 'version' returns 409, so bump the version to change an evaluator - 'delete_evaluator': soft-delete an evaluator by ID. Rules and guards that reference it keep the reference and silently stop producing scores - 'fork_template': derive a new evaluator from a template in one call. Prefer this over copying 'get_template' output into 'upsert_evaluator', which the API rejects - 'test_evaluator': run an inline evaluator definition against one generation and return its scores without persisting anything. Useful for tuning a judge config before 'upsert_evaluator' Identifiers (evaluator_id, template_id) accept only letters, digits, '_', and '.'; hyphens are rejected by the API. Template operations need a stack with the evaluator template store configured and return 404 otherwise. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write, plus 'test_evaluator' (which persists nothing), needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403. When to use: - A generation score names an evaluator and you need to see what it checks - Inspecting a template before deriving an evaluator from it - Tuning an llm_judge config against a real generation with 'test_evaluator' before storing it - Creating an evaluator so a rule or guard can reference it When NOT to use: - Finding which rule scheduled an evaluator, or which guard enforces it - Listing conversations, generations, or scores

Manage the offline experiments of Grafana Agent Observability (the grafana-agento11y-app plugin), their trials, and their scores. An experiment is one offline run of an agent over a test suite. Each test case in the suite produces one or more trials, each trial is scored by the experiment's evaluators, and the experiment reports a pass rate. Experiments are created by SDK runners, not from here. Operations: - 'list': experiments in this tenant, filterable by suite_id, status, source, created_by, tag, and a created_at or completed_at window. Each row carries the same result summary as 'get', so finding the experiment that regressed needs no second call - 'get': one experiment with its result summary: pass rate, average final score, total cost and tokens - 'get_report': the per-test-case breakdown, trimmed by row_limit. The test case input and expected values, the score records, and the artifact records are dropped because those fields have no size bound; each trial keeps its error message, a score_count, an artifact_count, and the IDs the drill-downs take - 'list_trials': one experiment's trials, paginated. Prefer this over 'get_report' on a large suite. It reports no cost or token counts: only the report path fills those in - 'list_scores': every score in one experiment, paginated - 'get_trial': one trial in full, including the test case snapshot with its input and expected values - 'list_trial_scores': one trial's scores, with the explanation each judge wrote - 'list_trial_artifacts': one trial's artifact metadata, with a content_ref rather than the bytes - 'list_facets': the distinct suites, owners, and tags across every experiment in the tenant, for building a 'list' filter. Only source, from, and to narrow it; it rejects a filter it would otherwise have to ignore - 'update': patch an experiment's name, description, tags, or metadata. Only the experiment's created_by may patch it, so patching an experiment someone else started answers 401 - 'cancel': stop a running experiment. It checks no owner, so any caller with the write permission can stop any experiment. An experiment that already finished is left alone: the call answers 200 and returns it unchanged instead of failing, so read the status on the result rather than assume a run was stopped Size: 'get_report' is fetched whole before it is trimmed, and a response above 10 MiB fails the call rather than arriving truncated. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it, repeating the first page's filters with absolute RFC3339 times. A relative bound such as now-7d re-resolves between calls and moves the window the cursor was issued against, so it is rejected alongside a cursor. Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Both writes need grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403. When to use: - Finding the last experiment for a suite after a suspected regression: 'list' by suite_id, then read the pass rate off the row - Finding which test cases an experiment failed on, then reading one failing trial in full - Labelling an experiment after triage, so 'list' by tag finds it later - Stopping an experiment that is burning judge tokens on a broken candidate When NOT to use: - Reading scores on live production traffic - Inspecting the test cases a suite defines, or editing them - Inspecting what an evaluator checks

Fetch a single LLM generation and its evaluation scores from Grafana Agent Observability (the grafana-agento11y-app plugin). Operations: - 'get': full generation detail by ID, including prompt, output, model, and usage (can be large) - 'scores': evaluation scores for a generation (evaluator, score key, score type, value, passed, explanation) When to use: - Drilling into one generation of a conversation - Checking why an evaluation passed or failed for a specific generation When NOT to use: - Searching or listing conversations

Manage the test suites of Grafana Agent Observability (the grafana-agento11y-app plugin), their versions, and their test cases. A test suite is the input side of an offline experiment: a named set of test cases that an SDK runner replays against an agent. Suites are versioned, and a test case belongs to one version rather than to the suite, so every test case operation takes both suite_id and version. A version is either a draft or published. A draft accepts test case edits; publishing freezes it and makes it the suite's latest_version, which is the version a runner picks up. A suite has at most one draft at a time. Operations: - 'list_suites': the test suites in this tenant, newest first. The rows carry no version history - 'get_suite': one suite with its full version history under versions - 'list_test_cases': the test cases of one suite version, oldest first, paginated - 'get_test_case': one test case in full, with its free-form input and expected values - 'create_suite': a new empty suite. It has no version yet, so follow it with 'create_draft_version' - 'update_suite': patch a suite's name, description, or tags - 'create_draft_version': open a new editable version. A suite that already has a draft answers 409 - 'publish_version': freeze a draft. There is no unpublish; a published version answers 409 to a second publish and to every test case edit, so changing a published suite means a new draft - 'upsert_test_case': write a whole test case into a draft version. It replaces the stored case rather than merging into it, so a field left out is cleared; read the case with 'get_test_case' first and send it back complete - 'delete_test_case': remove one test case from a draft version. Deleting a test case that is already gone answers 404 Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. Permissions: reads need grafana-agento11y-app.data:read (Agento11y Editor or Admin). Every write needs grafana-agento11y-app.eval:write, granted only by the Agento11y Admin role; an Editor token gets 403. When to use: - Reading the test cases at the version an experiment used, after it reported a failing case - Adding a regression case to a suite, then publishing the draft so the next experiment picks it up - Correcting a test case whose expected value was wrong When NOT to use: - Reading how a suite scored, or the trials, scores, and artifacts behind it - Changing what an evaluator checks

Manage Grafana alerting routing configuration, including notification policies, contact points and time intervals. Notification policies define how alerts are grouped, routed, and which contact points receive them. Time intervals define active/mute periods for alert notifications. When to use: - Understanding how alerts are routed to contact points/receivers - Debugging why an alert went to a specific receiver - Checking grouping, timing, or mute interval settings Does not show alert rule configuration or state.

Create Grafana-managed contact points for alert notifications using operation 'create_contact_point'. Requires name, type and integration-specific settings. Returns uid, name and type without settings or secrets. Contact points remain editable in the Grafana UI by default. External Alertmanager receivers are not supported. Does not list or inspect existing contact points.

List and inspect Grafana alert rules with filtering capabilities. When to use: - Understanding why an alert is or isn't firing - Auditing alert rule configuration (queries, conditions, labels, notification settings) - Finding alert rules by state, folder, group, or name - Comparing rule versions to see what changed Read-only: does not create, update, or delete rules, and does not show notification routing.

Create, update, and delete Grafana alert rules. When to use: - Creating, updating, or deleting alert rules Operation 'update' replaces the whole rule: it takes all required fields, not only the changed ones. Does not list or inspect rules, and does not manage notification routing.

List and inspect Grafana alerting silences. A silence temporarily suppresses notifications for alerts whose labels match a set of matchers. Operations: - 'list': list existing silences. Optionally filter by rule_uid (matches the __alert_rule_uid__ label) or by matchers. - 'get': retrieve a single silence by silence_id. When to use: - Inspecting which alerts are currently silenced and why Read-only: does not create, update, or delete silences, and does not show alert rules or notification routing.

Create, update, and delete Grafana alerting silences. A silence temporarily suppresses notifications for alerts whose labels match a set of matchers, without changing the alert rules themselves. Operations: - 'create': create a new silence. Requires matchers, starts_at, ends_at (RFC3339) and comment. - 'update': modify an existing silence by silence_id. Requires matchers, starts_at, ends_at and comment. The id is only kept when the posted matchers and starts_at match the stored ones, so pass back the stored starts_at of the silence; otherwise Alertmanager expires the old silence and returns a new id. - 'delete': expire/remove a silence by silence_id. When to use: - Muting noisy or expected alerts during maintenance windows Does not list or inspect silences, change alert rules, or manage notification routing.

Audits a Loki label strategy and optionally diagnoses query performance. Returns per-label verdicts, missing base labels, normalisation issues, and a recommended set. Pass datasourceUid for live cardinality or labels for static scoring; both may be combined.

Send a message to Grafana Assistant and wait for the full text reply. The assistant may use tools, metrics, logs, and other stack context—broader than firing one isolated data-source query. Suited to open-ended questions and triage that need assistant reasoning and tool use. **Multi-turn:** each result includes a contextId; passing it back continues the same conversation. **Time:** complex tasks can take several minutes; the call blocks until the reply is done or the request times out.

Historical/indexed memory search across your Grafana stack: infrastructure/service groups, dashboards, past investigations, mostly-resolved IRM incidents, and alert-rule definitions. Covers architecture, topology, dashboard discovery (including panel queries), alerts by meaning or content, past incidents, past investigations/RCAs, and broad "what do we know about X?" questions. Investigation and incident searches default to records created in the last three calendar months. Results are indexed snapshots, not live telemetry, and can be stale or incomplete: an infrastructure result's dependency list comes from a sample of recent traces and can miss calls. Live metrics, logs, traces, alert state, and on-call or incident data are not searched. Returns results grouped by collection with titles, summaries, links, and metadata (including datasource UIDs for infrastructure results).

Check datasource health. Filter by type or UIDs; omit both to check all.

Create a new annotation on a dashboard or panel. Set format to 'graphite' and provide 'what' for Graphite-format annotations.

Create a datasource in two steps. Called with only the type, it returns the plugin's field schema and creates nothing. Called with the type, the display name in the top-level name argument, schemaReviewed=true, and field values in the fields map, it creates the datasource. The plugin for the type must already be installed. Secrets (passwords, tokens) are not accepted. Returns UID, health check, and a config page link.

Create a Grafana folder. Provide a title and optional UID. Returns the created folder.

Create a new Grafana incident. Requires title, severity, and room prefix. Allows setting status, labels and custom fields. Creating an incident may notify or page many people.

Start a Grafana Assistant investigation: an agentic, multi-step root-cause analysis across the stack's metrics, logs, traces, dashboards, and alerts. Provide a natural-language instruction describing what to investigate. Optionally set a title, share with teams via teamNames, or pick an agent profile via agentProfileId. The investigation runs asynchronously and usually takes several minutes: this returns investigationId, chatId, and a url to open it in Grafana immediately, before the investigation finishes.

Create a Grafana snapshot from a full dashboard payload. Supports optional expiration and external snapshot fields.

Permanently delete an annotation by ID. The annotation cannot be recovered afterwards.

Delete a Grafana snapshot by snapshot key.

Get column schema for a table in a supported SQL datasource (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Returns column names and types.

Compare two complete traces. Returns a compact summary and includes the full span-level patch when it is at most 64 KiB. Request trace-patch-v0 only when full details are required; full patches are not size-bounded.

Generate deeplink URLs for Grafana resources. Supports dashboards (requires dashboardUid or provisioningPreview), panels (requires dashboardUid or provisioningPreview, plus panelId), and Explore queries (requires datasourceUid and optionally queries). For dashboard and panel links, provisioningPreview points at a dashboard staged on a provisioning repository branch (e.g. a git-sync PR preview). For explore links, the time range and queries are embedded inside the Grafana explore state. Set shorten=true to also attempt a /goto/<uid> short URL; if shortening fails, the full deeplink is returned.

Get a specific alert group from Grafana OnCall by its ID. Returns the full alert group details, including the most recent alert and its raw payload when the OnCall API provides them. Alert payloads carry integration-specific fingerprints (for example Sentry's payload.data.event.hashes or Alertmanager's payload.alerts[].fingerprint) that identify recurring alerts across different alert groups.

Returns annotation tags with optional filtering by tag name. Only the provided filters are applied.

Fetch Grafana annotations using filters such as dashboard UID, time range and tags.

Get assertion summary for a given entity with its type, name, env, site, namespace, and a time range

Read the transcript of an existing Grafana Assistant conversation by ID. Covers conversations started anywhere, including the Assistant sidebar in Grafana. Returns the user-visible messages in order as prose; includeToolCalls adds the assistant's tool calls and results. The conversationId is the same identifier used as an Assistant conversation's contextId.

Get the list of users currently on-call for a specific Grafana OnCall schedule ID. Returns the schedule ID, name, and a list of detailed user objects for those currently on call.

Retrieves the complete dashboard, including panels, variables, and settings, for a specific dashboard identified by its UID. Pass optional version to load a saved snapshot instead of the current dashboard. Saved snapshots are fetched through Grafana's legacy versions API, so 'apiVersion' is omitted and 'meta' is partial: only version, createdBy, and created are populated. For current (non-versioned) fetches, the response includes 'apiVersion' and 'isV2': when 'isV2' is true the dashboard uses the v2 schema (panels live under 'elements' keyed by name, arranged by 'layout'; variables under 'variables'), otherwise it is classic v1 ('panels[]' with 'templating.list'). The full JSON of a large dashboard can be very large.

Retrieve panel queries from a Grafana dashboard. Supports all datasource types (Prometheus, Loki, CloudWatch, SQL, etc.) and row-nested panels. Optionally filter to a specific panel by ID with `panelId`. Optionally provide `variables` for template variable substitution, which populates `processedQuery` and `requiredVariables` fields. Returns an array of objects with fields: title, query (raw expression), datasource (object with uid and type), and optionally processedQuery, refId, requiredVariables, and target. Targets built in a visual editor (CloudWatch metric search, InfluxDB query builder) have no string expression: those return an empty query plus `target`, the panel's raw query JSON. They can be executed as panel queries but not as standalone expressions.

Get specific parts of a dashboard using JSONPath expressions to minimize context window usage. JSONPath targets the dashboard's native schema. Classic v1 paths: '$.title' (title), '$.panels[*].title' (all panel titles), '$.panels[0]' (first panel), '$.templating.list' (variables), '$.annotations.list' (saved dashboard annotation queries/definitions), '$.tags' (tags), '$.panels[*].targets[*].expr' (all queries). v2 dashboards (isV2 true) use different paths: '$.title', '$.elements' (panels, keyed by name), '$.variables' (variables), '$.annotations'.

Get a compact summary of a dashboard including title, panel count, panel types, variables, and other metadata without the full JSON. Use this for dashboard overview and planning modifications without consuming large context windows.

Retrieves detailed information about a specific datasource by UID or name. Returns the full datasource model, including name, type, URL, access settings, JSON data, and secure JSON field status. Provide either uid or name; uid takes priority if both are given.

Fetch a Grafana documentation page. Set outline_only=true to get the heading structure first, then call again with a section name for bounded retrieval.

Get a single incident by ID. Returns the full incident details including title, status, severity, labels, custom fields, timestamps, and other metadata.

Get one Grafana Assistant investigation (AI-driven root-cause investigation) by ID. Returns the investigation's identifiers (investigationId and chatId), the authoritative row lifecycle state and metadata (title, description, state, summary, labels, team ownership, timestamps, completion quality, failure details), and the engine work snapshot (sessionStatus, mode, epoch, plan, report content). The row's state field is authoritative for investigation lifecycle (pending, in_progress, completed, failed, cancelled, paused). The snapshot's sessionStatus only describes the engine session (idle, active, pause) and does not indicate completion or failure. Legacy (v1) investigations may have no snapshot; the row metadata is still returned with snapshotError set.

Read the report of one Grafana Assistant investigation (AI-driven root-cause investigation) as markdown. Returns the report plus the investigation's state, summary, completion quality, reportPending, and a url to open it in Grafana. The report is empty until the investigation writes one, which usually happens once it settles. An investigation can also settle without a report, for example when it answers directly; its summary then holds the answer. A follow-up turn can regenerate the report, in which case reportPending is true and the previous report is returned. Reports cite evidence with [cite:pN] markers, and embedded panels appear as the same markers. Each marker is a panel ID in the investigation's evidence index.

Get the working thread of one Grafana Assistant investigation (AI-driven root-cause investigation) by ID: the user-visible conversation between the investigation agent and its tools. Resolves the investigation to its backing chat and returns the non-hidden user-visible messages in order. Each message keeps only prose (the agent's narrative and findings), tool calls (toolName and toolInput), and tool results (raw query output); internal reasoning and bookkeeping blocks are excluded. Tool results are returned verbatim and can be large; limit and offset page through long threads, and total reports the full user-visible count. The thread holds the raw data behind a report's [cite:pN] citations: each evidence entry's toolUseId matches the tool_result block in this thread that holds the captured query output.

Get detailed information for a specific Grafana OnCall shift using its ID. A shift represents a designated time period within a schedule when users are actively on-call. Returns the full shift details.

Render a Grafana dashboard panel, full dashboard or Explore view as a PNG image. Returns the image as base64 encoded data. Requires the Grafana Image Renderer service to be installed. Exactly one of dashboardUid (for stored dashboards), provisioningPreview (for dashboards staged on a provisioning repository branch, e.g. a git-sync PR) or explore (an ad-hoc datasource query rendered in Explore, no saved dashboard needed) must be supplied. Use this for generating visual snapshots of dashboards for reports, alerts, or presentations.

Check whether a Grafana plugin is installed and retrieve its details (name, version, type, enabled status). Returns installed=false when the plugin is not found.

Get example queries for a specific datasource type. Provides sample queries with descriptions for Prometheus (PromQL), Loki (LogQL), ClickHouse (SQL with Grafana macros), CloudWatch (metric configurations), and InfluxDB (Flux and InfluxQL). Use this to understand query syntax and common patterns for each datasource.

List available permissions and assignment capabilities for a Grafana resource type.

List all permissions set on a specific Grafana resource (e.g., dashboard, datasource, folder) by its type and ID.

List all assignments for a specific role, showing which users, teams, and service accounts have been assigned this role.

Get detailed information about a specific Grafana role by its UID, including permissions, metadata, and configuration.

Get a Grafana snapshot by key, including snapshot metadata and dashboard payload.

Retrieve a specific trace by ID

Retrieve TraceQL reference documentation with examples, covering attribute filters, aggregates, structural operators, and metrics queries. Consult this before writing a non-trivial TraceQL query, or after one returns an error or no results.

Make an authenticated HTTP request to the Grafana API. Similar to 'gh api' for GitHub. Supports any Grafana API endpoint with optional jq-style response filtering. Use this for API endpoints that don't have a dedicated tool.

Install a Grafana plugin by its plugin ID. When version is omitted, the tool looks up the latest version and returns it without installing; supplying a version installs that version.

List alert groups from Grafana OnCall with filtering options. Supports filtering by alert group ID, route ID, integration ID, state (new, acknowledged, resolved, silenced), team ID, time range, labels, and name. For time ranges, use format '{start}_{end}' ISO 8601 timestamp range (e.g., '2025-01-19T00:00:00_2025-01-19T23:59:59' for a specific day). For labels, use format 'key:value' (e.g., ['env:prod', 'severity:high']). Returns a list of alert group objects with their details. Supports pagination.

List all roles in Grafana. Optionally filter to show only roles that can be delegated by the current user. Returns role details including UID, name, permissions, and metadata.

List values for a CloudWatch dimension key (e.g. the specific cluster names behind a ClusterName dimension). Requires region. Supports cross-account monitoring via optional accountId parameter.

List dimension keys for a CloudWatch metric. Requires region. Supports cross-account monitoring via optional accountId parameter.

List metrics for a CloudWatch namespace. Requires region. Supports cross-account monitoring via optional accountId parameter.

List available CloudWatch namespaces (AWS/EC2, AWS/ECS, AWS/RDS, etc.). Requires region. Supports cross-account monitoring via optional accountId parameter.

List saved versions of a Grafana dashboard. Returns compact metadata: version number, author, timestamp, and save message. A version number can be passed to the dashboard fetch to load that snapshot.

List all configured datasources in Grafana. Use this to discover available datasources and their UIDs. Supports filtering by type and/or name (case-insensitive substring match) and pagination.

Discover available metric paths in a Graphite datasource by browsing the metric tree. Returns nodes matching the query pattern, each indicating whether it is a leaf metric (has data) or an expandable branch (has children). Use '*' as a wildcard at any level to enumerate the tree (e.g. '*' → top-level nodes, 'servers.*' → all second-level nodes under 'servers').

List available tag names in a Graphite datasource that uses tag-based metrics. Returns a list of tag name strings (e.g. ["name", "env", "region"]). These tags can be used to build tag-based target expressions (e.g. seriesByTag('name=cpu.load,env=prod')). Optionally filter by a prefix. Requires Graphite to be configured with tag support.

List the custom fields configured for Grafana incidents, including their type and, for select fields, the options that may be chosen.

List Grafana incidents. Allows filtering by status ('active', 'resolved') and optionally including drill incidents. Returns a preview list with basic details, and custom field values if requested.

List the evidence citation index for one Grafana Assistant investigation (AI-driven root-cause investigation) by ID. Investigation reports cite captured query panels with [cite:pN] markers. Each evidence entry describes one captured panel, keyed by that panel ID: the tool that produced it (prometheus, loki, tempo, pyroscope), a human-readable query summary, the epoch (agent turn) at capture time, the capture timestamp, and the tool call ID that produced it. This is an index, not the data: raw query results live in the investigation thread, in the tool result whose ID matches the entry's toolUseId. Legacy (v1) investigations have no engine session and return an empty list.

List the agent profiles available for Grafana Assistant investigations (AI-driven root-cause investigations) on this Grafana Cloud stack. Each profile describes an investigation agent configuration: its ID, display name, description, whether it is the default, its step budget, the tools it can use, and its content hash. A profile's ID is the agentProfileId accepted when creating an investigation.

List Grafana Assistant investigations (AI-driven root-cause investigations) on this Grafana Cloud stack. Returns one summary per investigation — ID, chat ID, title, state, timestamps, labels, team ownership, progress, and completion quality — plus the total count of matches for pagination. Results are limited to investigations the authenticated user is allowed to see. All filters are optional. chatId finds the investigation that owns a known chat (all other filters are then ignored), q is free-text search, state/scope/label/teamName/from/to narrow results, and limit/offset with the returned total paginate.

Lists all available label/field names (keys) found in logs within a specified Loki or VictoriaLogs datasource and time range. Returns a list of unique label strings (e.g., `["app", "env", "pod"]`). If the time range is not provided, it defaults to the last hour. Optionally narrow the search to a subset of streams with `matcher` (e.g. `{namespace="prod"}`).

Retrieves all unique values associated with a specific `labelName` within a Loki or VictoriaLogs datasource and time range. Returns a list of string values (e.g., for `labelName="env"`, might return `["prod", "staging", "dev"]`). Useful for discovering filter options. Defaults to the last hour if the time range is omitted. Optionally narrow the search to a subset of streams with `matcher` (e.g. `{namespace="prod"}`) — for example, to list `service` values seen only within a specific namespace.

List Grafana OnCall schedules, optionally filtering by team ID. If a specific schedule ID is provided, retrieves details for only that schedule. Returns a list of schedule summaries including ID, name, team ID, timezone, and shift IDs. Supports pagination.

List teams configured in Grafana OnCall. Returns a list of team objects with their details. Supports pagination.

List users from Grafana OnCall. These are OnCall users (separate from Grafana users). Can retrieve all users in the OnCall directory, a specific user by ID, or filter by username. Returns a list of user objects with their details. Supports pagination.

List label names in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Allows filtering by series selectors and time range.

Gets the values for a specific label name in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Allows filtering by series selectors and time range.

List Prometheus metric metadata. Returns metadata about metrics currently scraped from targets. Note: This endpoint is experimental.

Lists metric names in a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.). Filters metric names using the provided regex. Supports pagination (page * limit must not exceed 10000) and an optional time range to restrict results to metrics active within that window. Cloud Monitoring ignores the time range.

Lists all available label names (keys) found in profiles within a specified Pyroscope datasource, time range, and optional label matchers. Label matchers are typically used to qualify a service name ({service_name="foo"}). Returns a list of unique label strings (e.g., ["app", "env", "pod"]). Label names with double underscores (e.g. __name__) are internal and rarely useful to users. If the time range is not provided, it defaults to the last hour.

Lists all available label values for a particular label name found in profiles within a specified Pyroscope datasource, time range, and optional label matchers. Label matchers are typically used to qualify a service name ({service_name="foo"}). Returns a list of unique label strings (e.g. for label name "env": ["dev", "staging", "prod"]). If the time range is not provided, it defaults to the last hour.

Lists all available profile types available in a specified Pyroscope datasource and time range. Returns a list of all available profile types (example profile type: "process_cpu:cpu:nanoseconds:cpu:nanoseconds"). A profile type has the following structure: <name>:<sample type>:<sample unit>:<period type>:<period unit>. Not all profile types are available for every service. If the time range is not provided, it defaults to the last hour.

List Grafana dashboard snapshots with optional query and result limit filters.

List databases, schemas, or catalogs from a supported SQL datasource. Returns the organizational units (databases, schemas, or catalogs) that contain tables. For Athena: omit catalog to list catalogs, or pass catalog to list databases in it.

List tables from a supported SQL datasource (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Returns table names, schemas, and metadata.

List all roles assigned to one or more teams. Returns a map of team IDs to their assigned roles.

Search for Grafana teams by a query string. Returns a list of matching teams with details like name, ID, and URL.

List available attribute names for TraceQL queries. Without a scope (resource, span, etc.) the response can be very large.

List values for a fully scoped attribute name (e.g. resource.service.name). Useful for discovering what values exist for a specific attribute.

List all roles assigned to one or more users. Returns a map of user IDs to their assigned roles, excluding built-in roles and team-inherited roles.

List users in the Grafana organization. Returns a list of organization users with details like userid, email, role etc.

Query AWS CloudWatch metrics via Grafana. Requires region. Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms) Common namespaces: AWS/EC2, AWS/ECS, AWS/RDS, AWS/Lambda, ECS/ContainerInsights Example dimensions: ECS: {ClusterName, ServiceName}, EC2: {InstanceId} Cross-account monitoring: Use accountId to query metrics from a specific source account (e.g. '123456789012') or 'all' to query all linked accounts. Only applicable when using a CloudWatch monitoring account datasource.

Executes a search query against an Elasticsearch or OpenSearch datasource and retrieves matching documents. Supports Lucene query syntax (e.g., 'status:200 AND host:server1') for both Elasticsearch and OpenSearch. Elasticsearch Query DSL JSON is also supported for Elasticsearch datasources only (not OpenSearch). Returns a list of documents with their index, ID, source fields, and optional score. Use this to search logs, metrics, or any indexed data stored in Elasticsearch or OpenSearch. Defaults to 10 results and sorts by @timestamp in descending order (newest first).

Executes a Graphite render API query against a Graphite datasource and returns matching metric series with their datapoints. Supports the full Graphite target expression language including wildcard patterns (e.g. 'servers.web*.cpu.load5'), aggregation functions (e.g. 'sumSeries(app.*.requests)'), and tag-based queries (e.g. 'seriesByTag(\'name=cpu.load\')'). Datapoints with no recorded value are returned with a null value field. Time range defaults to the last hour if not specified.

Analyses metric data density for one or more Graphite series over a time window. Returns per-series statistics: fillRatio (fraction of non-null datapoints, 0.0–1.0), totalPoints, nonNullPoints, lastSeen (Unix timestamp of most recent non-null value, or null if none), longestGap (longest consecutive null run in seconds), and estimatedInterval (inferred write interval in seconds). Supports wildcard targets (e.g. 'obox-cl*.sys.sessions') to diagnose stale, sparse, or dead metrics across a cluster. A fillRatio of 0 with lastSeen null means the series reported no data in the requested window.

Query an InfluxDB datasource via Grafana. Supports both InfluxQL (v1.x) and Flux (v2.x). The 'dialect' parameter selects the query language; if omitted it's inferred from the datasource configuration. Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms) InfluxQL example: SELECT mean("value") FROM "cpu" WHERE time > now() - 1h GROUP BY time(1m) Flux example: from(bucket: "metrics") |> range(start: -1h) |> filter(fn: (r) => r._measurement == "cpu")

Executes a log query against a Loki or VictoriaLogs datasource and returns matching log entries (or metric samples on Loki). Defaults to the last hour, a limit of 10 entries, and 'backward' direction (newest first). The `logql` parameter takes LogQL on Loki and LogsQL on VictoriaLogs (e.g., Loki: `{app="foo"} |= "error"`; VictoriaLogs: `{app="foo"} "error"`). To count matching log lines precisely, use a `count_over_time()` metric query with queryType='instant'. For broad queries that match many lines, set `format` to 'compact' to group results by stream and avoid repeating label metadata on every line. If this server enables the Loki cost guardrail, expensive queries are rejected before execution: query cost is bytes SCANNED, determined only by the stream selector and time range — line filters (|=) and parsers (| json) reduce what is returned, not what is scanned. Use a stream selector with at least one selective positive label matcher (never `{}`, `=~".*"`/`=~".+"`, or negative-only matchers), keep time ranges narrow; rejected queries return rewrite guidance.

Retrieves detected log patterns from a Loki datasource for a given stream selector and time range. Returns a list of patterns, each containing a pattern string and a total count of occurrences. Patterns help identify common log structures and anomalies. The `logql` parameter must be a stream selector (e.g., `{job="nginx"}`) and does not support line filters or aggregations. Defaults to the last hour if the time range is omitted. **Not supported on VictoriaLogs** datasources - use a `| stats` pipeline instead.

Retrieves index-level statistics about log streams matching a given selector within a Loki or VictoriaLogs datasource and time range. Returns an object containing the count of streams, chunks, entries, and total bytes (e.g., `{"streams": 5, "chunks": 50, "entries": 10000, "bytes": 512000}`). **Important**: the `entries` count reflects storage-level index entries (chunk metadata), NOT the number of individual log lines matching the selector. Counting actual matching log lines requires a `count_over_time()` LogQL metric query. On VictoriaLogs only `entries` is populated; the other fields remain zero. The `logql` parameter **must** be a simple label selector (e.g., `{app="nginx", env="prod"}`) and does not support line filters, parsers, or aggregations. Defaults to the last hour if the time range is omitted.

Query a PromQL-compatible datasource (Prometheus, Thanos, Mimir, Cloud Monitoring, etc.) using a PromQL expression. Supports instant queries (single point) and range queries (time range). Time: RFC3339 or relative expressions like 'now', 'now-1h'.

Query Prometheus histogram percentiles from classic histogram '_bucket' series. Generates histogram_quantile PromQL. Example: metric='http_duration', percentile=95, labels='job="api"' Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms)

Unified Pyroscope query tool for fetching profiles or metrics from Pyroscope. Profile data shows WHICH functions consume resources; metrics data shows WHEN consumption spiked. Use query_type="both" for complete analysis in one call. query_type options (extends Grafana's PyroscopeQueryType): - "profile": returns profile data (shape controlled by format) - "metrics": returns time-series data points - "both" (default): returns both profile and metrics in one response format options (shape of the profile data): - "table" (default): per-function table with flat (self) and cumulative values, ranked by flat - "dot": call graph in Graphviz DOT format; nodes are per source line, so one function may span several nodes

Executes a search query against a Quickwit datasource and retrieves matching documents. Supports Lucene query syntax (e.g., 'severity_text:ERROR AND service_name:api') and partial Elasticsearch-compatible Query DSL JSON. The timestamp field is resolved from Quickwit index metadata (not jsonData.timeField). Returns a list of documents with their index, ID, source fields, and optional score. Use this to search logs or other indexed data stored in Quickwit. Defaults to 10 results and sorts by the index timestamp field in descending order (newest first).

Query a supported SQL datasource (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL) via Grafana. Supports datasource-specific macros: $__timeFilter(column), $__from/$__to, $__interval, ${varname} Time formats: 'now-1h', '2026-02-02T19:00:00Z', '1738519200000' (Unix ms) Example: SELECT timestamp, message FROM logs WHERE $__timeFilter(timestamp) LIMIT 100

Compute trace-derived metrics using a TraceQL metrics query. The syntax is unlike PromQL. Use type 'instant' for a single value or 'range' for a time series (default). Instant queries over large time ranges may timeout — keep the window under 15 minutes for instant, or use range instead.

Executes one or more dashboard panel queries with optional time range and variable overrides. Accepts an array of panel IDs to query in a single call. Fetches the dashboard, extracts queries from the specified panels, substitutes template variables and Grafana macros ($__range, $__rate_interval, $__interval), and routes to the appropriate datasource (Prometheus, Loki, ClickHouse, CloudWatch, InfluxDB, BigQuery, MSSQL, or PostgreSQL). Returns results keyed by panel ID - partial failures are allowed (some panels can succeed while others fail). If a panel uses a template variable datasource you cannot access, provide datasourceUid and datasourceType to override.

Search Grafana dashboards by query and/or folderUid, tag, and starred. Returns matching dashboards with title, UID, folder, tags, and URL.

Search Grafana documentation. Returns matching pages with title, URL, description, and product. Call with no query to list available product groups.

Search for Grafana folders by a query string. Returns matching folders with details like title, UID, and URL.

Search the Grafana plugin catalog by keyword, purpose, or partial name (e.g. 'azure monitoring', 'loki', 'database'). Returns results sorted by trust: official Grafana Labs plugins first, then commercial partner plugins, then community plugins, each with its exact pluginId. Results include warnings for enterprise-only or Angular-based plugins.

Search for traces using TraceQL queries

Generates an Alloy loki.process snippet enforcing an approved label set via stage.label_keep, with optional log-level normalisation and soft-enforcement placeholders.

Update the state of a Grafana OnCall alert group: acknowledge, unacknowledge, resolve, or unresolve it by ID. Returns the alert group's resulting OnCall state (one of new, acknowledged, resolved, silenced), or a stateWarning explaining why that state could not be read back after a successful update.

Updates the provided properties of an annotation by ID. Only fields included in the request are modified; omitted fields are left unchanged.

Create or update a dashboard. Returns the saved dashboard UID and dashboard link in the 'url' field, using the instance public URL when available. Two modes: (1) Full JSON — provide 'dashboard' for new dashboards or complete replacements. (2) Patch — provide 'uid' + 'operations' to make targeted changes to an existing dashboard. One of these two modes is required; 'folderUid', 'message', and 'overwrite' are supplementary and do nothing on their own. Dashboard authoring guidance: if a saved query must support one, many, or All values from a multi-select variable inside a regex expression or matcher, save '${var:regex}' rather than plain '$var'. Saved dashboard annotation queries/definitions live in dashboard JSON under 'annotations.list'; annotation events are stored separately and are not part of the dashboard JSON. For stat panels over the current dashboard range, make the query return the range-level result the stat should display; panel-side reduction only reduces returned series and does not compute peak-over-range or ratio-of-peaks semantics for you. Patch operations support JSONPaths like '$.panels[0].targets[0].expr', '$.panels[1].title', '$.panels[2].targets[0].datasource', '$.templating.list/-', and '$.annotations.list/-'. Append to arrays with '/- ' syntax: '$.panels/- '. Remove by index: {"op": "remove", "path": "$.panels[2]"}. Multiple removes on the same array are automatically reordered to avoid index-shifting issues. Note: only numeric array indices are supported in patch paths; filter expressions like [?(@.id==2)] and wildcards like [*] are not supported. Schema: prefer v2 for new dashboards; if this Grafana lacks v2 the save fails saying so, then send v1. Keep an existing dashboard in its stored schema (indicated by 'isV2'/'apiVersion' on the fetched dashboard). A body with top-level 'elements'/'layout' is saved as v2. Minimal v2 body: {"title":"T","timeSettings":{"from":"now-6h","to":"now"},"variables":[],"elements":{"p1":{"kind":"Panel","spec":{"id":1,"title":"Up","vizConfig":{"kind":"VizConfig","group":"timeseries","spec":{}},"data":{"kind":"QueryGroup","spec":{"queries":[{"kind":"PanelQuery","spec":{"refId":"A","query":{"kind":"DataQuery","group":"prometheus","datasource":{"name":"<ds uid>"},"spec":{"expr":"up"}}}}]}}}}},"layout":{"kind":"GridLayout","spec":{"items":[{"kind":"GridLayoutItem","spec":{"x":0,"y":0,"width":24,"height":8,"element":{"kind":"ElementReference","name":"p1"}}}]}}}. For tabs, layout is {"kind":"TabsLayout","spec":{"tabs":[{"kind":"TabsLayoutTab","spec":{"title":"A","layout":<GridLayout>}}]}}.

Update non-secret datasource fields by UID in two steps. Called with only the uid, it returns the datasource's field schema and changes nothing. Called with the uid, schemaReviewed=true, and the changed values in the fields map, it applies the update. Omitted fields are preserved. Secrets (passwords, tokens) cannot be changed. Returns an update message and a health check.

Update an existing Grafana incident by ID. Allows changing the status ('active' or 'resolved'), the severity, the title, and custom field values. Only the provided fields are changed. Use this to resolve an incident, to correct its severity or title, or to fill in custom fields as part of an on-call workflow.

Get information about the current Grafana identity: login, email, name, whether it is a Grafana (server) admin, the current organization, and the organizations it can access (with roles). Call this to discover which orgId values are valid before targeting a specific organization, and to understand the identity's capabilities.

Wait for a Grafana Assistant investigation (AI-driven root-cause investigation) to settle, up to timeoutSeconds (default 45, max 300). Many MCP clients cancel tool calls after 60 seconds. Returns as soon as the investigation is settled — completed, failed, cancelled, or paused — or when the timeout elapses, whichever is first. The result is a compact status: state, settled, timedOut, title, summary, completion quality, failure details, and a url to open the investigation in Grafana. Investigations usually take several minutes, so settled is often false on return. A paused investigation is waiting for a person in Grafana and will not progress on its own.