Managing Metabase

Metabase Management Skill

Manage and analyze Metabase questions, dashboards, database connections, and user activity via the Metabase API.

MANDATORY: Discovery-First Pattern

Always discover databases and collections before querying specific questions or dashboards.

Phase 1: Discovery

#!/bin/bash

metabase_api() {
    local method="${1:-GET}"
    local endpoint="$2"
    local data="${3:-}"

    if [ -n "$data" ]; then
        curl -s -X "$method" \
            -H "X-Metabase-Session: ${METABASE_SESSION_TOKEN}" \
            -H "Content-Type: application/json" \
            "${METABASE_URL}/api/${endpoint}" \
            -d "$data"
    else
        curl -s -X "$method" \
            -H "X-Metabase-Session: ${METABASE_SESSION_TOKEN}" \
            "${METABASE_URL}/api/${endpoint}"
    fi
}

echo "=== Databases ==="
metabase_api GET "database" | jq -r '
    .data[] | "\(.id)\t\(.name)\t\(.engine)\t\(if .is_sample then "SAMPLE" else "CUSTOM" end)"
' | column -t

echo ""
echo "=== Collections ==="
metabase_api GET "collection" | jq -r '
    .[] | select(.personal_owner_id == null) | "\(.id)\t\(.name)\t\(.location // "/")"
' | column -t | head -20

echo ""
echo "=== Recent Activity ==="
metabase_api GET "activity?limit=15" | jq -r '
    .[] | "\(.timestamp[0:16])\t\(.topic)\t\(.user?.common_name // "system")\t\(.model_id // "")"
' | column -t | head -15

Core Helper Functions

#!/bin/bash

metabase_api() {
    local method="${1:-GET}"
    local endpoint="$2"
    local data="${3:-}"

    if [ -n "$data" ]; then
        curl -s -X "$method" \
            -H "X-Metabase-Session: ${METABASE_SESSION_TOKEN}" \
            -H "Content-Type: application/json" \
            "${METABASE_URL}/api/${endpoint}" \
            -d "$data"
    else
        curl -s -X "$method" \
            -H "X-Metabase-Session: ${METABASE_SESSION_TOKEN}" \
            "${METABASE_URL}/api/${endpoint}"
    fi
}

# Authenticate and get session token if needed
metabase_login() {
    curl -s -X POST \
        -H "Content-Type: application/json" \
        "${METABASE_URL}/api/session" \
        -d "{\"username\": \"${METABASE_USER}\", \"password\": \"${METABASE_PASS}\"}" | jq -r '.id'
}

Output Rules

• TOKEN EFFICIENCY: Target ≤50 lines per output
• Use jq to extract key fields — never dump full question/dashboard definitions
• Filter collections to exclude personal folders unless specifically needed

Common Operations

Question (Saved Query) Management

#!/bin/bash
echo "=== Questions Summary ==="
metabase_api GET "card" | jq '
    {
        total: length,
        native_queries: [.[] | select(.dataset_query.type == "native")] | length,
        gui_queries: [.[] | select(.dataset_query.type == "query")] | length,
        archived: [.[] | select(.archived == true)] | length
    }'

echo ""
echo "=== Most Viewed Questions ==="
metabase_api GET "card" | jq -r '
    sort_by(-.view_count) | .[:15][] |
    "\(.id)\t\(.name[0:40])\t\(.view_count) views\t\(.database_id)\t\(.collection?.name // "root")"
' | column -t

echo ""
echo "=== Questions with Errors ==="
metabase_api GET "card" | jq -r '
    .[] | select(.last_query_start != null and .cache_invalidated_at != null) |
    select(.query_average_duration > 30000) |
    "\(.id)\t\(.name[0:40])\t\(.query_average_duration / 1000 | floor)s avg"
' | column -t | head -10

Dashboard Analysis

#!/bin/bash
DASHBOARD_ID="${1:?Dashboard ID required}"

echo "=== Dashboard Details ==="
metabase_api GET "dashboard/${DASHBOARD_ID}" | jq '{
    id: .id,
    name: .name,
    collection: .collection?.name,
    cards: (.dashcards | length),
    parameters: (.parameters | length),
    last_edit: .updated_at
}'

echo ""
echo "=== Dashboard Cards ==="
metabase_api GET "dashboard/${DASHBOARD_ID}" | jq -r '
    .dashcards[] | "\(.id)\t\(.card?.name // "text/heading")\t\(.card?.display // "N/A")\tsize=\(.size_x)x\(.size_y)"
' | column -t | head -20

echo ""
echo "=== Dashboard Parameters ==="
metabase_api GET "dashboard/${DASHBOARD_ID}" | jq -r '
    .parameters[] | "\(.name)\t\(.type)\t\(.default // "no default")"
' | column -t

Database Connection Health

#!/bin/bash
echo "=== Database Connection Status ==="
metabase_api GET "database" | jq -r '
    .data[] | "\(.id)\t\(.name)\t\(.engine)\t\(.details.host // "N/A")\t\(.details.port // "N/A")"
' | column -t

echo ""
echo "=== Sync Status ==="
metabase_api GET "database" | jq -r '
    .data[] | "\(.name)\tinitial_sync=\(.initial_sync_status)\tmetadata_sync=\(.metadata_sync_schedule // "auto")"
' | column -t

echo ""
echo "=== Database Tables ==="
DB_ID="${1:-}"
if [ -n "$DB_ID" ]; then
    metabase_api GET "database/${DB_ID}/metadata" | jq -r '
        .tables[] | select(.active == true) | "\(.schema // "public")\t\(.name)\t\(.rows // "?")\t\(.entity_type // "?")"
    ' | column -t | head -20
fi

Pulse and Subscription Management

#!/bin/bash
echo "=== Active Pulses ==="
metabase_api GET "pulse" | jq -r '
    .[] | select(.archived == false) | "\(.id)\t\(.name)\t\(.channels[0]?.channel_type // "?")\t\(.cards | length) cards"
' | column -t | head -15

echo ""
echo "=== Pulse Schedules ==="
metabase_api GET "pulse" | jq -r '
    .[] | select(.archived == false) |
    "\(.name)\t\(.channels[0]?.schedule_type // "?")\t\(.channels[0]?.schedule_hour // "?")\t\(.channels[0]?.recipients | length // 0) recipients"
' | column -t | head -15

echo ""
echo "=== Dashboard Subscriptions ==="
DASHBOARD_ID="${1:-}"
if [ -n "$DASHBOARD_ID" ]; then
    metabase_api GET "dashboard/${DASHBOARD_ID}/subscriptions" | jq -r '
        .[] | "\(.id)\t\(.channels[0]?.channel_type // "?")\t\(.channels[0]?.schedule_type // "?")"
    ' | column -t
fi

User Activity and Audit

#!/bin/bash
echo "=== Active Users ==="
metabase_api GET "user?status=active&limit=20" | jq -r '
    .data[] | "\(.id)\t\(.common_name)\t\(.email)\t\(.last_login[0:10] // "never")\t\(if .is_superuser then "ADMIN" else "USER" end)"
' | column -t | head -20

echo ""
echo "=== Recent Query Executions ==="
metabase_api GET "dataset" 2>/dev/null
metabase_api GET "activity?limit=20" | jq -r '
    .[] | select(.topic | test("query|card")) |
    "\(.timestamp[0:16])\t\(.topic)\t\(.user?.common_name // "?")\t\(.details?.name // .model_id // "?")"
' | column -t | head -15

Output Format

Present results as a structured report:

Managing Metabase Report
════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• Session tokens: Metabase sessions expire (default 14 days) — re-authenticate via POST /api/session if getting 401
• Card vs Question: In the API, "card" is the internal name for what the UI calls a "question" or "saved question"
• Native vs GUI queries: dataset_query.type is "native" for SQL or "query" for GUI builder — native queries bypass Metabase's query builder
• Collection permissions: Collections have group-based permissions — API results depend on the session user's access
• Database sync: Metabase syncs database metadata periodically — new tables may not appear until sync completes
• Query duration: query_average_duration is in milliseconds, not seconds — divide by 1000
• Pulse deprecation: Pulses are being replaced by Dashboard Subscriptions in newer versions — check both
• Embedding: Embedded questions/dashboards use signed JWTs — different auth flow than API tokens
• Caching: Metabase caches query results — stale results may be from cache, configurable per-database