---
title: "Preview an unsaved meter definition"
method: POST
path: "/v1/meters/preview"
tags: ["Meters"]
---

# Preview an unsaved meter definition

`POST /v1/meters/preview`

## Request

- Base URL: `https://api.creem.io`
- URL: `https://api.creem.io/v1/meters/preview`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/creem/apis/creem-api/docs/v1/meters/preview/post.ts> (a function with typed inputs; its response is checked against the schema)

Dry-run a candidate meter definition against your real usage over the last 7 whole UTC days (today included, future-dated events excluded) WITHOUT creating anything: matched events, aggregated units, distinct customers, and a zero-filled per-day series, oldest first. Useful for checking a definition before committing to it. The scan is capped defensively and runs newest-first, so a very high-volume store gets the most recent slice of the window rather than an unbounded scan — the recent days stay complete and the oldest day of the series degrades.

## Request body

- PreviewMeterApiRequestDto
  - `event_name` string, required: The usage event name the candidate meter would consume
  - `aggregation` 'count' | 'sum' | 'average' | 'min' | 'max' | 'unique', required: Aggregation to dry-run
  - `aggregation_property` string: Event property the aggregation reduces. Required for every aggregation except "count".
  - `filter` MeterFilterApiRequestDto
    - `conjunction` 'and' | 'or', required: How the clauses combine
    - `clauses` FilterClauseApiRequestDto[], required: Filter clauses. An empty list means the meter counts every event with the given event name.
      - `property` string, required: Event property to test — a key of the event's `properties` bag, unprefixed.
      - `operator` 'equals' | 'not_equals' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains', required: Comparison operator
      - `value` union, required: Value to compare against. Auto-parsed (number → boolean → string) on both sides before comparison, so "10" and 10 behave the same — which is why a raw number or boolean is accepted here as well as a string.
        - string
        - number
        - boolean
  - `unit_label` string: Display unit for the preview. Cosmetic (nothing is persisted); defaults to "units".

## Response `200`

Preview of the candidate definition

- MeterPreviewApiResponseDto
  - `matched_events` number, required: Events the meter would count over the preview window
  - `units` string, required: Aggregated units over the whole window, as a string for BigInt safety
  - `distinct_customers` number, required: Distinct customers among the matching events
  - `daily` MeterPreviewDailyApiResponseDto[], required: The last 7 UTC days (today included), oldest first and zero-filled
    - `date` string, required: UTC calendar day
    - `event_count` number, required: Matching events on this day
    - `value` string, required: The aggregation folded over this day alone, as a string for BigInt safety

## Other responses

- `400`: Bad Request - Invalid input parameters
- `401`: Unauthorized - Invalid or missing API key
- `404`: Not Found - Resource does not exist
- `422`: The candidate definition is not satisfiable

## Changes

- **2026-09-15** `071301350724`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/creem/apis/creem-api/changes/v1/meters/preview/post.md)

---

[API](https://skmtc.dev/creem/apis/creem-api.md) - [All operations](https://skmtc.dev/creem/apis/creem-api/llms.txt) - [OpenAPI document](https://skmtc.dev/creem/apis/creem-api/revisions/3f39a8f266c3?raw)