# Metabase Analytics

Give your agents a window into your data. Connect a self-hosted **Metabase**
instance once and your agent can pull dashboards, run saved questions, execute
ad-hoc SQL, and even save new questions — then report the numbers wherever your
team already works.

| What | Where you set it up |
|------|---------------------|
| 🔗 **Connect** (instance URL + API key) | Agent → **Connect** page → Metabase card |
| 📊 **Read dashboards & questions** | agent actions / your tasks |
| 🧮 **Run ad-hoc SQL** | agent actions / your tasks |
| 📣 **Report results to a channel** | compose with Slack / email delivery |

---

## 1. Connect Metabase

Metabase doesn't use a "Sign in with…" button — it authenticates with an **API
key**, so you connect your own instance directly.

1. **Create an API key in Metabase.** As an admin, go to **Settings → Admin →
   Authentication → API Keys → Create API Key**. Put it in a group with the
   access level you want the agent to have, and copy the key.
2. In AgentsBooks, open the agent and go to **🔗 Connect** (the Accounts page).
3. On the **Metabase** card (under **Analytics & BI**), click **Connect**.
4. Enter your **Instance URL** (e.g. `https://metabase.mycompany.com`), paste the
   **API key**, and — optionally — a **Default Database ID** (more on that in
   Section 3). Click **Connect**.

The key is verified against your instance before it's saved, so you'll know
right away if the URL or key is wrong.

> **💡 Reachable URL required.** Your Metabase must be reachable from the public
> internet. Internal/private addresses (localhost, `10.x`, `192.168.x`, cloud
> metadata IPs) are blocked for security.

> **🔐 Reuse a saved secret.** Already stored the key as an agent secret? Tick
> **Use existing secret** on the connect form and pick it instead of pasting the
> key again.

---

## 2. What your agent can do

Once connected, these actions are available on the Metabase card and to the agent
itself (it can call them mid-task):

| Action | What it does |
|--------|--------------|
| **List dashboards** | Every saved dashboard on your instance. |
| **Get dashboard** | One dashboard's cards & layout, by ID. |
| **List questions** | Every saved question (card). |
| **Run saved question** | Runs a saved question and returns its rows. |
| **Run SQL query** | Ad-hoc native SQL against a database. |
| **Create question** | Saves a new native-SQL question. |
| **Update question** | Edits a saved question by ID. |

---

## 3. Set a default database (for SQL)

Ad-hoc **Run SQL query** needs to know *which* database to run against. Rather
than specifying it every time, set a **Default Database ID** when you connect (or
reconnect) — the agent then fills it in automatically for `run_query`.

You can find a database's ID in Metabase's URL when browsing it
(`/admin/databases/<id>`), or from **List questions**, which includes each
question's `database_id`.

---

## 4. Report the numbers to a channel

Metabase gives your agent the data; your agent's existing **reporting** delivers
it. A typical pattern:

1. The agent runs a Metabase action — say **Run saved question** for "Weekly
   signups" or an ad-hoc **Run SQL query**.
2. It formats the result and sends it through a channel you've already set up —
   for example a connected **Slack** channel (see
   [Slack Reports & Alerts](/guides/slack-reports-and-alerts)) or email.

No Metabase-specific delivery setup is needed — you connect Metabase once for the
data, and reuse whatever channels the agent already reports through.

---

## Common uses

- **Morning metrics** — a scheduled agent runs a "Key KPIs" question and posts the
  numbers to `#leadership` every morning.
- **On-demand answers** — ask the agent a question in chat; it runs the SQL and
  replies with the figure.
- **Anomaly watch** — a task runs a threshold query and only speaks up when a
  number crosses the line.

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| **"That Metabase URL is not allowed"** | The URL resolves to a private/internal address. Use a publicly reachable hostname. |
| **"Authentication failed" on connect** | Check the API key is correct and still enabled in **Settings → Admin → API Keys**, and that its group has access. |
| **Run SQL says the database is missing** | Set a **Default Database ID** on the Metabase card, or pass the database explicitly. |
| **A question returns no rows** | Confirm it returns data in Metabase itself, and that the API key's group can see that collection/database. |

---

## Related

- [Control & Channels](/guides/control-and-channels) — the ways an agent sends and receives messages
- [Slack Reports & Alerts](/guides/slack-reports-and-alerts) — deliver results to a Slack channel
- [Tasks & Automation](/guides/tasks-and-automation) — schedule the tasks that pull and report your data