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

# POST /api/agent/v1/execute

`POST /api/agent/v1/execute`

Execute an MBQL query and return results.

  Accepts a base64-encoded MBQL query (as returned by /v1/construct-query) and executes it,
  returning results with column metadata.

  Response format:
  - On success: {:data {:cols [...] :rows [...]} :row_count N :status :completed :running_time M}
  - On failure: {:status :failed :error "message" ...}

  Standard userspace query limits are enforced (2000 rows for simple queries, 10000 for aggregated).

## Request body

- MetabaseAgentApiApiExecuteQueryRequest — Request schema for /v1/execute. Accepts a base64-encoded MBQL query.
  - `query` string, required

## 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

---

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