All API calls are read-only. Use $METRONOME_API_TOKEN for auth. Base URL: https://api.metronome.com/v1 (prod) or https://staging.api.metronome.com/v1 (sandbox).
Routing
| CSM asks... |
Mode |
Load |
| "which customers need attention", "MoM variance", "stuck invoices", "month-end review", "anomalies" |
Anomaly detection |
<references/anomaly-detection.md> |
| "how is [customer] tracking", "commit burn rate", "overrun risk", "will they run out", "commit health" |
Commit health |
<references/commit-health.md> |
| "monthly report", "portfolio briefing", "all-customer summary", "end of month", "who needs attention this month" |
Portfolio briefing |
<references/portfolio-briefing.md> |
| "prep for renewal", "renewal brief", "TCV scenarios", "contract expiring", "consumption trajectory" |
Renewal prep |
<references/renewal-prep.md> |
Read the relevant reference file before making any API calls or analysis.
Shared API calls
All modes use the same 5 endpoints. Collect data in this order per customer:
| Data needed |
Call |
| Customer UUID |
GET /v1/customers — match by name field from response |
| Contract terms, end date |
POST /v2/contracts/list with { "customer_id": "<id>" } |
| Commit / credit balances |
POST /v1/contracts/customerBalances/list with { "customer_id": "<id>", "include_balance": true } |
| Burn rate |
GET /v1/customers/{id}/costs?starting_on=<date>&ending_before=<date> — two calls, last 2 completed months |
| Invoice status |
GET /v1/customers/{id}/invoices?type=USAGE&sort=date-desc |
Shared thresholds
Apply these to FINALIZED data only. Never flag mid-month DRAFT invoices.
| Signal |
Threshold |
Flag |
| Commit % consumed |
≥ 80% |
🔴 Overrun risk |
| Commit % consumed |
< 20% at > 80% of contract term elapsed |
🟡 Breakage risk |
| MoM Δ% |
> +20% (FINALIZED invoices only) |
🟠 Spend spike |
| MoM Δ% |
< −20% (FINALIZED invoices only) |
🟡 Spend decline |
| Days to renewal |
≤ 30 |
🟠 Renewal imminent |
| Days to renewal |
31–90 |
🟡 Renewal upcoming |
| Stuck DRAFT invoice |
end_timestamp in the past, status still DRAFT |
🟠 Billing issue |
Fallback burn rate
If GET /v1/customers/{id}/costs returns $0 for a customer with an active commit, the customer is likely burning included credits first. Fall back to:
estimated_burn_rate = (original_balance − remaining_balance) / months_elapsed
Label any figure derived this way as estimated. Do not present it as a confirmed rate.
Mandatory gotchas
- All amounts are in cents. Divide by 100 before presenting. There is no
formatted_total field — use total from invoices and divide by 100. A balance of 5562901 = $55,629.01.
include_balance: true is required on customerBalances/list or percentage_consumed and remaining balance are null.customerBalances/list is capped at 25 results per page — unlike other endpoints (100 max). Paginate with next_page if a customer has many commits or credits.- Zero invoices ≠ anomaly. Some customers bill outside Metronome. Note "external invoicing" and skip invoice-based checks for that customer.
- Use completed months only for burn rate. Current period follows an S-curve (day 13 ≈ 37% of monthly total). Never use the current open period as the burn rate.
- If costs API returns $0 but FINALIZED USAGE invoices show non-zero totals, use invoice totals for trend analysis. The costs endpoint returns $0 when usage draws from a prepaid commit or custom credit type — invoice totals reflect actual charges after commit offset and are the reliable signal in those cases.
- If costs API returns $0 AND recent USAGE invoices are also $0 or absent, include this in the output: "No billing activity found in the review window. This customer may have been active in an earlier period — reply 'check history' to extend the lookback."
- Mid-month DRAFT invoices are not anomalies. Only flag DRAFT invoices whose
end_timestamp is in the past.
- Contract end date may be null. Evergreen contracts have no
ending_before. Ask the user before building any projections that require a fixed end date.
- Filter to
type=USAGE for burn rate. SCHEDULED invoices are flat platform fees — including them overstates consumption and inflates renewal pricing.
1---2name: metronome-csm-reviews3description: Customer health reviews for CSMs — anomaly detection (MoM spend variance, stuck DRAFT invoices, commit burn spikes), commit health (burn rate, overrun and breakage risk for a single customer), portfolio briefing (monthly all-customer report with exec summary and action items), and renewal prep (contract terms, trailing consumption, TCV scenarios). Use when asked which customers need attention, how a customer is tracking against their commit, for a monthly report or portfolio briefing, or to prep for a renewal.4---56All API calls are read-only. Use `$METRONOME_API_TOKEN` for auth. Base URL: `https://api.metronome.com/v1` (prod) or `https://staging.api.metronome.com/v1` (sandbox).78## Routing910| CSM asks... | Mode | Load |11| --- | --- | --- |12| "which customers need attention", "MoM variance", "stuck invoices", "month-end review", "anomalies" | Anomaly detection | <references/anomaly-detection.md> |13| "how is [customer] tracking", "commit burn rate", "overrun risk", "will they run out", "commit health" | Commit health | <references/commit-health.md> |14| "monthly report", "portfolio briefing", "all-customer summary", "end of month", "who needs attention this month" | Portfolio briefing | <references/portfolio-briefing.md> |15| "prep for renewal", "renewal brief", "TCV scenarios", "contract expiring", "consumption trajectory" | Renewal prep | <references/renewal-prep.md> |1617Read the relevant reference file before making any API calls or analysis.1819---2021## Shared API calls2223All modes use the same 5 endpoints. Collect data in this order per customer:2425| Data needed | Call |26| --- | --- |27| Customer UUID | `GET /v1/customers` — match by `name` field from response |28| Contract terms, end date | `POST /v2/contracts/list` with `{ "customer_id": "<id>" }` |29| Commit / credit balances | `POST /v1/contracts/customerBalances/list` with `{ "customer_id": "<id>", "include_balance": true }` |30| Burn rate | `GET /v1/customers/{id}/costs?starting_on=<date>&ending_before=<date>` — two calls, last 2 completed months |31| Invoice status | `GET /v1/customers/{id}/invoices?type=USAGE&sort=date-desc` |3233---3435## Shared thresholds3637Apply these to FINALIZED data only. Never flag mid-month DRAFT invoices.3839| Signal | Threshold | Flag |40| --- | --- | --- |41| Commit % consumed | ≥ 80% | 🔴 Overrun risk |42| Commit % consumed | < 20% at > 80% of contract term elapsed | 🟡 Breakage risk |43| MoM Δ% | > +20% (FINALIZED invoices only) | 🟠 Spend spike |44| MoM Δ% | < −20% (FINALIZED invoices only) | 🟡 Spend decline |45| Days to renewal | ≤ 30 | 🟠 Renewal imminent |46| Days to renewal | 31–90 | 🟡 Renewal upcoming |47| Stuck DRAFT invoice | `end_timestamp` in the past, status still DRAFT | 🟠 Billing issue |4849---5051## Fallback burn rate5253If `GET /v1/customers/{id}/costs` returns $0 for a customer with an active commit, the customer is likely burning included credits first. Fall back to:5455```56estimated_burn_rate = (original_balance − remaining_balance) / months_elapsed57```5859Label any figure derived this way as **estimated**. Do not present it as a confirmed rate.6061---6263## Mandatory gotchas6465- **All amounts are in cents.** Divide by 100 before presenting. There is no `formatted_total` field — use `total` from invoices and divide by 100. A balance of `5562901` = $55,629.01.66- **`include_balance: true` is required** on `customerBalances/list` or `percentage_consumed` and remaining balance are null.67- **`customerBalances/list` is capped at 25 results per page** — unlike other endpoints (100 max). Paginate with `next_page` if a customer has many commits or credits.68- **Zero invoices ≠ anomaly.** Some customers bill outside Metronome. Note "external invoicing" and skip invoice-based checks for that customer.69- **Use completed months only for burn rate.** Current period follows an S-curve (day 13 ≈ 37% of monthly total). Never use the current open period as the burn rate.70- **If costs API returns $0 but FINALIZED USAGE invoices show non-zero totals, use invoice totals for trend analysis.** The costs endpoint returns $0 when usage draws from a prepaid commit or custom credit type — invoice totals reflect actual charges after commit offset and are the reliable signal in those cases.71- **If costs API returns $0 AND recent USAGE invoices are also $0 or absent**, include this in the output: *"No billing activity found in the review window. This customer may have been active in an earlier period — reply 'check history' to extend the lookback."*72- **Mid-month DRAFT invoices are not anomalies.** Only flag DRAFT invoices whose `end_timestamp` is in the past.73- **Contract end date may be null.** Evergreen contracts have no `ending_before`. Ask the user before building any projections that require a fixed end date.74- **Filter to `type=USAGE` for burn rate.** SCHEDULED invoices are flat platform fees — including them overstates consumption and inflates renewal pricing.
metronome-industries