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

# POST /api/agent/v2/construct-query

`POST /api/agent/v2/construct-query`

Construct an MBQL query from a portable MBQL 5 representations JSON payload.

  The body is `{"query": <external-query>}` where `<external-query>` is a JSON object
  matching `::lib.schema/external-query` — see the `construct_notebook_query` tool
  documentation for the format reference. Returns a base64-encoded MBQL query that can be
  executed via /v1/execute or paginated via /v2/query.

## Request body

- MetabaseAgentApiApiConstructQueryRequest — Request body for /v2/construct-query and the fresh-query branch of /v2/query. A single `:query` key whose value is a JSON object matching [[metabase.lib.schema/external-query]] — the canonical portable MBQL 5 wire format. The query is fully self-describing: the database is derived from the first stage's `source-table:` or `source-card:`, all field references are portable FKs (`[<db-name>, <schema>, <table-name>, <column-name>]`), and there is no auxiliary `source_entity` / `referenced_entities` envelope. See `resources/metabot/prompts/tools/construct_notebook_query.md` for the full format reference (including operators, joins, expressions, multi-stage queries, and FK conventions). Closed map: any extra top-level keys (notably the legacy `source_entity` / `referenced_entities` envelope from before the repr migration) are rejected with a 400 so callers don't silently send fields the server ignores.
  - `query` MetabaseLibSchemaExternalQuery, required — unresolved $ref

## Response `2XX`

Successful response

- MetabaseAgentApiApiConstructQueryResponse — Response containing a base64-encoded MBQL query for use with /v1/execute.
  - `query` string, required

## Other responses

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

---

[API](https://skmtc.dev/metabase/apis/metabase-api.md) · [All operations](https://skmtc.dev/metabase/apis/metabase-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/metabase/metabase-api/revisions/e879e0319b12/schema)