> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Meter
> Creates a meter — a named, countable action of your product — that plans can price and subscriptions report usage against.
**Enabled per organization**
Usage-based billing must be enabled for your organization before these endpoints accept requests. Contact your Yuno account manager to enable it. Requests from an organization where it is not enabled return `403 PRODUCT_NOT_ENABLED`.
**`event_name` and `aggregation` are immutable**
They define what your systems send and how it counts, so they can't change after creation (a PATCH that includes them is silently ignored). To change either, create a new meter with a new `event_name` and archive the old one with [Update Meter](/reference/meters/update-meter) (`status: INACTIVE`). `event_name` is unique per account across active **and** archived meters, so pick a name you won't need to reuse. `status` sent on creation is ignored — a new meter is always `ACTIVE`.
See [The Meter Object](/reference/meters/the-meter-object) for every field, and the [Usage-Based Billing guide](/docs/payment-features/subscriptions/usage-based-billing) for the end-to-end flow. Refer to [Meter Error Codes](/reference/meters/meter-error-codes) for the possible error outcomes.
## OpenAPI
````yaml openapi/meters/create-meter.json POST /subscriptions/meters
openapi: 3.1.0
info:
title: meters
version: 1.0.0
servers:
- url: https://api-sandbox.y.uno/v1
- url: https://api.eu.y.uno/v1
security:
- sec0: []
sec1: []
paths:
/subscriptions/meters:
post:
summary: Create Meter
description: >-
Usage-based billing must be enabled for your organization before this
endpoint accepts requests (otherwise `403 PRODUCT_NOT_ENABLED`). Creates
a meter: a named, countable action your product performs (tokens, API
requests, gigabytes held). The meter defines the `event_name` your
systems send and how the reported values aggregate per billing cycle.
Attach it to a plan as a metered price to bill usage.
operationId: create-meter
parameters:
- in: header
name: X-Idempotency-Key
required: true
schema:
type: string
description: >-
Unique identifier used in HTTP headers to ensure that a request is
processed only once, even if it is retried due to network issues or
timeouts. Optional, as on the rest of the Yuno API.
requestBody:
content:
application/json:
schema:
type: object
required:
- account_id
- name
- event_name
- aggregation
properties:
account_id:
type: string
description: >-
The unique identifier of the account the meter belongs to
(UUID, 36 chars).
name:
type: string
description: >-
The meter display name (MAX 255; MIN 3). Leading and
trailing spaces are trimmed.
description:
type: string
description: >-
What the meter counts and how. Optional but recommended — it
is how your team and Yuno support understand the meter.
event_name:
type: string
description: >-
The key your systems send on every usage event to reference
this meter (MAX 100; lowercase letters, digits, `_` and `.`
only — `^[a-z0-9_.]+$`). Must be unique across all meters of
the account, `ACTIVE` or `INACTIVE`, else `409
METER_EVENT_NAME_CONFLICT`. Immutable after creation.
aggregation:
type: string
enum:
- SUM
- COUNT
- LAST
description: >-
How reported events roll up into the cycle quantity. `SUM`
adds every event `value` (tokens, minutes). `COUNT` counts
events, ignoring `value` (API requests). `LAST` keeps the
most recent `value` (a gauge such as gigabytes held).
Immutable after creation.
unit_label:
type: string
description: >-
Singular unit label used when the usage is displayed.
Example: `token`.
plural_unit_label:
type: string
description: >-
Plural unit label used when the usage is displayed. Example:
`tokens`.
default_price:
type: object
required:
- currency
- value
properties:
currency:
type: string
description: >-
MAX 3; MIN 3. Must be `USD` — any other currency is
rejected with `400 INVALID_PARAMETERS`.
value:
type: number
format: float
description: >-
Default price per unit beyond the included credits
(multiple of 0.0001). Inherited by USD plans that attach
this meter without an explicit `price_per_credit`.
metadata:
type: array
description: >-
Optional key-value pairs attached to the meter (MAX 48
entries; keys must be unique per meter).
items:
type: object
required:
- key
- value
properties:
key:
type: string
description: MAX 48.
value:
type: string
description: MAX 512.
status:
type: string
enum:
- ACTIVE
- INACTIVE
description: >-
Ignored on creation — a new meter is always `ACTIVE`. Use
Update Meter to archive it.
examples:
Meter:
value:
account_id: 00000000-0000-4000-8000-000000000002
name: AI tokens
description: >-
LLM tokens consumed by model responses, reported once per
response
event_name: ai_tokens
aggregation: SUM
unit_label: token
plural_unit_label: tokens
default_price:
currency: USD
value: 0.002
metadata:
- key: team
value: platform
responses:
'201':
description: '201'
content:
application/json:
examples:
Result:
value:
id: 55555555-5555-5555-5555-555555555555
account_id: 00000000-0000-4000-8000-000000000002
name: AI tokens
description: >-
LLM tokens consumed by model responses, reported once per
response
event_name: ai_tokens
aggregation: SUM
unit_label: token
plural_unit_label: tokens
default_price:
currency: USD
value: 0.002
metadata:
- key: team
value: platform
status: ACTIVE
created_at: '2026-08-18T09:00:04.000000Z'
updated_at: '2026-08-18T09:00:04.000000Z'
schema:
type: object
properties:
id:
type: string
description: The unique identifier of the meter.
account_id:
type: string
description: The unique identifier of the account that owns the meter.
name:
type: string
description:
type: string
nullable: true
event_name:
type: string
aggregation:
type: string
enum:
- SUM
- COUNT
- LAST
unit_label:
type: string
nullable: true
plural_unit_label:
type: string
nullable: true
default_price:
type: object
properties:
currency:
type: string
value:
type: number
metadata:
type: array
items:
type: object
properties:
key:
type: string
value:
type: string
status:
type: string
enum:
- ACTIVE
- INACTIVE
example: ACTIVE
created_at:
type: string
description: Set by Yuno on creation.
updated_at:
type: string
description: Set by Yuno on every update.
'400':
description: '400'
content:
application/json:
examples:
Invalid event_name:
summary: Invalid event_name
value:
code: INVALID_PARAMETERS
messages:
- >-
The field 'event_name' has an invalid value, it must
contain only lowercase letters, numbers, underscores and
dots.
Missing account_id:
summary: Missing account_id
value:
code: INVALID_PARAMETERS
messages:
- The account_id is required
Non-USD default_price:
summary: Non-USD default_price
value:
code: INVALID_PARAMETERS
messages:
- The default_price currency must be USD
Invalid aggregation:
summary: Invalid aggregation
value:
code: INVALID_PARAMETERS
messages:
- The aggregation must be one of SUM, COUNT, LAST
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
'403':
description: '403'
content:
application/json:
examples:
Product not enabled:
summary: Product not enabled
value:
code: PRODUCT_NOT_ENABLED
messages:
- Usage-based billing is not enabled for this organization
schema:
type: object
properties:
code:
type: string
example: PRODUCT_NOT_ENABLED
messages:
type: array
items:
type: string
'409':
description: '409'
content:
application/json:
examples:
Result:
value:
code: METER_EVENT_NAME_CONFLICT
messages:
- >-
A meter with event_name ai_tokens already exists for
this account
schema:
type: object
properties:
code:
type: string
messages:
type: array
items:
type: string
deprecated: false
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: public-api-key
x-default:
sec1:
type: apiKey
in: header
name: private-secret-key
x-default:
````