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

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

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

Construct an MBQL query from a table or metric.

  Returns a base64-encoded MBQL query that can be used with the query API.

  For tables, supports: filters, fields, aggregations, group_by, order_by, limit.
  For metrics, supports: filters, group_by (aggregation is defined by the metric).

## Request body

- union — Request schema for /v1/construct-query. Accepts either table_id or metric_id.
  - MetabaseEnterpriseAgentApiApiConstructQueryTableRequest — Request schema for constructing a query from a table. Query components: - filters: Filter conditions to apply - fields: Specific fields to select (omit for all fields) - aggregations: Aggregation functions (sum, count, avg, etc.). Use sort_order on the aggregation to order by it. - group_by: Fields to group by, with optional temporal granularity - order_by: Order by regular fields only. To order by an aggregation result, use sort_order on the aggregation instead. - limit: Maximum rows to return
    - `aggregations` MetabaseEnterpriseMetabotV3ToolsApiAggregation[], nullable
      - union — Aggregation — count (field optional), field-based (field required), or measure-based.
        - MetabaseEnterpriseMetabotV3ToolsApiCountAggregation — Count aggregation — counts rows, no field_id needed. Use sort_order to order results by this aggregation ('asc' or 'desc').
          - `bucket` 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'second-of-minute' | 'minute-of-hour' | 'hour-of-day' | 'day-of-week' | 'day-of-month' | 'day-of-year' | 'week-of-year' | 'month-of-year' | 'quarter-of-year' | 'year-of-era'
          - `function` 'count', required
          - `sort_order` 'asc' | 'desc', nullable
        - MetabaseEnterpriseMetabotV3ToolsApiFieldAggregation — Aggregation using a field and function. field_id is required. Use sort_order to order results by this aggregation ('asc' or 'desc').
          - `bucket` 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'second-of-minute' | 'minute-of-hour' | 'hour-of-day' | 'day-of-week' | 'day-of-month' | 'day-of-year' | 'week-of-year' | 'month-of-year' | 'quarter-of-year' | 'year-of-era'
          - `field_id` string, required
          - `function` 'avg' | 'count-distinct' | 'max' | 'min' | 'sum', required
          - `sort_order` 'asc' | 'desc', nullable
        - MetabaseEnterpriseMetabotV3ToolsApiMeasureAggregation — Aggregation using a pre-defined measure.
          - `measure_id` integer, required
          - `sort_order` 'asc' | 'desc', nullable
    - `fields` MetabaseEnterpriseMetabotV3ToolsApiField[], nullable
      - `bucket` 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'second-of-minute' | 'minute-of-hour' | 'hour-of-day' | 'day-of-week' | 'day-of-month' | 'day-of-year' | 'week-of-year' | 'month-of-year' | 'quarter-of-year' | 'year-of-era'
      - `field_id` string, required
    - `filters` MetabaseEnterpriseMetabotV3ToolsApiFilter[], nullable
      - union
        - MetabaseEnterpriseMetabotV3ToolsApiSegmentFilter — Filter using a pre-defined segment.
          - `segment_id` integer, required
        - MetabaseEnterpriseMetabotV3ToolsApiExistenceFilter
          - `field_id` string, required
          - `operation` 'is-null' | 'is-not-null' | 'string-is-empty' | 'string-is-not-empty' | 'is-true' | 'is-false', required
        - MetabaseEnterpriseMetabotV3ToolsApiTemporalExtractionFilter
          - `field_id` string, required
          - `operation` 'year-equals' | 'year-not-equals' | 'quarter-equals' | 'quarter-not-equals' | 'month-equals' | 'month-not-equals' | 'day-of-week-equals' | 'day-of-week-not-equals' | 'hour-equals' | 'hour-not-equals' | 'minute-equals' | 'minute-not-equals' | 'second-equals' | 'second-not-equals', required
          - `value` integer, required
        - MetabaseEnterpriseMetabotV3ToolsApiDisjunctiveTemporalExtractionFilter
          - `field_id` string, required
          - `operation` 'year-equals' | 'year-not-equals' | 'quarter-equals' | 'quarter-not-equals' | 'month-equals' | 'month-not-equals' | 'day-of-week-equals' | 'day-of-week-not-equals' | 'hour-equals' | 'hour-not-equals' | 'minute-equals' | 'minute-not-equals' | 'second-equals' | 'second-not-equals', required
          - `values` integer[], required
        - MetabaseEnterpriseMetabotV3ToolsApiTemporalFilter
          - `bucket` 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'second-of-minute' | 'minute-of-hour' | 'hour-of-day' | 'day-of-week' | 'day-of-month' | 'day-of-year' | 'week-of-year' | 'month-of-year' | 'quarter-of-year' | 'year-of-era'
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'greater-than' | 'greater-than-or-equal' | 'less-than' | 'less-than-or-equal', required
          - `value` union, required
            - string
            - integer
        - MetabaseEnterpriseMetabotV3ToolsApiDisjunctiveTemporalFilter
          - `bucket` 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'second-of-minute' | 'minute-of-hour' | 'hour-of-day' | 'day-of-week' | 'day-of-month' | 'day-of-year' | 'week-of-year' | 'month-of-year' | 'quarter-of-year' | 'year-of-era'
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'greater-than' | 'greater-than-or-equal' | 'less-than' | 'less-than-or-equal', required
          - `values` union[], required
            - union
              - …
        - MetabaseEnterpriseMetabotV3ToolsApiStringFilter
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'string-contains' | 'string-not-contains' | 'string-starts-with' | 'string-ends-with', required
          - `value` string, required
        - MetabaseEnterpriseMetabotV3ToolsApiDisjunctiveStringDateFilter
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'string-contains' | 'string-not-contains' | 'string-starts-with' | 'string-ends-with', required
          - `values` string[], required
        - MetabaseEnterpriseMetabotV3ToolsApiNumericFilter
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'greater-than' | 'greater-than-or-equal' | 'less-than' | 'less-than-or-equal', required
          - `value` union, required
            - integer
            - number
        - MetabaseEnterpriseMetabotV3ToolsApiDisjunctiveNumericFilter
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals', required
          - `values` union[], required
            - union
              - …
    - `group_by` MetabaseEnterpriseMetabotV3ToolsApiGroupBy[], nullable
      - `field_granularity` 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'day-of-week', nullable
      - `field_id` string, required
    - `limit` integer, nullable — value must be an integer greater than zero.
    - `order_by` MetabaseEnterpriseMetabotV3ToolsApiOrderBy[], nullable — Order by regular fields only. To order by aggregation results, use sort_order on the aggregation.
      - `direction` 'asc' | 'desc', required
      - `field` MetabaseEnterpriseMetabotV3ToolsApiField, required
        - `bucket` 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'second-of-minute' | 'minute-of-hour' | 'hour-of-day' | 'day-of-week' | 'day-of-month' | 'day-of-year' | 'week-of-year' | 'month-of-year' | 'quarter-of-year' | 'year-of-era'
        - `field_id` string, required
    - `table_id` integer, required — value must be an integer greater than zero.
  - MetabaseEnterpriseAgentApiApiConstructQueryMetricRequest — Request schema for constructing a query from a metric. Only supports filters and group_by (aggregation is defined by the metric).
    - `filters` MetabaseEnterpriseMetabotV3ToolsApiFilter[], nullable
      - union
        - MetabaseEnterpriseMetabotV3ToolsApiSegmentFilter — Filter using a pre-defined segment.
          - `segment_id` integer, required
        - MetabaseEnterpriseMetabotV3ToolsApiExistenceFilter
          - `field_id` string, required
          - `operation` 'is-null' | 'is-not-null' | 'string-is-empty' | 'string-is-not-empty' | 'is-true' | 'is-false', required
        - MetabaseEnterpriseMetabotV3ToolsApiTemporalExtractionFilter
          - `field_id` string, required
          - `operation` 'year-equals' | 'year-not-equals' | 'quarter-equals' | 'quarter-not-equals' | 'month-equals' | 'month-not-equals' | 'day-of-week-equals' | 'day-of-week-not-equals' | 'hour-equals' | 'hour-not-equals' | 'minute-equals' | 'minute-not-equals' | 'second-equals' | 'second-not-equals', required
          - `value` integer, required
        - MetabaseEnterpriseMetabotV3ToolsApiDisjunctiveTemporalExtractionFilter
          - `field_id` string, required
          - `operation` 'year-equals' | 'year-not-equals' | 'quarter-equals' | 'quarter-not-equals' | 'month-equals' | 'month-not-equals' | 'day-of-week-equals' | 'day-of-week-not-equals' | 'hour-equals' | 'hour-not-equals' | 'minute-equals' | 'minute-not-equals' | 'second-equals' | 'second-not-equals', required
          - `values` integer[], required
        - MetabaseEnterpriseMetabotV3ToolsApiTemporalFilter
          - `bucket` 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'second-of-minute' | 'minute-of-hour' | 'hour-of-day' | 'day-of-week' | 'day-of-month' | 'day-of-year' | 'week-of-year' | 'month-of-year' | 'quarter-of-year' | 'year-of-era'
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'greater-than' | 'greater-than-or-equal' | 'less-than' | 'less-than-or-equal', required
          - `value` union, required
            - string
            - integer
        - MetabaseEnterpriseMetabotV3ToolsApiDisjunctiveTemporalFilter
          - `bucket` 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'second-of-minute' | 'minute-of-hour' | 'hour-of-day' | 'day-of-week' | 'day-of-month' | 'day-of-year' | 'week-of-year' | 'month-of-year' | 'quarter-of-year' | 'year-of-era'
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'greater-than' | 'greater-than-or-equal' | 'less-than' | 'less-than-or-equal', required
          - `values` union[], required
            - union
              - …
        - MetabaseEnterpriseMetabotV3ToolsApiStringFilter
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'string-contains' | 'string-not-contains' | 'string-starts-with' | 'string-ends-with', required
          - `value` string, required
        - MetabaseEnterpriseMetabotV3ToolsApiDisjunctiveStringDateFilter
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'string-contains' | 'string-not-contains' | 'string-starts-with' | 'string-ends-with', required
          - `values` string[], required
        - MetabaseEnterpriseMetabotV3ToolsApiNumericFilter
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals' | 'greater-than' | 'greater-than-or-equal' | 'less-than' | 'less-than-or-equal', required
          - `value` union, required
            - integer
            - number
        - MetabaseEnterpriseMetabotV3ToolsApiDisjunctiveNumericFilter
          - `field_id` string, required
          - `operation` 'equals' | 'not-equals', required
          - `values` union[], required
            - union
              - …
    - `group_by` MetabaseEnterpriseMetabotV3ToolsApiGroupBy[], nullable
      - `field_granularity` 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'day-of-week', nullable
      - `field_id` string, required
    - `metric_id` integer, required — value must be an integer greater than zero.

## Response `2XX`

Successful response

- MetabaseEnterpriseAgentApiApiConstructQueryResponse — 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

## Changes

- **2026-03-09** `78297d193ca4` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/metabase/apis/metabase-api/changes/api/agent/v1/construct-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-service-production.skmtc.workers.dev/v1/apis/metabase/metabase-api/revisions/78297d193ca4/schema)