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

# AI & Agents Overview

> Ask questions about your traces in plain English by pointing an AI agent at the Mirador REST API

Everything an AI agent needs to investigate your traces already exists: the [REST API](/api/overview) exposes your traces, event timelines, and metadata over typed, read-only endpoints, and [`llms.txt`](https://api.mirador.org/llms.txt) documents all of it in a single brief written for LLMs. Give an agent those two things plus a [server key](/api/authentication), and you can ask questions like:

* *"Explain why traces in the past 24 hours have been having more errors."*
* *"Which attribute values are most correlated with failed traces this week?"*
* *"Summarize what happened in trace 317 and where it went wrong."*
* *"Are bridge transfers failing more often on one chain than the others?"*
* *"Compare error rates before and after yesterday's 14:00 UTC deploy."*

There's no special AI product surface to enable — no plugin, no separate endpoint. Any agent that can make HTTP requests (Claude Code, a custom agent built on the Claude API, an internal incident bot) can do this today.

## Why this works well

The REST API was designed with agent use in mind, and a few properties make investigations reliable rather than hallucinated:

* **Discoverable field universe.** The [metadata endpoints](/api/endpoints#metadata) list every tag and attribute key your project has actually used, so an agent composes filters from real fields instead of guessing names.
* **Exact counts in one request.** `GET /v1/traces` with `per_page=10` returns `pagination.total` — an exact count. An agent can compare error volume across time windows with a handful of cheap requests before drilling into anything.
* **Complete evidence per trace.** `GET /v1/traces/{trace_id}/events` returns the full, ordered event timeline, so conclusions about *why* a trace failed are grounded in the actual events, not the summary alone.
* **Read-only by construction.** Server keys can only read. An agent exploring your project can't mutate or delete anything.

## The three ingredients

<Steps>
  <Step title="A server key">
    Create one in the dashboard under your project's API keys — see
    [Authentication](/api/authentication). Use a dedicated key per agent so you
    can revoke it independently.
  </Step>

  <Step title="The llms.txt brief">
    [`https://api.mirador.org/llms.txt`](https://api.mirador.org/llms.txt)
    documents the auth scheme, every endpoint, the filter grammar, pagination,
    and response shapes — enough for an agent to query Mirador with no other
    context. Paste it into the agent's context or let the agent fetch it (the
    endpoint requires no key).
  </Step>

  <Step title="A question">
    Ask in plain English. Good questions name a time window and an outcome —
    "why are errors up in the last 24 hours" gives the agent a concrete
    comparison to run.
  </Step>
</Steps>

## What an investigation looks like

For a question like *"why are errors up in the past 24 hours?"*, a well-briefed agent typically:

1. **Establishes the baseline** — counts error traces in the last 24 hours vs. the prior 24 hours using `filter=severity="error"` with `since`/`until` windows.
2. **Discovers the field universe** — lists tags and attribute keys so the next step slices along dimensions that actually exist.
3. **Finds the concentration** — re-counts errors sliced by tag, attribute value, or trace name to find where the increase is concentrated (one chain? one country? one flow?).
4. **Drills into evidence** — pulls the full event timelines of a few representative failing traces and reads the actual error events.
5. **Reports with pointers** — summarizes the likely cause and links the specific `trace_id`s to investigate in the dashboard.

The [worked investigation](/ai/investigating-with-ai) walks through this end to end with real requests and responses.

## Next Steps

<CardGroup cols={2}>
  <Card title="Connect an agent" icon="plug" href="/ai/connecting-an-agent">
    Wire up Claude Code, a custom agent, or an incident bot
  </Card>

  <Card title="Worked investigation" icon="magnifying-glass-chart" href="/ai/investigating-with-ai">
    "Why are errors up in the past 24 hours?" — step by step
  </Card>

  <Card title="REST API overview" icon="server" href="/api/overview">
    The endpoints agents query
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Create and manage server keys
  </Card>
</CardGroup>