---
title: "Preview a single combination with live data"
method: POST
path: "/api/v1/compiler/combination/preview"
tags: ["compiler"]
---

# Preview a single combination with live data

`POST /api/v1/compiler/combination/preview`

Preview a single combination: resolve, compile, execute, and build config.

Chains existing services to provide a single-call preview for the query
gallery. Returns data + WidgetConfig for immediate rendering.

RLS: Filtered to current client (ClientRLSDB).

## Query parameters

- `source` string, nullable

## Headers

- `X-Kater-CLI-ID` string, nullable

## Request body

- CombinationPreviewRequest — Request to preview a single combination with live data.
  - `combination` string, required — Comma-separated slot selections, same format as ResolveRequest.combination. Example: 'dimension=due_month,measure=compliance_rate'
  - `connection_id` string, uuid, required — Connection to preview against
  - `pinned_variant` string, nullable — Optional pinned variant name (e.g. '_base').
  - `query_id` string, uuid, required — UUID of the query template
  - `tenant_key` string, required — Tenant key for multi-tenant execution. Use 'kater_global_tenant' for no-tenancy clients.

## Response `200`

Successful Response

- CombinationPreviewResponse — Response from combination preview with data + resolved config.
  - `auto_title` string, nullable — Auto-generated title
  - `cache_hit` boolean — Whether the result was served from cache
  - `column_map` ColumnMapEntryResponse[] — Enriched column metadata
    - `aggregation` string, nullable — Aggregation type for measures: sum, count, min, max, avg, unknown. None for non-measures.
    - `field_type` string, required — Field type: dimension, measure, or calculation
    - `kater_id` string, required — UUID string used as SQL column alias
    - `label` string, nullable — Display label
    - `name` string, required — Human-readable column name
  - `config` object — Resolved WidgetConfig (from config builder)
  - `data` object[] — Query result rows
  - `errors` CompilerErrorItem[] — Compilation errors (if any)
    - `code` string, required — Machine-readable error code
    - `column` integer, nullable — Column number in the source file
    - `file` string, nullable — Source file path where the error occurred
    - `line` integer, nullable — Line number in the source file
    - `message` string, required — Human-readable error description
    - `ref` string, nullable — Reference to the source element (e.g. view or query name)
    - `remediation` string, nullable — Suggested fix for this error
  - `execution_time_ms` number — Total execution time in milliseconds
  - `success` boolean, required — Whether preview succeeded
  - `widget_type` string, nullable — Resolved widget type (e.g. 'axis_metric_by_dimensiondate')

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

## Changes

- **2026-03-05** `6a140b82e07c` — 3 breaking, 1 warning, 1 info
  - added the new required request property `query_id`
  - the request property `tenant_key` became required
  - request property `tenant_key` list-of-types was narrowed by removing types `null` from media type `application/json`
  - removed the request property `query_ref`
  - …1 more
- **2026-02-26** `bef1f3e205dd` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/kater-ai/apis/kater-api/changes/api/v1/compiler/combination/preview/post.md)

---

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