---
title: "Compile + run one widget, persist nothing (scope: dashboards:write)"
method: POST
path: "/widgets/preview"
---

# Compile + run one widget, persist nothing (scope: dashboards:write)

`POST /widgets/preview`

## Request

- Base URL: `https://api.lochless.io/api/v1`
- URL: `https://api.lochless.io/api/v1/widgets/preview`
- Auth: HTTP bearer

## Request body

- Widget
  - `type` 'number' | 'over_time' | 'breakdown' | 'share' | 'over_time_by_group' | 'table' | 'narrative' | 'status_kpi' | 'before_after' | 'timeline' | 'quote' | 'checklist' | 'param_block', required
  - `prompt` string, required: The widget's NL subject. Untrusted free text — stored, never interpreted.
  - `title` string: Optional short heading for the card. Omit and the heading is derived from the subject. Display-only — never compiled or executed, so it cannot change what the widget computes.
  - `spec` object: Deliverable widgets only (status_kpi/timeline/checklist/...). Display-only labels, never executed.
  - `params` object
    - `metric` string
    - `dimension` string
    - `time_bucket` string

## Response `200`

{ widget, result, chosen, options, interpretation, ... }

## Other responses

- `400`

---

[API](https://skmtc.dev/lochless/apis/synoptic-customer-api.md) · [All operations](https://skmtc.dev/lochless/apis/synoptic-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lochless/apis/synoptic-customer-api/revisions/e6dee3956611?raw)