Using Metabase with Dynamic Content

The Metabase data source integration is currently in beta. Contact your Technical Account Manager for access.

Matik's Metabase integration lets you pull data directly from your Metabase dashboards and questions into your dynamic content. You can insert Metabase visualizations as screenshot images, extract tabular data from questions, or pull single values for text-based content — all without having to recreate your Metabase work in another tool.

Connecting Metabase as a Data Source

To connect Matik to your Metabase instance, you'll need to provide three pieces of information, plus an optional SSH tunnel configuration.

Required Configuration

Metabase Base URL: The URL of your Metabase instance — the same URL you see in your browser when you visit Metabase. Must include the protocol (e.g., https://metabase.yourcompany.com).
API Key: A Metabase API key used to authenticate all requests. You can find or generate one in your Metabase instance under Admin → Settings → API Keys.
Embedding Secret Key: Required for generating secure, signed embed previews and screenshots of dashboards and questions. Find this in your Metabase instance under Admin → Settings → Static Embedding → Embedding secret key.

Dashboard & Question setup

There are some additional required steps to make dashboards and questions usable in Matik:

Publish desired dashboards and questions as static embeds: Any dashboard or question you want to use in Matik must be published as a Static Embed. To do this:
1. On each dashboard or question, go to Sharing > Embed
2. Under "You will need to publish this dashboard before you can embed it in another application,” click the "Publish" button in the top right.
(If using parameters) Ensure they are editable in the static embed: In Embed Settings, go to Parameters, and ensure each parameter you want to use is set to ‘Editable.’ Matik sets parameter values through the embed URL, so parameters set to ‘Locked’ cannot be changed from Matik.

Publishing as a static embed is only needed for Image DC and for the preview in the dynamic content form. Table, Chart, and Text DC run the question through the Metabase API and do not require embedding.

Optional: SSH Tunnel

If your Metabase instance is hosted within a private network or VPC, Matik can securely connect through a bastion server using an SSH tunnel. When enabled, Matik routes all Metabase API requests through the tunnel. You'll need to provide:

the SSH host
port
username
private key.

Important: when configuring Metabase dynamic content through an embedded browser view, the connection is made from the user’s browser, not through Matik’s backend tunnel. Therefore, the user must be on their corporate private network with direct access to Metabase. Additionally, the Metabase host must be served over HTTPS to comply with Matik’s Content Security Policy.

Testing the Connection

After entering your credentials, click Test Connection to verify that Matik can reach your Metabase instance. Matik will attempt to connect using your API key and confirm access. If the test fails, see the Troubleshooting section below for common error messages and resolutions.

Permissions & Access

Matik uses your API key's permissions to determine which collections, dashboards, and questions are accessible. The content visible in Matik directly reflects what that API key can access in your Metabase instance.

We recommend creating a dedicated API key for the Matik integration and scoping its permissions to only the collections and dashboards that need to be used in Matik. This keeps the content selection experience clean and avoids exposing unnecessary data.

What Matik Can Use from Metabase

Matik works with dashboards and questions. Other Metabase object types are not supported as sources for dynamic content:

Questions (also called cards) work with every DC type.
Dashboards work with Image DC only.
Metrics, models, and documents are not supported. If the content you need lives in one of these, save it as a question first.

A question can live in a collection or be saved directly inside a dashboard. Both appear in the Question dropdown. Questions saved inside a dashboard are listed with the dashboard name after them, for example Qualified Pipeline (Q3 QBR), so you can tell them apart from similarly named questions in the collection.

Pulling Data and Images from Metabase

Matik supports two ways to pull data from Metabase, depending on whether you want to work with a dashboard or an individual question.

	Dashboard	Question
How data is pulled	Captures a screenshot of the full dashboard or a specific card via a secure signed embed.	Executes the question's query and returns the results as tabular data, or captures a screenshot of the question's visualization.
Supported DC types	Image only	Image, Table, Chart, Text, Recipient, Sender
Parameter behavior	Parameters are pulled from the dashboard's filter definitions. Supports multi-tab dashboards with per-tab parameters.	Parameters are pulled from the question's own parameter definitions.

To create Metabase dynamic content, follow the steps in the form:

Select a Collection — the organizational folder in Metabase that contains your dashboards and questions.
Select a Dashboard or Question, depending on the form type you chose.
- For dashboards: if the dashboard has multiple tabs, you can select which tab to use. (Note: Each tab has its own set of parameters, and switching tabs will clear any previously configured parameters since they may differ between tabs. When capturing screenshots, only the content from the selected tab is included.)
- For dashboards with Image DC: you can choose to capture the entire dashboard or select a specific card.
Configure parameters, output settings, and fields to return as needed.

Dynamic Content Types

Image

Returns a screenshot of a Metabase dashboard or question. Matik uses a secure signed embed URL to render the content and capture it as a PNG image.

For dashboards, you can capture the entire dashboard (including content below the fold) or select a specific card to capture. For dashboards with multiple tabs, select the tab you want before capturing.
For questions, Matik captures a screenshot of the question's visualization.

You can use the Image Resolution settings to configure image dimensions.

Default image dimensions are 1024 × 768 for dashboards and 800 × 600 for questions.
You can customize the image dimensions by setting the desired width and height in pixels, and optionally lock the aspect ratio.
To preview your chart at the specified dimensions, use Test API.

Table

Returns the tabular data from a Metabase question as rows and columns. Matik executes the question's query and extracts the results, including column headers. Use this when you want to power a native table with Metabase data.

Chart

Returns data in the same tabular format as Table DC, which Matik then uses for chart rendering within your template. Use this when you want to pull Metabase data with a native chart object.

Text

Returns a single value extracted from a question's results. This is useful for inserting individual metrics or summary statistics.

Filtering Data on Generation

Metabase dashboards and questions can have parameters that control the data they return. Matik automatically detects available parameters when you select a dashboard or question and displays them in the configuration form. Matik can work with parameters in two ways:

Use Matik inputs: use this when you want fine admin control over how parameters are populated.
Let end users filter on the dashboard: use this when you simply want to let the end users filter directly on whatever filters are included in Metabase

Note: these approaches are mutually exclusive. You must choose one or the other — either map parameters to Matik inputs, or expose them directly to end users.

Parameters vs. Dashboard Filters

These look similar in Metabase but behave differently in Matik, and the difference is the most common reason a question comes back unfiltered.

Question parameters are defined on the question itself. In a SQL question they are the variables you write with double curly braces, for example {{account_name}}. These are the parameters Matik can set for Table, Chart, and Text DC.
Dashboard filters are defined on the dashboard and mapped to the cards on it. Matik can use these for Image DC of a dashboard, but they do not apply to Table, Chart, or Text DC, because Matik runs the question on its own rather than through the dashboard.

Only SQL questions can have parameters. Questions built with the visual query builder (the notebook editor) cannot, so there is nothing for Matik to filter on. To make one filterable from Matik, convert it to SQL and add a variable or field filter for each value you want to pass in.

To check whether a question has parameters, open the question itself in Metabase and look for filter widgets above the results. If the only filters you see are at the top of a dashboard, those are dashboard filters, not question parameters.

Filtering with Matik Inputs

You can set parameter values in two ways:

Matik input references: Use the &:input_name syntax to dynamically pass a value from a Matik input at generation time. For example, setting a "Customer" parameter to &:account_name means the end user provides the account name when generating content, and Matik passes it through to Metabase.
Static values: Enter a fixed value directly (e.g., Acme Corp or 2025). This value will be used every time the dynamic content runs.

Because parameters support Matik input references, you can create dynamic content that pulls different data for each recipient or generation run — for example, filtering a dashboard to a specific account, region, or date range.

When you map parameters to Matik inputs, Matik hides Metabase's own filter widgets in the preview and uses its own parameter fields instead. Only the values set in Matik affect the generated content, so changing a filter inside the embed would have no effect.

Supported Parameters

Metabase Parameter Type	Matik Input Type	Notes
Text	String
Number	Number
Date	Date	Formatted as YYYY-MM-DD
Date Range	Date Range	Tilde-separated format: YYYY-MM-DD~YYYY-MM-DD
Boolean	Boolean	Handled as true/false

Previewing with Parameters

After setting parameter values, click Apply to refresh the embed preview with those values. If any parameters reference Matik inputs, you'll be prompted to enter sample values so the preview can render with real data.

Allow End Users to Filter on the Dashboard

You can let end users view and set dashboard parameters directly at generation time by enabling the "Let end users view and set dashboard parameters" checkbox. When enabled, the dashboard's filters are exposed to the end user in the generation form, giving them interactive control over the data.

Best Practices

Scope your API key. Create a dedicated API key for Matik and limit its access to only the collections and dashboards your team needs. This improves security and keeps the content selection experience manageable.
Keep dashboards simple for screenshots. Complex dashboards with many cards or heavy visualizations may take longer to render as screenshots. If screenshot generation is slow, consider targeting a specific card rather than the full dashboard.
Write questions in SQL if they need to be filtered. Add a variable or field filter for each value you want to pass from Matik, and give it a clear name so it is easy to map to a Matik input.
Give parameters default values. A question that runs on its own in Metabase will also run in Matik, which makes previews and testing easier.

Limitations

API keys can be rotated or revoked. Matik authenticates with an API key, which does not expire on its own, but it stops working if it is deleted or rotated in Metabase. If your connection fails unexpectedly, generate a new key and update it in Matik.
Embedding requires Static Embedding to be enabled. The Embedding Secret Key is required for dashboard and question previews and for Image DC screenshot generation. Make sure Static Embedding is enabled in your Metabase admin settings.
Dashboard & questions must be published as Static Embeds. Any dashboard or question you wish to use for Image DC or previews must be published as a Static Embed. Any parameters you wish to use should be set to Editable. Parameters set to Locked cannot be changed from Matik.
Cross-domain restrictions. Depending on your browser's security policies and Metabase's session cookie configuration (SameSite settings), embed previews may not render in certain environments.
Only SQL questions can be filtered from Matik. Questions built with the query builder have no parameters, so Matik has no values to pass in.
Dashboard filters only apply to Image DC. Table, Chart, and Text DC run the question directly, so any filtering has to come from the question's own parameters.
Metrics, models, and documents are not supported. Save the content you need as a question in a collection or dashboard.

Troubleshooting

Error or Issue	Why It Happens	How to Resolve
Authentication failed. Please check your API key and ensure it's valid.	The API key is incorrect, expired, or has been revoked.	Generate a new API key in Metabase under Admin → Settings → API Keys, and update it in Matik.
API key does not have sufficient permissions. Please check your API key permissions in Metabase admin settings.	The API key doesn't have access to the requested resource.	Check your API key's permission scope in Metabase admin settings. Ensure it has access to the collections, dashboards, and questions you need.
API key is invalid or has been deleted. Please generate a new API key in your Metabase instance.	The API key was deleted or deactivated in Metabase.	Generate a new API key in your Metabase instance and update the data source configuration in Matik.
Metabase instance not found. Please check your base URL and ensure Metabase is running.	The base URL is incorrect or Metabase is not accessible from Matik.	Verify the base URL matches your Metabase instance. If Metabase is behind a VPN or private network, configure an SSH tunnel.
Unable to connect to Metabase. Please check your base URL and ensure Metabase is running.	Network connectivity issue between Matik and your Metabase instance.	Check that the base URL is correct and that Metabase is running. If using a VPN, ensure Matik's IP addresses are whitelisted or configure an SSH tunnel.
Base URL and API key are required.	One or both required fields were left blank when testing the connection.	Ensure both the Metabase Base URL and API Key fields are filled in before testing the connection.
Connection to Metabase timed out. Please check your network connection and try again.	Metabase did not respond within the timeout period.	Check your network connectivity and ensure Metabase is responsive. If the instance is under heavy load, try again later.
Metabase server error. Please try again later or contact your Metabase administrator.	An internal error occurred on the Metabase server.	Try again later. If the issue persists, contact your Metabase administrator to check server logs.
A question you expect is missing from the Question dropdown.	The question is in a different collection, the API key cannot see it, or it is a metric, model, or document rather than a question.	Confirm which collection the question is saved in, check the API key's permissions, and make sure the item is saved as a question. Questions saved inside a dashboard appear with the dashboard name after them.
No parameters appear after you select a question.	The question has no parameters of its own. Query builder questions cannot have them, and dashboard filters do not count.	Open the question in Metabase and add a SQL variable or field filter for each value you want Matik to pass in.
Data comes back unfiltered even though the dashboard has filters.	For Table, Chart, and Text DC, Matik runs the question on its own, so dashboard filters are not applied.	Move the filter onto the question as a parameter, then map it to a Matik input or a static value.
You must specify a value for ...	A parameter in the static embed is set to Locked, which requires a value on every request.	Set the parameter to Editable in Embed settings. Matik supplies the value itself, so it does not need to be locked.