---
title: "Evaluate an expression for a billable metric"
method: POST
path: "/billable_metrics/evaluate_expression"
tags: ["billable_metrics"]
---

# Evaluate an expression for a billable metric

`POST /billable_metrics/evaluate_expression`

## Request

- Base URL: `https://api.getlago.com/api/v1`
- URL: `https://api.getlago.com/api/v1/billable_metrics/evaluate_expression`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/getlago/apis/lago-api-documentation/docs/billable_metrics/evaluate_expression/post.ts> (a function with typed inputs; its response is checked against the schema)

This endpoint evaluates an expression against a test event. Use it to check an expression before you set it on a billable metric.

## Request body

- BillableMetricEvaluateExpressionInput
  - `expression` string, required: Expression used to calculate the event units. The expression is evaluated for each event and the result is then used to calculate the total aggregated units. Event values are read with `event.code`, `event.timestamp` and `event.properties.<name>`. Accepted functions are `ceil`, `concat`, `floor`, `greatest`, `least` and `round` as well as `+`, `-`, `/` and `*` operations. `ceil`, `floor` and `round` accept an optional second parameter to specify the number of decimals.
  - `event` object, required
    - `code` string: The code that identifies a targeted billable metric.
    - `timestamp` union: This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception.
      - integer
      - string
    - `properties` object: This field represents additional properties associated with the event. They can be used when evaluating the expression.

## Response `200`

Billable metric expression evaluation result

- BillableMetricEvaluateExpressionResult
  - `expression_result` object, required
    - `value` string, required: Result of evaluating the expression. A numeric result is returned as a decimal string.

## Other responses

- `400`: Bad Request error
- `401`: Unauthorized error
- `422`: Unprocessable entity error

## Changes

- **2026-11-05** `b216574b9612`: 2 info
  - the request property `event/code` became optional
  - the request property `event/properties` became optional
- **2026-11-03** `5d26657495a3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getlago/apis/lago-api-documentation/changes/billable_metrics/evaluate_expression/post.md)

---

[API](https://skmtc.dev/getlago/apis/lago-api-documentation.md) - [All operations](https://skmtc.dev/getlago/apis/lago-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/getlago/apis/lago-api-documentation/revisions/b216574b9612?raw)