---
title: "Evaluate price"
method: POST
path: "/prices/{price_id}/evaluate"
tags: ["Price"]
---

# Evaluate price

`POST /prices/{price_id}/evaluate`

[NOTE] It is recommended to use the `/v1/prices/evaluate` which offers further functionality, such as multiple prices, inline
price definitions, and querying over preview events.

This endpoint is used to evaluate the output of a price for a given customer and time range.
It enables filtering and grouping the output using
[computed properties](/extensibility/advanced-metrics#computed-properties),
supporting the following workflows:

1. Showing detailed usage and costs to the end customer.
2. Auditing subtotals on invoice line items.

For these workflows, the expressiveness of computed properties in both the filters and grouping is critical.
For example, if you'd like to show your customer their usage grouped by hour and another property, you can
do so with the following `grouping_keys`:
`["hour_floor_timestamp_millis(timestamp_millis)", "my_property"]`.
If you'd like to examine a customer's usage for a specific property value, you can do so with the following `filter`:
`my_property = 'foo' AND my_other_property = 'bar'`.

By default, the start of the time range must be no more than 100 days ago and the length of the results
must be no greater than 1000. Note that this is a POST endpoint rather than a GET endpoint because it
employs a JSON body rather than query parameters.

## Path parameters

- `price_id` string, required

## Request body

- EvaluatePriceBody
  - `customer_id` string, nullable — The ID of the customer to which this evaluation is scoped.
  - `external_customer_id` string, nullable — The external customer ID of the customer to which this evaluation is scoped.
  - `timeframe_start` string, date-time, required — The inclusive lower bound for event timestamps
  - `timeframe_end` string, date-time, required — The exclusive upper bound for event timestamps
  - `filter` string, nullable — A boolean [computed property](/extensibility/advanced-metrics#computed-properties) used to filter the underlying billable metric
  - `grouping_keys` string[] — Properties (or [computed properties](/extensibility/advanced-metrics#computed-properties)) used to group the underlying billable metric
  - `metric_parameter_overrides` object, nullable — Optional overrides for parameterized billable metric parameters. If the metric has parameter definitions and no overrides are provided, defaults will be used.

## Response `200`

OK

- EvaluatePriceResource
  - `data` EvaluatePriceGroup[], required
    - `grouping_values` union[], required — The values for the group in the order specified by `grouping_keys`
      - union
        - string
        - number
        - boolean
    - `quantity` number, required — The price's usage quantity for the group
    - `amount` string, required — The price's output for the group

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

## Changes

- **2026-02-18** `3c7ee3ec9931` — 1 info
  - added the new optional request property `metric_parameter_overrides`

[Change history](https://skmtc.dev/orbcorp/apis/api-reference/changes/prices/:price_id/evaluate/post.md)

---

[API](https://skmtc.dev/orbcorp/apis/api-reference.md) · [All operations](https://skmtc.dev/orbcorp/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/orbcorp/api-reference/revisions/2580a0ee8d4c/schema)