Skip to main content

Evaluate price​

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, 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 required
    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 date-time required

    The inclusive lower bound for event timestamps

    timeframe_end date-time required

    The exclusive upper bound for event timestamps

    filter string nullable

    A boolean computed property used to filter the underlying billable metric

    grouping_keys string[]

    Default value: []

    Properties (or computed properties) used to group the underlying billable metric

Responses

OK

Response Headers
    Schema
      data object[] required
    • Array [
      • grouping_values object[] required

      The values for the group in the order specified by grouping_keys

    • Array [
      • oneOf

      string

    • ]
      • quantity number required

      The price's usage quantity for the group

      amount string required

      The price's output for the group

    • ]
    Loading...