Card

The Card API manages questions in Metabase. Cards represent saved questions that can be displayed as visualizations, added to dashboards, or executed to retrieve data. This API includes 16 endpoints.

List cards

Get a list of all cards (questions) you have access to.

GET /api/card

curl -X GET \
  https://your-metabase.com/api/card \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Response

[
  {
    "id": 1,
    "name": "Total Orders",
    "description": "Count of all orders",
    "display": "scalar",
    "query_type": "query",
    "database_id": 1,
    "collection_id": 5,
    "created_at": "2024-01-15T10:00:00Z"
  }
]

Get card

Get details about a specific card by ID.

GET /api/card/{id}

curl -X GET \
  https://your-metabase.com/api/card/1 \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Parameters

integer

required

Card ID or NanoID string

legacy-mbql

boolean

Return query in MBQL 4 format instead of MBQL 5 (default: false)

Response

integer

Card ID

name

string

Card name

description

string

Card description

display

string

Visualization type (table, bar, line, pie, scalar, etc.)

dataset_query

object

The query definition (MBQL or native SQL)

visualization_settings

object

Display settings for the visualization

result_metadata

array

Metadata about result columns

collection_id

integer

ID of the collection containing this card

Create card

Create a new card (question).

POST /api/card

curl -X POST \
  https://your-metabase.com/api/card \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "name": "New Question",
    "display": "table",
    "visualization_settings": {},
    "dataset_query": {
      "type": "query",
      "database": 1,
      "query": {
        "source-table": 5
      }
    }
  }'

Request body

name

string

required

Question name

dataset_query

object

required

Query definition (MBQL or native)For MBQL queries:

{
  "type": "query",
  "database": 1,
  "query": {
    "source-table": 5
  }
}

For native SQL:

{
  "type": "native",
  "database": 1,
  "native": {
    "query": "SELECT * FROM orders"
  }
}

display

string

required

Visualization type (table, bar, line, pie, scalar, etc.)

visualization_settings

object

required

Visualization configuration (can be empty object)

description

string

Card description

collection_id

integer

Collection to save the card in

type

string

Card type: “question” or “model” (default: “question”)

parameters

array

Template tag parameters for the question

Update card

Update an existing card.

PUT /api/card/{id}

curl -X PUT \
  https://your-metabase.com/api/card/1 \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "name": "Updated Question Name",
    "description": "Updated description"
  }'

Parameters

integer

required

Card ID

Request body

All fields are optional. Only include fields you want to update.

name

string

Updated card name

description

string

Updated description

dataset_query

object

Updated query definition

display

string

Updated visualization type

visualization_settings

object

Updated visualization settings

collection_id

integer

Move to a different collection

archived

boolean

Archive or unarchive the card

Delete card

Permanently delete a card.

DELETE /api/card/{id}

curl -X DELETE \
  https://your-metabase.com/api/card/1 \
  -H 'X-Metabase-Session: SESSION_TOKEN'

This permanently deletes the card. To soft delete (archive), use PUT /api/card/{id} with "archived": true.

Execute card query

Run the query for a card and get results.

POST /api/card/{card-id}/query

curl -X POST \
  https://your-metabase.com/api/card/1/query \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "ignore_cache": false
  }'

Parameters

card-id

integer

required

Card ID or NanoID

Request body

ignore_cache

boolean

Skip cached results and run fresh query (default: false)

dashboard_id

integer

Dashboard context if running from a dashboard

collection_preview

boolean

Whether this is a collection preview query

Response

data

object

Query results

rows - Array of result rows
cols - Array of column metadata
rows_truncated - Number of truncated rows if result was limited

status

string

Query status (“completed”, “failed”, etc.)

row_count

integer

Number of rows returned

running_time

integer

Query execution time in milliseconds

Download query results

Execute a card query and download results in a specific format.

POST /api/card/{card-id}/query/{export-format}

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

Parameters

card-id

integer

required

Card ID

export-format

string

required

Export format: csv, xlsx, or json

Request body

format_rows

boolean

Apply formatting to cell values (default: false)

pivot_results

boolean

Pivot the results (default: false)

parameters

array

Parameter values for the query

Response

Returns file data in the requested format with appropriate content-type header.

Copy card

Create a copy of an existing card.

POST /api/card/{id}/copy

curl -X POST \
  https://your-metabase.com/api/card/1/copy \
  -H 'X-Metabase-Session: SESSION_TOKEN'

The copied card will be named “Copy of [original name]” and will be saved to the same collection.

Get card dashboards

Get a list of dashboards where this card appears.

GET /api/card/{id}/dashboards

curl -X GET \
  https://your-metabase.com/api/card/1/dashboards \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Response

[
  {
    "id": 5,
    "name": "Sales Dashboard"
  },
  {
    "id": 12,
    "name": "Executive Overview"
  }
]

Get query metadata

Get metadata needed to build/edit a card’s query.

GET /api/card/{id}/query_metadata

curl -X GET \
  https://your-metabase.com/api/card/1/query_metadata \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Response

Returns database metadata, table info, and field definitions needed for the query builder.

Create public link

Generate a public sharing link for a card.

POST /api/card/{card-id}/public_link

curl -X POST \
  https://your-metabase.com/api/card/1/public_link \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Public sharing must be enabled in instance settings. Requires admin permissions.

Response

{
  "uuid": "110c3d96-ff3a-4ec6-9a82-7c2d5e073fa2"
}

The card can be accessed at /public/question/{uuid}.

Delete public link

Remove the public sharing link for a card.

DELETE /api/card/{card-id}/public_link

curl -X DELETE \
  https://your-metabase.com/api/card/1/public_link \
  -H 'X-Metabase-Session: SESSION_TOKEN'

List embeddable cards

Get all cards that can be embedded.

GET /api/card/embeddable

curl -X GET \
  https://your-metabase.com/api/card/embeddable \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Returns cards where enable_embedding is true.

Parameter values

Get parameter values

Fetch possible values for a card parameter.

GET /api/card/{card-id}/params/{param-key}/values

curl -X GET \
  https://your-metabase.com/api/card/1/params/category/values \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Search parameter values

Search for parameter values matching a query.

GET /api/card/{card-id}/params/{param-key}/search/{query}

curl -X GET \
  https://your-metabase.com/api/card/1/params/category/search/electronics \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Results are limited to the first 1000 matches.

Overview

Core Resources

User Management

Advanced

List cards

Response

Get card

Parameters

Response

Create card

Request body

Update card

Parameters

Request body

Delete card

Execute card query

Parameters

Request body

Response

Download query results

Parameters

Request body

Response

Copy card

Get card dashboards

Response

Get query metadata

Response

Create public link

Response

Delete public link

List embeddable cards

Parameter values

Get parameter values

Search parameter values

Overview

Core Resources

User Management

Advanced

Documentation Index

​List cards

​Response

​Get card

​Parameters

​Response

​Create card

​Request body

​Update card

​Parameters

​Request body

​Delete card

​Execute card query

​Parameters

​Request body

​Response

​Download query results

​Parameters

​Request body

​Response

​Copy card

​Get card dashboards

​Response

​Get query metadata

​Response

​Public sharing

​Create public link

​Response

​Delete public link

​List embeddable cards

​Parameter values

​Get parameter values

​Search parameter values

List cards

Response

Get card

Parameters

Response

Create card

Request body

Update card

Parameters

Request body

Delete card

Execute card query

Parameters

Request body

Response

Download query results

Parameters

Request body

Response

Copy card

Get card dashboards

Response

Get query metadata

Response

Public sharing

Create public link

Response

Delete public link

List embeddable cards

Parameter values

Get parameter values

Search parameter values