Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/metabase/metabase/llms.txt

Use this file to discover all available pages before exploring further.

The Actions API enables you to perform write operations on your database through Metabase. Actions allow you to execute INSERT, UPDATE, and DELETE operations programmatically. This API includes 7 endpoints.

​
Actions overview

Actions in Metabase allow you to:
  • Create new database records
  • Update existing records
  • Delete records
  • Execute custom database operations
  • Trigger actions from dashboards and forms
Actions must be enabled in your database settings and require appropriate permissions.

​
List actions

Get all actions you have access to. 
GET /api/action

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

​
Response

[
  {
    "id": 1,
    "name": "Create Order",
    "description": "Insert a new order",
    "type": "implicit",
    "model_id": 5,
    "database_id": 1,
    "creator_id": 1,
    "created_at": "2024-01-15T10:00:00Z"
  }
]

​
Get action

Get details about a specific action. 
GET /api/action/{action-id}

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

​
Parameters

​
action-id
integer
required
Action ID

​
Response

​
id
integer
Action ID
​
name
string
Action name
​
description
string
Action description
​
type
string
Action type: “implicit”, “query”, or “http”
​
model_id
integer
Associated model/question ID
​
database_id
integer
Database ID for query actions
​
dataset_query
object
Query definition for query-based actions
​
parameters
array
Action parameters/inputs
​
visualization_settings
object
Form and button display settings

​
Create action

Create a new action. 
POST /api/action

curl -X POST \
  https://your-metabase.com/api/action \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "name": "Update Product Price",
    "description": "Update the price of a product",
    "type": "query",
    "model_id": 5,
    "database_id": 1,
    "dataset_query": {
      "type": "native",
      "native": {
        "query": "UPDATE products SET price = {{price}} WHERE id = {{product_id}}",
        "template-tags": {
          "product_id": {
            "type": "number",
            "required": true
          },
          "price": {
            "type": "number",
            "required": true
          }
        }
      },
      "database": 1
    }
  }'

​
Request body

​
name
string
required
Action name
​
type
string
required
Action type:
  • "implicit" - Auto-generated CRUD actions
  • "query" - Custom SQL query actions
  • "http" - HTTP API actions
​
model_id
integer
Model/question ID to associate with
​
database_id
integer
Database ID (required for query actions)
​
dataset_query
object
Query definition with template tags for parameters
​
description
string
Action description
​
parameters
array
Parameter definitions
​
visualization_settings
object
Form appearance and behavior settings

​
Update action

Update an existing action. 
PUT /api/action/{id}

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

​
Parameters

​
id
integer
required
Action ID

​
Request body

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

​
Delete action

Delete an action. 
DELETE /api/action/{action-id}

curl -X DELETE \
  https://your-metabase.com/api/action/1 \
  -H 'X-Metabase-Session: SESSION_TOKEN'
Deleting an action cannot be undone. Any dashboard buttons or forms using this action will stop working.

​
Execute action

Execute an action with provided parameters. 
POST /api/action/{id}/execute

curl -X POST \
  https://your-metabase.com/api/action/1/execute \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "parameters": {
      "product_id": 123,
      "price": 29.99
    }
  }'

​
Request body

​
parameters
object
required
Map of parameter names to valuesExample:
{
  "product_id": 123,
  "price": 29.99,
  "name": "Widget"
}

​
Response

​
rows-affected
array
Number of rows affected by the action
​
success
boolean
Whether the action succeeded
{
  "rows-affected": [1],
  "success": true
}
Action execution is transactional. If the action fails, changes are rolled back.

​
Preview action execution

Preview what an action would do without actually executing it. 
GET /api/action/{action-id}/execute

curl -X GET \
  'https://your-metabase.com/api/action/1/execute?parameters={"product_id":123}' \
  -H 'X-Metabase-Session: SESSION_TOKEN'

​
Query parameters

​
parameters
object
JSON string of parameter values

​
Public actions

​
List public actions

Get all actions with public links. 
GET /api/action/public

curl -X GET \
  https://your-metabase.com/api/action/public \
  -H 'X-Metabase-Session: SESSION_TOKEN'
Requires admin permissions. Returns actions that have public UUIDs for embedding.
Generate a public link for an action. 
POST /api/action/{id}/public_link

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

​
Response

{
  "uuid": "110c3d96-ff3a-4ec6-9a82-7c2d5e073fa2"
}
The action can be accessed publicly at /api/public/action/{uuid}. Remove the public link for an action. 
DELETE /api/action/{id}/public_link

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

​
Action types

​
Implicit actions

Auto-generated CRUD actions based on a model:
  • Create - Insert new rows
  • Update - Modify existing rows
  • Delete - Remove rows

​
Query actions

Custom SQL actions with template tags for parameters. Useful for:
  • Complex business logic
  • Bulk operations
  • Custom validation

​
HTTP actions

Call external APIs:
  • POST to webhooks
  • Trigger external workflows
  • Sync with other systems

​
Error codes

​
400 Bad Request
error
Invalid action configuration or parameters
​
403 Forbidden
error
Insufficient permissions to execute action
​
404 Not Found
error
Action not found
​
500 Internal Server Error
error
Action execution failed