---
title: "POST /api/agent/v1/construct-native-query"
method: POST
path: "/api/agent/v1/construct-native-query"
tags: ["/api/agent"]
---

# POST /api/agent/v1/construct-native-query

`POST /api/agent/v1/construct-native-query`

## Request

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

Construct a native (raw SQL) query against a database.

  Wraps `sql` into a serialized native query and returns it base64-encoded — the same
  `{"query": <base64>}` shape as /v2/construct-query — so it can be saved as a question via
  /v1/question (the MCP layer swaps the base64 for a `query_handle`).

  This endpoint does NOT execute the SQL; to run native SQL ad hoc use /v1/execute-sql. The
  MBQL execution endpoints (/v1/execute, /v2/query) reject native queries by design, so a
  handle produced here is for saving, not for /v2/query execution.

## Request body

- MetabaseAgentApiApiConstructNativeQueryRequest: Request body for /v1/construct-native-query: a target database and a raw SQL string.
  - `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

- MetabaseAgentApiApiConstructQueryResponse: Response containing a base64-encoded MBQL query for use with /v1/execute. The optional `:prompt` echoes the request's prompt back so the MCP layer can store it with the handle (see `metabase.mcp.tools/make-store-construct-query-result`).
  - `prompt` string, nullable: value must be a non-blank string.
  - `query` string, required: value must be a non-blank string.

## 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/construct-native-query/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)