---
title: "GET /api/embed-mcp/queries/{handle}"
method: GET
path: "/api/embed-mcp/queries/{handle}"
tags: ["/api/embed-mcp"]
---

# GET /api/embed-mcp/queries/{handle}

`GET /api/embed-mcp/queries/{handle}`

## Request

- Base URL: `` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/embed-mcp/queries/{handle}`
- Auth: API key in header `X-API-Key`

Resolve a query handle to the base64-encoded MBQL the iframe should render.

   This is how the v2 MCP Apps tools keep result data out of the model context: `visualize_query`
   and `render_drill_through` return only a handle, and the iframe exchanges it here using the
   scoped UI credential it was rendered with. The lookup is user-scoped (see
   [[metabase.mcp.session/find-handle-row]]) and the credential is accepted only on the MCP UI
   request surface, so a handle on its own is not a bearer credential.

## Path parameters

- `handle` string, required

## Request body

- object

## Response `2XX`

Successful response

- object
  - `prompt` string, nullable, required
  - `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/embed-mcp/queries/:handle/get.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)