Dataset

Execute queries and retrieve data programmatically through the Metabase API

The Dataset API allows you to execute ad-hoc queries and retrieve data. This is the primary endpoint for running queries programmatically. The API includes 8 endpoints.

Execute query

Execute an ad-hoc query and retrieve results.

POST /api/dataset

curl

curl -X POST \
  https://your-metabase.com/api/dataset \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "database": 1,
    "type": "query",
    "query": {
      "source-table": 5,
      "limit": 10
    }
  }'

Request body

database · integer

Database ID to query (optional for saved question queries)

type · string · required

Query type: “query” (MBQL) or “native” (SQL)

query · object · required

MBQL query object

Example MBQL query:

{
  "source-table": 5,
  "aggregation": [["count"]],
  "breakout": [["field", 12, null]],
  "limit": 100
}

native · object

Native SQL query (when type is “native”)

Example:

{
  "query": "SELECT * FROM orders LIMIT 100",
  "template-tags": {}
}

parameters · array

Parameter values for template tags

constraints · object

Query constraints like max results

Response

data · object

Query results

• rows - Array of result rows
• cols - Array of column metadata
• rows_truncated - Number of rows truncated (if limited)

database_id · integer

Database that was queried

status · string

Query status: “completed”, “failed”, etc.

row_count · integer

Number of rows returned

running_time · integer

Query execution time in milliseconds

json_query · object

The query that was executed

{
  "data": {
    "rows": [
      [1, "Product A", 29.99],
      [2, "Product B", 49.99]
    ],
    "cols": [
      {
        "name": "ID",
        "base_type": "type/Integer",
        "display_name": "ID"
      },
      {
        "name": "NAME",
        "base_type": "type/Text",
        "display_name": "Name"
      },
      {
        "name": "PRICE",
        "base_type": "type/Float",
        "display_name": "Price"
      }
    ]
  },
  "status": "completed",
  "row_count": 2,
  "running_time": 145
}

This endpoint does not use query caching. Results are always fresh from the database.

Export query results

Execute a query and download results in a specific format.

POST /api/dataset/{export-format}

curl

curl -X POST \
  https://your-metabase.com/api/dataset/csv \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "query": {
      "database": 1,
      "type": "query",
      "query": {
        "source-table": 5
      }
    },
    "visualization_settings": {},
    "format_rows": true,
    "pivot_results": false
  }' \
  -o results.csv

Parameters

export-format · string · required

Export format: csv, xlsx, or json

Request body

query · object · required

Query object with database, type, and query/native fields

visualization_settings · object · required

Visualization settings (can be empty object)

format_rows · boolean

Apply cell formatting to values (default: false)

pivot_results · boolean

Pivot the results (default: false)

Response

Returns file data with appropriate content-type:

• CSV: text/csv
• XLSX: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
• JSON: application/json

Get query metadata

Get metadata needed to construct a query.

POST /api/dataset/query_metadata

curl

curl -X POST \
  https://your-metabase.com/api/dataset/query_metadata \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "database": 1
  }'

Request body

database · integer · required

Database ID to get metadata for

Response

Returns database metadata including tables, fields, and foreign key relationships needed for building queries.

Convert to native query

Convert an MBQL query to native SQL.

POST /api/dataset/native

curl

curl -X POST \
  https://your-metabase.com/api/dataset/native \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "database": 1,
    "type": "query",
    "query": {
      "source-table": 5,
      "limit": 10
    },
    "pretty": true
  }'

Request body

database · integer · required

Database ID (minimum: 1)

type · string · required

Query type (“query”)

query · object · required

MBQL query to convert

pretty · boolean

Format the SQL with indentation (default: true)

Response

query · string

Native SQL query

{
  "query": "SELECT * FROM orders LIMIT 10"
}

Get parameter values

Get possible values for a query parameter.

POST /api/dataset/parameter/values

curl

curl -X POST \
  https://your-metabase.com/api/dataset/parameter/values \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "parameter": {
      "id": "param1",
      "type": "category",
      "target": ["dimension", ["field", 5, null]]
    },
    "field_ids": [5]
  }'

Request body

parameter · object · required

Parameter definition with id, type, and target

field_ids · array

Field IDs to get values from

Response

Returns an array of possible parameter values.

Search parameter values

Search for parameter values matching a query string.

POST /api/dataset/parameter/search/{query}

curl

curl -X POST \
  https://your-metabase.com/api/dataset/parameter/search/electronics \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "parameter": {
      "id": "category",
      "type": "category"
    }
  }'

Parameters

query · string · required

Search query (minimum: 1 character)

Request body

parameter · object · required

Parameter definition

field_ids · array

Field IDs to search

Get parameter remapping

Get remapped values for a parameter.

POST /api/dataset/parameter/remapping

curl

curl -X POST \
  https://your-metabase.com/api/dataset/parameter/remapping \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "parameter": {
      "id": "param1",
      "type": "category"
    },
    "value": 123
  }'

Request body

parameter · object · required

Parameter definition

value · required

Value to get remapping for

field_ids · array

Field IDs

Generate pivot table

Generate a pivoted dataset for a query.

POST /api/dataset/pivot

curl

curl -X POST \
  https://your-metabase.com/api/dataset/pivot \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "database": 1,
    "type": "query",
    "query": {
      "source-table": 5,
      "aggregation": [["count"]],
      "breakout": [["field", 12, null], ["field", 13, null]]
    }
  }'

Request body

database · integer · required

Database ID (minimum: 1)

type · string · required

Query type

query · object · required

Query with breakout fields for pivoting

Response

Returns pivoted data with row and column groupings.

Use pivot queries for creating cross-tab reports and matrices.