---
title: "POST /api/agent/v1/execute-sql"
method: POST
path: "/api/agent/v1/execute-sql"
tags: ["/api/agent"]
---

# POST /api/agent/v1/execute-sql

`POST /api/agent/v1/execute-sql`

## Request

- Base URL: `` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/agent/v1/execute-sql`
- Auth: API key in header `X-API-Key`

Execute a raw SQL query against a database. Returns rows + column metadata.

  Requires the user to have native-query permission on the target database; the QP
  middleware enforces this. The instance-level `mcp-execute-sql-enabled` setting
  must also be on (it is by default).

## Request body

- MetabaseAgentApiApiExecuteSqlRequest: Request shape for /v1/execute-sql. The LLM passes a raw SQL string against a target database.
  - `database_id` integer, required: value must be an integer greater than zero.
  - `sql` string, required: value must be a non-blank string.

## Response `2XX`

Successful response

- MetabaseAgentApiApiExecuteQueryResponse: Response from query execution. The HTTP status is always 202 because results are streamed — check the `status` field to determine success or failure.
  - `data` object
    - `cols` MetabaseAgentApiApiColumnMetadata[], required
      - `base_type` string, required
      - `display_name` string, required
      - `effective_type` string, nullable
      - `name` string, required
    - `rows` array[], required
      - unknown[]
        - unknown
  - `error` string
  - `row_count` integer
  - `running_time` integer
  - `status` 'completed' | 'failed', required

## Other responses

- `4XX`: Client error response
- `5XX`: Server error response

## Changes

- **2026-11-04** `2e178f5a7934`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/metabase/apis/metabase-api/changes/api/agent/v1/execute-sql/post.md)

---

[API](https://skmtc.dev/metabase/apis/metabase-api.md) - [All operations](https://skmtc.dev/metabase/apis/metabase-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metabase/apis/metabase-api/revisions/2e178f5a7934?raw)