openapi: 3.0.1 info: title: Metronome Alerts Billable Metrics API version: 1.0.0 description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)' servers: - url: https://api.metronome.com description: Production server security: - bearerAuth: [] tags: - name: Billable Metrics paths: /v1/billable-metrics: post: description: Create a new billable metric operationId: createBillableMetric-v1 summary: Create a billable metric requestBody: description: The billable metric to create content: application/json: schema: $ref: '#/components/schemas/CreateBillableMetricPayload' example: name: CPU hours aggregate: Count filter: type: object $schema: http://json-schema.org/draft-07/schema required: - event_type responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Id' example: data: id: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc tags: - Billable Metrics get: description: "Retrieves all billable metrics with their complete configurations. Use this for programmatic discovery and management of billable metrics, such as associating metrics to products and auditing for orphaned or archived metrics. \nImportant: Archived metrics are excluded by default; use `include_archived`=`true` parameter to include them.\n" operationId: listAllBillableMetrics-v1 summary: List all billable metrics tags: - Billable Metrics parameters: - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/NextPage' - name: include_archived in: query description: If true, the list of returned metrics will include archived metrics required: false schema: type: boolean responses: '200': description: Success content: application/json: schema: type: object required: - data - next_page properties: data: type: array items: $ref: '#/components/schemas/BillableMetricV1' next_page: type: string nullable: true example: data: - name: data transfer (GB) id: 9570e4f3-d1da-4b95-ba81-bd40ee002727 aggregation_type: SUM aggregation_key: bytes event_type_filter: in_values: - cpu_usage property_filters: - name: cpu_hours exists: true - name: region exists: true in_values: - EU - NA - name: machine_type exists: true in_values: - slow - fast group_keys: - - region - - machine_type custom_fields: envionment: production next_page: null /v1/billable-metrics/create: post: description: "Create billable metrics programmatically with this endpoint—an essential step in configuring your pricing and packaging in Metronome.\n\nA billable metric is a customizable query that filters and aggregates events from your event stream. These metrics are continuously tracked as usage data enters Metronome through the ingestion pipeline. The ingestion process transforms raw usage data into actionable pricing metrics, enabling accurate metering and billing for your products.\n\n### Use this endpoint to: \n- Create individual or multiple billable metrics as part of a setup workflow.\n- Automate the entire pricing configuration process, from metric creation to customer contract setup.\n- Define metrics using either standard filtering/aggregation or a custom SQL query.\n\n### Key response fields: \n- The ID of the billable metric that was created\n- The created billable metric will be available to be used in Products, usage endpoints, and alerts. \n\n### Usage guidelines: \n- Metrics defined using standard filtering and aggregation are Streaming billable metrics, which have been optimized for ultra low latency and high throughput workflows. \n- Use SQL billable metrics if you require more flexible aggregation options.\n" operationId: createBillableMetricV1-v1 summary: Create a billable metric tags: - Billable Metrics requestBody: description: The details of the billable metric to create. content: application/json: schema: $ref: '#/components/schemas/CreateBillableMetricV1Payload' example: name: CPU Hours event_type_filter: in_values: - cpu_usage property_filters: - name: cpu_hours exists: true - name: region exists: true in_values: - EU - NA - name: machine_type exists: true in_values: - slow - fast aggregation_type: SUM aggregation_key: cpu_hours group_keys: - - region - - machine_type responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Id' example: data: id: 58fb0650-e54a-4d17-93cb-ba8e56c32c65 /v1/billable-metrics/archive: post: description: "Use this endpoint to retire billable metrics that are no longer used. After a billable metric is archived, that billable metric can no longer be used in any new Products to define how that product should be metered. If you archive a billable metric that is already associated with a Product, the Product will continue to function as usual, metering based on the definition of the archived billable metric. \n\nArchived billable metrics will be returned on the `getBillableMetric` and `listBillableMetrics` endpoints with a populated `archived_at` field.\n" operationId: archiveBillableMetric-v1 summary: Archive a billable metric tags: - Billable Metrics requestBody: description: The ID of the billable metric to archive content: application/json: schema: $ref: '#/components/schemas/Id' example: id: 8deed800-1b7a-495d-a207-6c52bac54dc9 responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Id' example: data: id: 8deed800-1b7a-495d-a207-6c52bac54dc9 '404': $ref: '#/components/responses/NotFound' /v1/billable-metrics/{billable_metric_id}: get: description: "Retrieves the complete configuration for a specific billable metric by its ID. Use this to review billable metric setup before associating it with products. Returns the metric's `name`, `event_type_filter`, `property_filters`, `aggregation_type`, `aggregation_key`, `group_keys`, `custom fields`, and `SQL query` (if it's a SQL billable metric). \n\nImportant: \n- Archived billable metrics will include an `archived_at` timestamp; they no longer process new usage events but remain accessible for historical reference.\n" operationId: getBillableMetric-v1 summary: Get a billable metric tags: - Billable Metrics parameters: - $ref: '#/components/parameters/BillableMetricId' responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/BillableMetricV1' example: data: id: 8deed800-1b7a-495d-a207-6c52bac54dc9 name: CPU Hours event_type_filter: in_values: - cpu_usage property_filters: - name: cpu_hours exists: true - name: region exists: true in_values: - EU - NA - name: machine_type exists: true in_values: - slow - fast aggregation_type: SUM aggregation_key: cpu_hours group_keys: - - region - - machine_type '404': $ref: '#/components/responses/NotFound' put: description: "Updates only the display name of an existing billable metric. Use this to correct mistakes or apply standardized naming conventions across all billable metrics. Returns the billable metric ID to confirm the update. \n\nImportant: Only the name can be modified via this endpoint; configurations cannot be changed after creation. \n\n#### Example workflow:\nIf you need to make changes to a streaming billable metric, for example, Metronome supports easily rolling out these changes using a simple workflow:\n1. Duplicate the billable metric\n2. Make required changes\n3. Save the metric\n4. Navigate to the product you have associated with the incorrect metric\n5. Schedule the product to reference the newly created metric on the appropriate date\n" operationId: updateBillableMetric-v1 summary: Update a billable metric tags: - Billable Metrics parameters: - $ref: '#/components/parameters/BillableMetricId' requestBody: description: The billable metric to update content: application/json: schema: type: object required: - name properties: name: type: string description: The new name of the metric example: name: CPU hours responses: '200': description: Success content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/Id' example: data: id: 8deed800-1b7a-495d-a207-6c52bac54dc9 /v1/customers/{customer_id}/billable-metrics: get: description: 'Get all billable metrics available for a specific customer. Supports pagination and filtering by current plan status or archived metrics. Use this endpoint to see which metrics are being tracked for billing calculations for a given customer. ' operationId: listBillableMetrics-v1 summary: Get billable metrics for a customer parameters: - $ref: '#/components/parameters/CustomerId' - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/NextPage' - name: on_current_plan in: query description: If true, the list of metrics will be filtered to just ones that are on the customer's current plan required: false schema: type: boolean - name: include_archived in: query description: If true, the list of returned metrics will include archived metrics required: false schema: type: boolean tags: - Billable Metrics responses: '200': description: Success content: application/json: schema: type: object required: - data - next_page properties: data: type: array items: $ref: '#/components/schemas/BillableMetricWithDeprecatedFields' next_page: type: string nullable: true example: data: - name: data transfer (GB) id: 9570e4f3-d1da-4b95-ba81-bd40ee002727 group_by: - cluster - region aggregate: sum aggregate_keys: - bytes aggregation_type: SUM aggregation_key: bytes event_type_filter: in_values: - cpu_usage property_filters: - name: cpu_hours exists: true - name: region exists: true in_values: - EU - NA - name: machine_type exists: true in_values: - slow - fast group_keys: - - region - - machine_type - name: CPU hours id: 13117714-3f05-48e5-a6e9-a66093f13b4d aggregation_type: SUM aggregation_key: bytes event_type_filter: in_values: - cpu_usage property_filters: - name: cpu_hours exists: true - name: region exists: true in_values: - EU - NA - name: machine_type exists: true in_values: - slow - fast group_keys: - - region - - machine_type archived_at: '2024-10-01T11:23:44Z' next_page: null components: schemas: PropertyFilter: type: object required: - name properties: name: type: string description: The name of the event property. exists: type: boolean description: Determines whether the property must exist in the event. If true, only events with this property will pass the filter. If false, only events without this property will pass the filter. If null or omitted, the existence of the property is optional. in_values: type: array items: type: string description: Specifies the allowed values for the property to match an event. An event will pass the filter only if its property value is included in this list. If undefined, all property values will pass the filter. Must be non-empty if present. not_in_values: type: array items: type: string description: Specifies the values that prevent an event from matching the filter. An event will not pass the filter if its property value is included in this list. If null or empty, all property values will pass the filter. Must be non-empty if present. GroupKeysArray: type: array items: type: array items: type: string description: Property names that are used to group usage costs on an invoice. Each entry represents a set of properties used to slice events into distinct buckets. EventTypeFilter: type: object properties: in_values: type: array items: type: string description: A list of event types that are explicitly included in the billable metric. If specified, only events of these types will match the billable metric. Must be non-empty if present. not_in_values: type: array items: type: string description: A list of event types that are explicitly excluded from the billable metric. If specified, events of these types will not match the billable metric. Must be non-empty if present. description: An optional filtering rule to match the 'event_type' property of an event. CreateBillableMetricPayload: type: object required: - name - aggregate - filter properties: name: type: string aggregate: type: string enum: - count - Count - COUNT - latest - Latest - LATEST - max - Max - MAX - sum - Sum - SUM - unique - Unique - UNIQUE aggregate_key: type: string filter: type: object description: JSON Schema filter to apply to the metric additionalProperties: true group_keys: type: array items: type: string group_values: type: array items: type: string BillableMetricWithDeprecatedFields: allOf: - $ref: '#/components/schemas/BillableMetricBase' - type: object properties: aggregation_type: $ref: '#/components/schemas/AggregationType' AggregationKey: type: string description: A key that specifies which property of the event is used to aggregate data. This key must be one of the property filter names and is not applicable when the aggregation type is 'count'. CustomField: type: object description: 'Custom fields to be added eg. { "key1": "value1", "key2": "value2" }' additionalProperties: type: string BillableMetricBase: required: - name - id type: object properties: group_by: type: array description: (DEPRECATED) use group_keys instead items: type: string description: A list of keys that can be used to additionally segment the values of the billable metric when making usage queries group_keys: $ref: '#/components/schemas/GroupKeysArray' name: type: string id: type: string format: uuid aggregate: type: string description: (DEPRECATED) use aggregation_type instead aggregate_keys: type: array description: (DEPRECATED) use aggregation_key instead items: type: string filter: type: object description: (DEPRECATED) use property_filters & event_type_filter instead additionalProperties: true aggregation_key: $ref: '#/components/schemas/AggregationKey' event_type_filter: $ref: '#/components/schemas/EventTypeFilter' property_filters: $ref: '#/components/schemas/PropertyFiltersArray' custom_fields: x-cf-entity: billable_metric $ref: '#/components/schemas/CustomField' sql: type: string description: The SQL query associated with the billable metric archived_at: type: string format: date-time description: RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived. Error: required: - message type: object properties: message: type: string PropertyFiltersArray: type: array items: $ref: '#/components/schemas/PropertyFilter' description: A list of filters to match events to this billable metric. Each filter defines a rule on an event property. All rules must pass for the event to match the billable metric. Id: required: - id type: object properties: id: type: string format: uuid AggregationType: type: string enum: - count - Count - COUNT - latest - Latest - LATEST - max - Max - MAX - sum - Sum - SUM - unique - Unique - UNIQUE description: Specifies the type of aggregation performed on matching events. BillableMetricV1: type: object required: - id - name properties: id: type: string format: uuid description: ID of the billable metric name: type: string description: The display name of the billable metric. event_type_filter: $ref: '#/components/schemas/EventTypeFilter' property_filters: $ref: '#/components/schemas/PropertyFiltersArray' aggregation_type: $ref: '#/components/schemas/AggregationType' aggregation_key: $ref: '#/components/schemas/AggregationKey' group_keys: $ref: '#/components/schemas/GroupKeysArray' custom_fields: $ref: '#/components/schemas/CustomField' sql: type: string description: The SQL query associated with the billable metric archived_at: type: string format: date-time description: RFC 3339 timestamp indicating when the billable metric was archived. If not provided, the billable metric is not archived. CreateBillableMetricV1Payload: type: object required: - name properties: name: type: string description: The display name of the billable metric. sql: type: string description: The SQL query associated with the billable metric. This field is mutually exclusive with aggregation_type, event_type_filter, property_filters, aggregation_key, and group_keys. If provided, these other fields must be omitted. event_type_filter: $ref: '#/components/schemas/EventTypeFilter' property_filters: $ref: '#/components/schemas/PropertyFiltersArray' aggregation_type: $ref: '#/components/schemas/AggregationType' aggregation_key: $ref: '#/components/schemas/AggregationKey' description: Specifies the type of aggregation performed on matching events. Required if `sql` is not provided. group_keys: $ref: '#/components/schemas/GroupKeysArray' custom_fields: description: Custom fields to attach to the billable metric. $ref: '#/components/schemas/CustomField' responses: NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error' parameters: NextPage: name: next_page in: query description: Cursor that indicates where the next page of results should start. required: false schema: type: string CustomerId: name: customer_id in: path required: true schema: type: string format: uuid example: d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc BillableMetricId: name: billable_metric_id in: path required: true schema: type: string format: uuid example: 13117714-3f05-48e5-a6e9-a66093f13b4d PageLimit: name: limit in: query description: Max number of results that should be returned required: false schema: type: integer minimum: 1 maximum: 100 securitySchemes: bearerAuth: type: http scheme: bearer