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

# POST /api/agent/v2/query

`POST /api/agent/v2/query`

Execute a portable MBQL 5 representations JSON query and stream the results, with
  continuation-token pagination.

  Accepts either a JSON body (same shape as /v2/construct-query) or a `continuation_token`
  from a previous response. Returns results with column metadata and an optional
  `continuation_token` for fetching the next page.

## Request body

- union — Request body for /v2/query. Accepts either a fresh-query payload (`{:query <external-query>}`, same shape as /v2/construct-query) or a `:continuation_token` from a prior response. Both branches are closed maps: extra top-level keys (e.g. the legacy `source_entity` / `referenced_entities` envelope, or sending `:query` and `:continuation_token` simultaneously) are rejected with a 400.
  - object
    - `continuation_token` string, required
  - 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

- MetabaseAgentApiApiQueryResponse — Response from query execution. The HTTP status is always 202 because results are streamed — check the `status` field to determine success or failure.
  - `continuation_token` string, nullable
  - `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

---

[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)