Redash Agent

Drive a Redash instance over its REST API: introspect data sources, write and run queries, create visualizations, and assemble dashboards. A bundled zero-dependency Python helper (redash.py, stdlib only) wraps every endpoint and prints JSON so you can chain steps.

Prerequisites

Two environment variables must be set before any command:

export REDASH_URL="https://redash.example.com"   # your instance, no trailing slash
export REDASH_API_KEY="<user API key>"

• Get the user API key from Redash → top-right avatar → Settings → Account → API Key. A user key inherits that user's permissions and is required to create or modify anything.
• A per-query API key (shown on a query page) only reads that one query's results — not enough for this skill.
• python3 must be on PATH (stdlib only — no pip install needed).
• If the instance sits behind Cloudflare/a WAF, a 403 with error code: 1010 means the default agent is banned. The helper already sends a normal User-Agent; override it with REDASH_USER_AGENT (e.g. a browser string) if a stricter rule still blocks you.

Always run test first to confirm credentials before doing real work:

python3 redash.py test

If the user hasn't given you a URL or key, ask for them. Never hardcode them into files; they're secrets.

How Redash objects fit together

data source ──> query (SQL) ──> visualization(s) ──┐
                                                    ├─> widget ──> dashboard
                              text ─────────────────┘

• A query holds SQL + a data source. Running it produces a query result.
• A visualization is a view of a query's result (TABLE, CHART, COUNTER, …). A query can have several.
• A dashboard is a grid of widgets. Each widget embeds one visualization (or is a free text/markdown box).
• New queries and dashboards are created as drafts (is_draft: true) — invisible in lists until published.

The commands

Run each from the skill directory, e.g. python3 redash.py data-sources.

Workflow A — write and run a query

1. Find the data source. data-sources → note the id the user means. If unsure which, ask.
2. Learn the schema. schema --data-source-id N → use real table/column names. Don't guess.
3. Validate the SQL with exec-sql (nothing saved yet) so you catch errors before committing:

   python3 redash.py exec-sql --data-source-id 1 --sql "SELECT count(*) FROM users"

4. Save it once it works:

   python3 redash.py create-query --name "Active users" \
     --sql "SELECT date, count(*) FROM users GROUP BY 1" \
     --data-source-id 1 --publish

   Capture the returned id — you need it for visualizations and widgets.

Workflow B — build a dashboard

A widget needs a visualization id, and a query has no chart visualization by default (only an implicit table). So the order is: query → visualization → dashboard → widgets → publish.

1. Create + publish each query (Workflow A). Keep each query id.
2. Decide the visualization per query, then confirm. Look at the result columns and propose a fit (table / line / bar / counter) with the intended axis mapping, and confirm with the user before creating it — don't silently pick. Then create it, capturing each returned id:

   python3 redash.py create-viz --query-id 42 --type CHART --name "Signups over time" \
     --options '{"globalSeriesType":"line","columnMapping":{"date":"x","count":"y"}}'

   For a plain table widget, you can reuse the query's built-in table viz — get-query --id 42 and read visualizations[].id (the one with "type":"TABLE").
3. Create the dashboard and capture id + slug:

   python3 redash.py create-dashboard --name "Growth"

4. Add a widget per visualization, laying them out on the grid (check its width first — see the note below):

   python3 redash.py add-widget --dashboard-id 7 --viz-id 99 \
     --col 0 --row 0 --size-x 3 --size-y 8
   python3 redash.py add-widget --dashboard-id 7 --viz-id 100 \
     --col 3 --row 0 --size-x 3 --size-y 8

   • Check the grid width first. It's not fixed — Redash dashboards are commonly 6 or 12 columns. When adding to an existing dashboard, get-dashboard --id and read the largest sizeX/col+sizeX among current widgets to learn the width, then match it (a full-width widget = that width). For a brand-new dashboard, 6 is the safe default.
   • Place new widgets below existing ones. Compute the next free row as max(row + sizeY) over current widgets so you don't overlap.
   • Increment row (by the previous size-y) to start a new row.
   • Text/markdown box: omit --viz-id, pass --text "## Section".
5. Publish so it appears for others:

   python3 redash.py publish-dashboard --id 7

6. Report the dashboard URL: $REDASH_URL/dashboards/<id>-<slug> (the URL path is the id followed by the slug, e.g. /dashboards/7-growth).

Visualization --options reference

create-viz takes a --type and a JSON --options blob whose shape depends on the type. Common ones:

• TABLE — {} works (Redash auto-derives columns). Every query already has a table viz, so you rarely need to create one.
• CHART — set the chart kind and map result columns to axes:

  {
    "globalSeriesType": "line",
    "columnMapping": {"<x_column>": "x", "<y_column>": "y"},
    "seriesOptions": {},
    "legend": {"enabled": true}
  }

  globalSeriesType ∈ line column area pie scatter bubble heatmap. For a grouped series add the grouping column with "series" in columnMapping.
• COUNTER — a single big number:

  {"counterColName": "<value_column>", "rowNumber": 1, "counterLabel": "Total"}

• PIVOT — {}; configure in UI, or pass pivot config if known.

When unsure of a chart option's exact key, create the viz with a minimal options blob, then tell the user they can fine-tune it in the Redash UI — the API and UI edit the same object.

Parameterized queries

If the SQL contains {{ param }} placeholders, declare them in query --options:

{"parameters": [{"name": "country", "type": "text", "title": "Country"}]}

Then run-query accepts values — extend the helper or run via the UI for parameter entry. For ad-hoc runs, inline the value instead.

Pitfalls — don't repeat these

• Don't skip test. A wrong URL or a per-query key (vs. user key) fails confusingly later. Verify first.
• Don't invent table/column names. Always pull schema first; Redash errors are opaque.
• Don't forget to publish. Freshly created queries and dashboards are drafts and won't show in lists until --publish / publish-dashboard.
• Don't expect a query to have a chart automatically. Only an implicit TABLE viz exists; you must create-viz for any chart before it can go in a widget.
• Don't overflow the grid width. col + size-x must stay ≤ the dashboard's column count (6 or 12 — read it off existing widgets; see Workflow B step 4), or widgets overlap.
• Don't add a widget with a stale viz id. Use the id returned by create-viz (or from get-query), not the query id.
• Don't hardcode secrets. Read REDASH_URL/REDASH_API_KEY from the environment; if missing, ask the user.
• Don't poll yourself. run-query/exec-sql/schema already poll the job to completion and return final data. (schema returns a refresh job on a cold cache — the helper waits and re-fetches.)
• Fetch dashboards by numeric id, not slug. On 26.x a slug passed to get-dashboard returns HTTP 500 (id-only routing). Run dashboards to resolve a name/slug to its id first. (The id is also the leading number in a dashboard URL like /dashboards/7-growth.)
• Don't assume a 6-column grid. Width varies per dashboard (6 or 12 are both common). Read it off existing widgets before placing new ones, or they'll overlap or leave gaps.

Verified end-to-end against Redash 26.3.0 (MySQL data source): data-sources → schema → exec-sql → create-query → run-query → create-viz (CHART) → create-dashboard → add-widget → publish → delete all succeeded.

Keep this skill focused: introspect, query, visualize, and assemble dashboards via the Redash API — leave deep chart styling to the UI.