List spend invoice breakdowns

curl --request POST \
  --url https://api.metronome.com/v1/customers/{customer_id}/invoices/spend-breakdowns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "starting_on": "2021-01-01T00:00:00Z",
  "ending_before": "2021-02-01T00:00:00Z",
  "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
  "window_size": "day",
  "sort": "date_desc",
  "group_keys": [
    "region"
  ]
}
'

{
  "data": [
    {
      "id": "6a37bb88-8538-48c5-b37b-a41c836328bd",
      "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989",
      "type": "USAGE",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-02-01T00:00:00Z",
      "breakdown_start_timestamp": "2021-01-01T00:00:00Z",
      "breakdown_end_timestamp": "2021-01-02T00:00:00Z",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "contract_id": "9de042a1-b955-43ce-9ab4-e3c2004570d1",
      "line_items": [
        {
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "name": "CPU hours",
          "type": "usage",
          "quantity": 1488,
          "total": 14392,
          "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8"
        }
      ],
      "status": "DRAFT"
    },
    {
      "id": "6a37bb88-8538-48c5-b37b-a41c836328bd",
      "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989",
      "type": "USAGE",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-02-01T00:00:00Z",
      "breakdown_start_timestamp": "2021-01-02T00:00:00Z",
      "breakdown_end_timestamp": "2021-01-03T00:00:00Z",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "contract_id": "9de042a1-b955-43ce-9ab4-e3c2004570d1",
      "line_items": [
        {
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "name": "CPU hours",
          "type": "usage",
          "quantity": 1488,
          "total": 14392,
          "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8"
        }
      ],
      "status": "DRAFT"
    }
  ],
  "next_page": null
}

Invoices

List spend invoice breakdowns

Granularly analyze customer spend patterns by dynamically slicing and dicing costs across any dimension. This endpoint empowers you to break down spending by granular properties like user, organization, model, region, or any custom event property—even if these aren’t the default groupings on your invoices. Unlike standard invoice breakdowns, this endpoint focuses purely on spend analysis, making helpful for building powerful cost analytics dashboards that show spend before credit/commit application.

Use this endpoint to:

Identify cost drivers: Pinpoint which users, teams, or resources are driving the most spend
Build usage analytics dashboards: Let customers explore their costs by any event property (user_id, org_id, model_id, region, etc.)
Enable showback/chargeback: Allocate costs to specific departments, projects, or cost centers
Detect anomalies: Find unexpected spending patterns by analyzing costs across different dimensions
Optimize resource usage: Help customers identify underutilized or over-provisioned resources
Support multi-tenancy: Show spending breakdowns for specific organizations within a single account
Create custom reports: Generate executive dashboards with spending by any business-relevant dimension

Key response fields:

Spend-focused invoice data with:

Pure spend information: No commits or credits—just raw spending data for cleaner analysis
Dynamic grouping: Line items grouped by your specified group_keys (overriding default presentation groups)
Filtered results: Only line items matching your group_filters criteria
Flexible time windows: Daily, hourly, or full-period (none) breakdowns
Complete line item details: Including quantities, unit prices, and custom presentation group values

Usage guidelines:

Group key setup: All keys used in group_keys, group_filters, and pricing groups must exist in the same compound group key on the billable metric
Supported window sizes: hour, day, or none (for full period analysis)
Filtering power: Use group_filters to focus on specific values (e.g., only show data for specific user_ids)
Override flexibility: Change how costs are grouped without affecting actual invoicing

Limitations:

Cannot override group keys when using:
- MAX aggregation billable metrics
- Tiered pricing
- Quantity rounding
- Commit-specific overrides
- Overrides on presentation group values

POST

customers

{customer_id}

invoices

spend-breakdowns

List spend invoice breakdowns

curl --request POST \
  --url https://api.metronome.com/v1/customers/{customer_id}/invoices/spend-breakdowns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "starting_on": "2021-01-01T00:00:00Z",
  "ending_before": "2021-02-01T00:00:00Z",
  "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
  "window_size": "day",
  "sort": "date_desc",
  "group_keys": [
    "region"
  ]
}
'

{
  "data": [
    {
      "id": "6a37bb88-8538-48c5-b37b-a41c836328bd",
      "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989",
      "type": "USAGE",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-02-01T00:00:00Z",
      "breakdown_start_timestamp": "2021-01-01T00:00:00Z",
      "breakdown_end_timestamp": "2021-01-02T00:00:00Z",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "contract_id": "9de042a1-b955-43ce-9ab4-e3c2004570d1",
      "line_items": [
        {
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "name": "CPU hours",
          "type": "usage",
          "quantity": 1488,
          "total": 14392,
          "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8"
        }
      ],
      "status": "DRAFT"
    },
    {
      "id": "6a37bb88-8538-48c5-b37b-a41c836328bd",
      "customer_id": "617e39d8-68f4-4592-b8d2-c2bf26a76989",
      "type": "USAGE",
      "start_timestamp": "2021-01-01T00:00:00Z",
      "end_timestamp": "2021-02-01T00:00:00Z",
      "breakdown_start_timestamp": "2021-01-02T00:00:00Z",
      "breakdown_end_timestamp": "2021-01-03T00:00:00Z",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "contract_id": "9de042a1-b955-43ce-9ab4-e3c2004570d1",
      "line_items": [
        {
          "credit_type": {
            "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
            "name": "USD (cents)"
          },
          "name": "CPU hours",
          "type": "usage",
          "quantity": 1488,
          "total": 14392,
          "product_id": "5c1f40cd-9ff8-4e90-ae53-5f81b0e9d1e8"
        }
      ],
      "status": "DRAFT"
    }
  ],
  "next_page": null
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

customer_id

string<uuid>

required

Query Parameters

include_list_prices

boolean

If set, list prices will be returned for each contract usage and subscription line item.

Body

application/json

starting_on

string<date-time>

required

RFC 3339 timestamp. Breakdowns will only be returned for time windows that start on or after this time.

ending_before

string<date-time>

required

RFC 3339 timestamp. Breakdowns will only be returned for time windows that end on or before this time.

skip_zero_qty_line_items

boolean

If set, all zero quantity line items will be filtered out of the response.

credit_type_id

string<uuid>

If provided, only invoices with the specified credit type id will be included in the response.

sort

enum<string>

default:date_asc

Invoice sort order by issued_at, e.g. date_asc or date_desc. Defaults to date_asc.

Available options:

date_asc,

date_desc

window_size

enum<string>

The granularity of the breakdowns to return. Defaults to "day".

Available options:

hour,

day,

none,

HOUR,

DAY,

NONE,

Hour,

Day,

None

group_keys

string[]

A list of keys that can be used to additionally segment the values of the billable metric when making usage queries. Must be valid keys that are present in the billable metrics or an empty list. The value will be ignored and the default keys will be used if: billable metric is MAX type; product uses tiered pricing model; product has quantity rounding enabled; there are contract overrides based on presentation group keys

group_filters

object

An object where the keys are the group keys and the values are arrays of group values. If the values is an empty array, the returned usage data will be aggregated across all values for that key. The value will be ignored and the default keys will be used if: billable metric is MAX type; product uses tiered pricing model; product has quantity rounding enabled; there are contract overrides based on presentation group keys

Show child attributes

limit

integer

default:100

Max number of results that should be returned. For daily and "none" breakdowns, the response can return up to 35 days worth of breakdowns. For hourly breakdowns, the response can return up to 24 hours. If there are more results, a cursor to the next page is returned.

Required range: 1 <= x <= 100

next_page

string

Cursor that indicates where the next page of results should start.

Response

Success

data

object[]

required

Show child attributes

next_page

string | null

required

⌘I