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:
- On each dashboard or question, go to Sharing > Embed
- 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.’
Optional: SSH Tunnel
If your Metabase instance is hosted within a private network or VPC, you can configure an SSH tunnel to allow Matik to connect securely through a bastion host. When enabled, Matik routes all Metabase API requests through the tunnel. You'll need to provide the SSH host, port, username, and private key.
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.
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 (filters) 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.
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.
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.
Limitations
- API session expiration. Metabase API sessions expire after 14 days by default (configurable via MB_SESSION_AGE in Metabase). If your connection fails unexpectedly, the API key or session may need to be refreshed.
- 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 with Matik must be published as a Static Embed. Any parameters you wish to use should be set to Editable.
- 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.
Troubleshooting
| Error Message | 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. |
Comments
0 comments
Article is closed for comments.