---
title: "Preview Criteria"
method: POST
path: "/api/v1/lists/preview-criteria"
tags: ["lists"]
---

# Preview Criteria

`POST /api/v1/lists/preview-criteria`

Compile a natural-language audience into criteria + a live match count.

## Request body

- CriteriaPreviewRequest — Natural-language description to compile into criteria.
  - `description` string, required

## Response `200`

Successful Response

- CriteriaPreviewResult — Compiled criteria + a human summary + how many contacts match now.
  - `criteria` Criteria, required — A versioned dynamic-list definition.
    - `version` integer
    - `match` 'all' | 'any'
    - `clauses` Clause[]
      - `field` string, required
      - `op` 'eq' | 'neq' | 'in' | 'gte' | 'lte' | 'is_true' | 'is_false', required
      - `value` union
        - string
        - integer
        - number
        - boolean
        - union[]
          - union
            - string
            - integer
            - number
            - boolean
    - `last_interaction_within_days` integer, nullable
    - `arriving_within_hours` integer, nullable
    - `in_house` boolean, nullable
    - `property_ids` string[], nullable
  - `summary` string, required
  - `match_count` integer, required

## Other responses

- `422` — Validation Error

## Changes

> 18 revisions in range; 1 not diffed.

- **2026-09-03** `d65b8fefae34` — 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status

[Change history](https://skmtc.dev/getanana/apis/cleon-api/changes/api/v1/lists/preview-criteria/post.md)

---

[API](https://skmtc.dev/getanana/apis/cleon-api.md) · [All operations](https://skmtc.dev/getanana/apis/cleon-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getanana/apis/cleon-api/revisions/202b7d85683e?raw)