> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vantage.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Metronome

> Import Metronome revenue and usage data into Vantage as business metrics.

Vantage integrates with [Metronome](https://metronome.com/) to bring billing revenue and product usage data into Vantage as [Business Metrics](/per_unit_costs). You can then analyze Metronome revenue and usage alongside Vantage cost data to understand customer profitability, cost per unit, gross margin, and pricing efficiency.

Metronome is connected from the Apps section of Vantage. It does not import Metronome as a cost provider. Instead, Vantage imports Metronome data as labeled business metrics that can be assigned to [Cost Reports](/cost_reports), used in [Canvas](/canvas), and queried with the [FinOps Agent](/vantage_finops_agent).

## How It Works

Vantage connects to the Metronome API with a bearer token, discovers revenue and usage data, and imports the selected data into Vantage business metrics. Each imported row is daily and can be labeled by customer so you can compare cost, usage, and revenue at the same level of detail.

```mermaid theme={null}
flowchart LR
    Metronome[Metronome API] --> Revenue["Daily Invoice Revenue"]
    Metronome --> Usage["Billable Metric Usage"]
    Revenue --> BusinessMetrics["Vantage Business Metrics"]
    Usage --> BusinessMetrics
    BusinessMetrics --> CostReports["Cost Reports and Unit Costs"]
    BusinessMetrics --> Canvas["Canvas"]
    BusinessMetrics --> Agent["FinOps Agent"]
```

Vantage can import two kinds of Metronome business metrics:

| Metric type           | Metronome source             | Use it for                                                                                                    |
| --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Daily invoice revenue | Metronome invoice breakdowns | Revenue, gross margin, customer profitability, and cost as a percentage of revenue                            |
| Usage                 | Metronome billable metrics   | Cost per compute hour, API request, storage GB-hour, AI token, seat, transaction, or other product usage unit |

Labels identify the customer associated with the metric value. When configuring the import, you can choose one of the following label sources:

| Label source  | Best for                                                                 |
| ------------- | ------------------------------------------------------------------------ |
| Customer name | Human-readable customer profitability and usage analysis                 |
| Ingest alias  | Cleaner or external customer identifiers already maintained in Metronome |
| Customer ID   | Stable joins and troubleshooting when names or aliases are not available |

<Note>
  Metronome business metrics sync daily. Initial imports and reimports can take time to finish, especially when importing historical data across many customers or billable metrics.
</Note>

## Connect Metronome

### Prerequisites

Before you connect Metronome to Vantage, make sure you have:

* A Vantage role that can manage integrations, such as **Organization Owner** or **Integration Owner**. See [Role-Based Access Control](/rbac).
* Access to create or retrieve a Metronome API token.
* A Metronome token that can access customers, invoice breakdowns, usage queries, and billable metrics.

Metronome API tokens use bearer authentication. See Metronome's [API authentication documentation](https://docs.metronome.com/api-reference/authentication) and [RBAC documentation](https://docs.metronome.com/guides/platform-configuration/role-based-access-rbac#assign-a-role-to-an-api-token) for details on creating and scoping API tokens.

<Tip>
  If your Metronome workspace uses RBAC roles for API tokens, use an Administrator, Writer, or custom role that can access customer records, invoice breakdowns, usage data, and billable metrics. Metronome roles cannot be changed after token creation, so create a new token if the current one is too limited.
</Tip>

### Create the Connection

<Steps>
  <Step title="Open the Metronome integration">
    In Vantage, navigate to [Settings > Metronome](https://console.vantage.sh/settings/metronome?connect=true). You can also open **Settings**, select **Integrations**, then choose **Metronome** from the Apps section.
  </Step>

  <Step title="Enter connection details">
    Click **Add API Key**. Enter a descriptive account name and paste your Metronome API token.
  </Step>

  <Step title="Connect the account">
    Click **Connect Account**. Vantage validates the token by checking that it can read Metronome customers and query usage data.
  </Step>

  <Step title="Create your first business metric">
    After the account is connected, create one or more Metronome-backed business metrics from **Financial Planning > Business Metrics**. See [Import from Metronome](/per_unit_costs#import-from-metronome) for the full workflow.
  </Step>
</Steps>

<Warning>
  Store your Metronome API token securely. Do not paste the token into Canvas, the FinOps Agent, Slack, or any client-side application.
</Warning>

## Validate the Setup

After connecting Metronome, create one revenue metric and one usage metric before building reports (see [Import from Metronome](/per_unit_costs#import-from-metronome) for details). This gives you a quick way to confirm the connection, metric discovery, labels, and imported values are working.

<Steps>
  <Step title="Create a revenue metric">
    Create a new business metric, select **Import via Metronome**, choose your connected Metronome account, and select **Daily invoice revenue**. Use a clear name like `Metronome Revenue`.
  </Step>

  <Step title="Create a usage metric">
    Create a second business metric, select the same Metronome account, and choose a billable usage metric such as `Compute Hours`, `API Requests`, `Storage GB-Hours`, `AI Tokens`, or `Virtual Machine Hours`.
  </Step>

  <Step title="Check labels and values">
    Open the **Imported Metrics** tab for each business metric. Confirm that rows appear by date and that labels match the customer naming style you expected.
  </Step>

  <Step title="Assign the metrics to Cost Reports">
    Assign the metrics to Cost Reports only after the imported values look correct. For example, assign `Metronome Virtual Machine Hours` to a COGS Cost Report to calculate cost per VM hour.
  </Step>
</Steps>

## Example Workflows

The examples below assume you already created Metronome-backed business metrics in Vantage and that you have at least one Cost Report that represents COGS or product infrastructure cost. Replace the metric and report names with the names in your account.

### Top Customers by Usage

Use this when you want to find which customers are driving the most product usage before you look at cost or revenue.

<Prompt description={`Show my top customers by Metronome usage over the last 30 days. Use the "Metronome Virtual Machine Hours" business metric, group by customer label, include total usage, daily average usage, and share of total usage, and sort descending.`} actions={["copy"]}>
  Show my top customers by Metronome usage over the last 30 days. Use the "Metronome Virtual Machine Hours" business metric, group by customer label, include total usage, daily average usage, and share of total usage, and sort descending.
</Prompt>

Expected output: one row per customer with usage totals and share of usage. Use this to identify the customers that should be reviewed first for unit cost, margin, or pricing analysis.

<Frame>
  <img src="https://assets.vantage.sh/docs/metronome-canvas-prompt.png" alt="Canvas table showing top customers by Metronome usage" />
</Frame>

### COGS and Unit Cost by Customer

Use this when you have a Cost Report for product COGS and a Metronome usage metric with customer labels.

<Prompt description={`Using my "COGS" Cost Report and the "Metronome Virtual Machine Hours" business metric, calculate cost per VM hour by customer for the last 30 days. Include total COGS, total VM hours, cost per VM hour, and rank customers by total COGS.`} actions={["copy"]}>
  Using my "COGS" Cost Report and the "Metronome Virtual Machine Hours" business metric, calculate cost per VM hour by customer for the last 30 days. Include total COGS, total VM hours, cost per VM hour, and rank customers by total COGS.
</Prompt>

Expected output: one row per customer with cost, usage, and cost per unit. Use this to find customers whose usage is disproportionately expensive.

### Gross Margin by Customer

Use this when you import Metronome revenue and want to compare it with Vantage COGS for the same customer labels.

<Prompt description={`Compare "Metronome Revenue" to my "COGS" Cost Report for the last month. Group by customer label and include revenue, COGS, gross margin dollars, and gross margin percent.`} actions={["copy"]}>
  Compare "Metronome Revenue" to my "COGS" Cost Report for the last month. Group by customer label and include revenue, COGS, gross margin dollars, and gross margin percent.
</Prompt>

Expected output: a customer profitability table. Review low or negative margin customers first, then inspect the underlying Cost Report filters and usage metric labels.

### Pricing Targets from Current Unit Cost

Use this when you know the current cost per product unit and want to evaluate price points for target margins.

<Prompt description={`Use my current cost per VM hour from the "COGS" Cost Report and "Metronome Virtual Machine Hours" business metric to suggest prices that would produce 20%, 40%, and 60% gross margin. Show the formula and include one row per target margin.`} actions={["copy"]}>
  Use my current cost per VM hour from the "COGS" Cost Report and "Metronome Virtual Machine Hours" business metric to suggest prices that would produce 20%, 40%, and 60% gross margin. Show the formula and include one row per target margin.
</Prompt>

Expected output: a table with current cost per unit and suggested price per unit for each target margin. Use the result as a pricing input in Metronome.

### Usage-Based Cost Allocation

Use this when a shared platform cost should be allocated to customers based on their share of Metronome usage.

<Prompt description={`Allocate shared cloud and platform costs in my "COGS" Cost Report to customers based on the "Metronome Virtual Machine Hours" labels, then show COGS by customer and cost per VM hour for the last 30 days.`} actions={["copy"]}>
  Allocate shared cloud and platform costs in my "COGS" Cost Report to customers based on the "Metronome Virtual Machine Hours" labels, then show COGS by customer and cost per VM hour for the last 30 days.
</Prompt>

Expected output: customer-level cost allocation based on usage share. If you want the allocation to be reusable across reports, create a [Virtual Tag](/tagging) that uses the Metronome business metric as the allocation basis.

### Product Usage Portfolio

Use this when you import several Metronome usage metrics and want to see which product dimension is growing fastest.

<Prompt description={`Show daily Metronome usage for Compute Hours, API Requests, Storage GB-Hours, and AI Tokens for the last 30 days. Include one row per product metric and day, and call out the fastest-growing metric.`} actions={["copy"]}>
  Show daily Metronome usage for Compute Hours, API Requests, Storage GB-Hours, and AI Tokens for the last 30 days. Include one row per product metric and day, and call out the fastest-growing metric.
</Prompt>

Expected output: daily usage by product metric. Use this to decide which usage unit should be paired with a Cost Report first.

## Ask the FinOps Agent

You can also ask the [FinOps Agent](/vantage_finops_agent) one-off questions about Metronome-backed business metrics in the Vantage console. Name the relevant business metric and Cost Report so the agent can scope the analysis.

Try prompts like:

* `Which customers had the highest Metronome usage last month, and how did their COGS compare?`
* `Use my Metronome Revenue business metric and my COGS Cost Report to find customers below 30% gross margin.`
* `Explain why cost per VM hour increased last week for my Metronome Virtual Machine Hours metric.`
* `Create a Cost Report that uses my COGS filters and assign the Metronome API Requests business metric to show cost per thousand requests.`

## Related Metronome Documentation

The Vantage integration uses these Metronome concepts and APIs:

* [API authentication](https://docs.metronome.com/api-reference/authentication)
* [Assign an RBAC role to an API token](https://docs.metronome.com/guides/platform-configuration/role-based-access-rbac#assign-a-role-to-an-api-token)
* [Billable metrics](https://docs.metronome.com/guides/implement-metronome/core-concepts/create-billable-metrics)
* [List all billable metrics](https://docs.metronome.com/api-reference/billable-metrics/list-all-billable-metrics)
* [Get batched usage data](https://docs.metronome.com/api-reference/usage/get-batched-usage-data)
* [List invoice breakdowns](https://docs.metronome.com/api-reference/invoices/list-invoice-breakdowns)

## Troubleshooting

<AccordionGroup>
  <Accordion title="I do not see Metronome in Settings or Business Metrics">
    Confirm that your Vantage user has permission to manage integrations. You need a role such as **Organization Owner** or **Integration Owner**.
  </Accordion>

  <Accordion title="The API token is rejected">
    Vantage validates the token by checking customer and usage access. If the token is rejected, create a new Metronome API token with access to customers, invoice breakdowns, usage queries, and billable metrics.

    If your Metronome account uses RBAC for API tokens, assign an Administrator, Writer, or custom role with access to those endpoints. See Metronome's [RBAC documentation](https://docs.metronome.com/guides/platform-configuration/role-based-access-rbac#assign-a-role-to-an-api-token).
  </Accordion>

  <Accordion title="Usage metrics do not appear in the dropdown">
    The usage metric dropdown is populated from Metronome billable metrics. If it is empty, confirm that the token can access `GET /v1/billable-metrics` and that your Metronome account has active billable metrics.

    After confirming permissions, refresh the metric list or try reconnecting with a new token.
  </Accordion>

  <Accordion title="The metric is stuck in Pending or data looks stale">
    Initial imports and daily refreshes can take time to finish. Check again after the import completes or after the next daily sync.

    If the metric remains pending, confirm that the Metronome connection is still active and that the business metric is connected to the intended Metronome account and metric type.
  </Accordion>

  <Accordion title="Labels are customer IDs instead of names">
    Check the label source selected for the business metric. If you selected **Customer ID**, Vantage uses the raw Metronome customer ID.

    If you selected **Ingest alias** or **Customer name**, Vantage can fall back to the customer ID when that value is not available in Metronome. Edit the business metric configuration if you want a different label source.
  </Accordion>

  <Accordion title="Two customers have similar labels">
    If two Metronome customers have the same name, Vantage disambiguates the labels with an ID suffix. This is expected and helps prevent two customers from being merged into one labeled metric.
  </Accordion>

  <Accordion title="Revenue is missing but usage is present">
    Usage can exist before a customer is billed or before a product has billable revenue configured in Metronome. In that case, usage metrics appear in Vantage, but revenue may be zero or missing for the same customer and date range.

    Confirm that the customer has invoice data in Metronome for the selected period, then rerun the analysis for a date range that includes billed revenue.
  </Accordion>

  <Accordion title="Totals do not match a Cost Report">
    Compare the Canvas or FinOps Agent prompt against the Cost Report. Make sure the prompt uses the same workspace, report, date range, cost settings, and business metric labels.

    For unit cost analysis, also confirm that the Cost Report contains the COGS or product costs you want to divide by the Metronome metric. If the report contains all company costs, the cost per unit may be inflated.
  </Accordion>

  <Accordion title="Metronome is not listed with cost provider integrations">
    This is expected. Metronome is connected from Apps and imports revenue and usage as business metrics. It does not import provider costs into Vantage.

    To analyze Metronome data with costs, assign the Metronome business metric to a Cost Report or reference it in Canvas or the FinOps Agent.
  </Accordion>
</AccordionGroup>