Usage meters: definitions, threshold breaches, and consuming products.
List meters
Returns a paginated list of meters. Supports the unified field.op=value filter grammar.
query Parameters
created_atFilter on created_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. created_at.gt=value; a bare created_at=value means eq.
functionFilter on function (enum). Operators: eq, in — dot grammar, e.g. function.in=value; a bare function=value means eq. A bare comma-separated value is in-sugar: function=a,b means function.in=a,b. Legal values: SUM, COUNT, MAX, MIN, AVG, UNIQUE_COUNT, LAST, P95.
keyFilter on key (string). Operators: eq, in, contains — dot grammar, e.g. key.in=value; a bare key=value means eq. A bare comma-separated value is in-sugar: key=a,b means key.in=a,b.
late_event_policyFilter on late_event_policy (enum). Operators: eq, in — dot grammar, e.g. late_event_policy.in=value; a bare late_event_policy=value means eq. A bare comma-separated value is in-sugar: late_event_policy=a,b means late_event_policy.in=a,b. Legal values: DROP, CLAMP_TO_PERIOD, REBILL_PRIOR.
metric_keyFilter on metric_key (string). Operators: eq, in, contains — dot grammar, e.g. metric_key.in=value; a bare metric_key=value means eq. A bare comma-separated value is in-sugar: metric_key=a,b means metric_key.in=a,b.
nameFilter on name (string). Operators: eq, contains — dot grammar, e.g. name.contains=value; a bare name=value means eq.
updated_atFilter on updated_at (date-time). Operators: eq, gt, gte, lt, lte — dot grammar, e.g. updated_at.gt=value; a bare updated_at=value means eq.
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
searchCase-insensitive substring match over key, name, and metric_key. Filterable fields (key, name, metric_key, function, late_event_policy, created_at, updated_at) accept apifilter operator suffixes
Case-insensitive substring match over key, name, and metric_key. Filterable fields (key, name, metric_key, function, late_event_policy, created_at, updated_at) accept apifilter operator suffixes
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List meters › Responses
OK
Create a meter
Creates an org-scoped meter usable by any product.
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Create a meter › Request Body
When set, defines this as a derived meter computed from other meters via a formula.
dedup_key_pathJSON-path to the event field used for deduplication; default uses the event's idempotency_key.
dimensionsEvent metadata fields exposed for group-by.
event_schemaJSON-Schema document validating ingested events; null disables validation.
Predicate tree restricting which events the meter includes.
functionAggregation applied over the window: SUM, COUNT, MAX, MIN, AVG, UNIQUE_COUNT, LAST, or P95.
keyOrg-unique slug identifying the meter; lowercase letter then [a-z0-9_-], 1-64 chars.
late_event_policyHow events arriving after period close are handled: DROP, CLAMP_TO_PERIOD, or REBILL_PRIOR.
metric_keyEvent ingestion key this meter aggregates over.
nameHuman-readable label for the meter.
negative_allowedWhether the aggregated value may go negative (e.g. for credits/reversals).
Alert conditions evaluated against the meter's output.
unique_by_fieldEvent field whose distinct values are counted; required for UNIQUE_COUNT.
unit_currency_fieldEvent field carrying the currency when the metric measures money.
unit_labelDisplay label for one metric unit (e.g. "calls").
value_fieldEvent field aggregated; required for SUM/MAX/MIN/AVG/P95/LAST, forbidden for COUNT/UNIQUE_COUNT.
Time window over which to aggregate; null uses the default window.
Create a meter › Responses
Created
List threshold-breach events across every meter in the org
The org-wide breach inbox: threshold-breach events across every meter, newest first, keyset-paginated.
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List threshold-breach events across every meter in the org › Responses
OK
Get a meter
Returns a single org-scoped meter with its aggregation configuration (function, value field, filter tree, window, composed sources).
path Parameters
idMeter UUID
Meter UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get a meter › Responses
OK
Delete a meter
Fails with 409 if any product binding still references this meter.
path Parameters
idMeter UUID
Meter UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete a meter › Responses
No Content
Update a meter
Merge-patch update. Meters are shared, de-versioned entities: billing-relevant fields (function, value_field, filter_tree, window, unique_by_field, late_event_policy, composed_of) go live immediately and trigger a republish of every ACTIVE product consuming the meter (see /meters/{id}/consumers).
path Parameters
idMeter UUID
Meter UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Update a meter › Request Body
New derived-meter formula; omitted leaves it unchanged.
dedup_key_pathNew dedup JSON-path; omitted leaves it unchanged.
dimensionsNew group-by dimension fields; omitted leaves them unchanged.
event_schemaNew event JSON-Schema; omitted leaves it unchanged.
New event predicate tree; omitted leaves it unchanged.
functionNew aggregation function; omitted leaves it unchanged.
late_event_policyNew late-event policy; omitted leaves it unchanged.
nameNew human-readable label; omitted leaves it unchanged.
negative_allowedNew negative-value setting; omitted leaves it unchanged.
New alert thresholds; omitted leaves them unchanged.
unique_by_fieldNew distinct-count event field; omitted leaves it unchanged.
unit_currency_fieldNew unit-currency event field; omitted leaves it unchanged.
unit_labelNew unit display label; omitted leaves it unchanged.
value_fieldNew aggregated event field; omitted leaves it unchanged.
New aggregation window; omitted leaves it unchanged.
Update a meter › Responses
OK
List bindings for a meter
Returns every product-meter binding that references the meter, across products.
path Parameters
idMeter UUID
Meter UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List bindings for a meter › Responses
OK
List threshold-breach events for a meter
Reads from the shared domain_event_outbox; newest first; capped at the standard pagination limit.
path Parameters
idMeter UUID
Meter UUID
query Parameters
limitPage size. Values above the server-side cap are clamped (standard default 50, cap 200; a few document-heavy lists use larger windows). Invalid values fall back to the default.
cursorOpaque continuation token from the previous response's pagination.cursor. Omit for the first page. Cursors are stateless and do not expire, but are only valid for the list and filters that produced them.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List threshold-breach events for a meter › Responses
OK
Daily breach counts for a meter
Daily count of threshold-breach events for one meter over a recent window. Powers the threshold-rail sparkline.
path Parameters
idMeter UUID
Meter UUID
query Parameters
daysWindow in days (1-90, default 30)
Window in days (1-90, default 30)
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Daily breach counts for a meter › Responses
OK
List products consuming a meter
The consumer census: every ACTIVE product that bills through this meter (via a live binding, or a composed-source snapshot at the product's head version).
path Parameters
idMeter UUID
Meter UUID
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List products consuming a meter › Responses
OK