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

# Metronome source connector

> Read Metronome customers, contracts, billing, usage, and reference data with Filament.

Connector ID `metronome`

The Metronome source provides 46 selectable resources through an
[HTTP manifest](https://filament.getgalaxy.io/pages/connectors/building-a-connector/http-manifests.md).
It targets Contracts v2 with the shared v1 endpoints and optional legacy Plans
reads. Use `metronome@v2` to pin this API selection. `metronome` resolves to it.
The connector is in preview. Its API contracts and shared engine have been
checked locally, but live account reads have not been validated.

## Configuration

| Field | Scope | Default | Description |
| - | - | - | - |
| `ingestion` | Connection | `api` | `api` reads the Metronome API. `webhooks` receives notifications and needs no API fields. `both` does both. See [Webhooks](#webhooks). |
| `api_token` | Connection | | Required secret. API token with access to selected resources. |
| `customer_archived_states` | Connection | `false,true` | Active and archived customers. `false` selects active only and `true` selects archived only. Also controls customer-dependent reads. |
| `start_date` | Pipeline | | Inclusive UTC date for usage, invoice breakdowns, spend breakdowns, and legacy costs. |
| `end_date` | Pipeline | | Exclusive UTC date for the same resources. Must be later than `start_date`. |

Dates use `YYYY-MM-DD` and are sent at UTC midnight. Windowed resources require
both `start_date` and `end_date`. Other resources do not require a date window.

Create a token under **Developer → API tokens** in the Metronome app. Tokens
inherit their creator's permissions unless Metronome applies narrower access.
Use a read-only token for the intended environment and grant access to each
selected endpoint, including POST reads. See
[API authentication](https://docs.metronome.com/api-reference/authentication).
Connection testing reads one billable-metrics page and requires access to that
endpoint. Discovery alone does not test access.

## Resources

The default selection includes billable metrics, customers, products, rate cards,
pricing units, custom field keys, account billing providers, customer billing
configurations, contracts, commits, credits, packages, and invoices. All other
resources are opt-in.

### Customers and reference data

| Resource | Endpoint | Parent |
| - | - | - |
| `billable_metrics` | `GET /v1/billable-metrics` | |
| `customers` | `GET /v1/customers` | |
| `products` | `POST /v1/contract-pricing/products/list` | |
| `rate_cards` | `POST /v1/contract-pricing/rate-cards/list` | |
| `pricing_units` | `GET /v1/credit-types/list` | |
| `custom_field_keys` | `POST /v1/customFields/listKeys` | |
| `billing_providers` | `POST /v1/listConfiguredBillingProviders` | |
| `customer_billing_configurations` | `POST /v1/getCustomerBillingProviderConfigurations` | `customers` |
| `customer_billable_metrics` | `GET /v1/customers/{customer_id}/billable-metrics` | `customers` |

### Contracts, commitments, and packages

| Resource | Endpoint | Parent |
| - | - | - |
| `contracts` | `POST /v2/contracts/list` | `customers` |
| `contract_edit_history` | `POST /v2/contracts/getEditHistory` | `contracts` |
| `commits` | `POST /v1/contracts/customerCommits/list` | `customers` |
| `credits` | `POST /v1/contracts/customerCredits/list` | `customers` |
| `balances` | `POST /v1/contracts/customerBalances/list` | `customers` |
| `seat_balances` | `POST /v1/contracts/seatBalances/list` | `contracts` |
| `subscriptions` | `POST /v2/contracts/get` | `contracts` |
| `subscription_quantity_history` | `POST /v1/contracts/getSubscriptionQuantityHistory` | `subscriptions` |
| `subscription_seats_history` | `POST /v1/contracts/getSubscriptionSeatsHistory` | `subscriptions` |
| `packages` | `POST /v1/packages/list` | |
| `package_contracts` | `POST /v1/packages/listContractsOnPackage` | `packages` |

### Invoices, usage, and rates

| Resource | Endpoint | Parent |
| - | - | - |
| `invoices` | `GET /v1/customers/{customer_id}/invoices` | `customers` |
| `invoice_breakdowns` | `GET /v1/customers/{customer_id}/invoices/breakdowns` | `customers` |
| `usage` | `POST /v1/usage` | |
| `rate_card_rate_schedules` | `POST /v1/contract-pricing/rate-cards/getRateSchedule` | `rate_cards` |
| `contract_rates` | `POST /v1/contracts/getContractRateSchedule` | `contracts` |
| `net_balances` | `POST /v1/contracts/customerBalances/getNetBalance` | `customers, pricing_units` |
| `net_quantity_balances` | `POST /v1/contracts/customerBalances/getNetBalance` | `customers` |

### Notifications

| Resource | Endpoint | Parent |
| - | - | - |
| `threshold_notifications` | `POST /v1/customer-alerts/list` | `customers` |
| `offset_notifications` | `POST /v2/notifications/offset/list` | |
| `system_notifications` | `POST /v2/notifications/system/list` | |

### Administration

| Resource | Endpoint | Parent |
| - | - | - |
| `services` | `GET /v1/services` | |

### Account-specific features

| Resource | Endpoint | Parent |
| - | - | - |
| `approval_requests` | `GET /v1/approval_requests` | |
| `customer_revenue_configurations` | `POST /v1/getCustomerRevenueSystemConfigurations` | `customers` |
| `historical_balances` | `POST /v1/contracts/historicalBalances/list` | `customers` |
| `spend_invoice_breakdowns` | `POST /v1/customers/{customer_id}/invoices/spend-breakdowns` | `customers` |
| `contract_named_schedules` | `POST /v1/contracts/listNamedSchedules` | `customers` |

### Legacy Plans and amendments

| Resource | Endpoint | Parent |
| - | - | - |
| `legacy_contracts` | `POST /v1/contracts/list` | `customers` |
| `plans` | `GET /v1/plans` | |
| `plan_details` | `GET /v1/planDetails/{plan_id}` | `plans` |
| `plan_charges` | `GET /v1/planDetails/{plan_id}/charges` | `plans` |
| `plan_customers` | `GET /v1/planDetails/{plan_id}/customers` | `plans` |
| `customer_plans` | `GET /v1/customers/{customer_id}/plans` | `customers` |
| `customer_plan_adjustments` | `GET /v1/customers/{customer_id}/plans/{customer_plan_id}/priceAdjustments` | `customer_plans` |
| `credit_grants` | `POST /v1/credits/listGrants` | |
| `credit_ledger_entries` | `POST /v1/credits/listEntries` | |
| `customer_costs` | `GET /v1/customers/{customer_id}/costs` | `customers` |

Each list emits one row per returned object. Related line items, ledgers,
contract terms, subscription schedules, package terms, and notification policies
remain JSON arrays or objects. IDs remain strings,
amounts and fractional quantities use decimal projections, and timestamps carry
time zones. Every resource includes a `raw` remainder for additional fields.

Contract responses can truncate embedded commits and credits. Use `commits` and
`credits` for their complete paginated lists, including contract-level and archived
records with ledgers and balances. `balances` provides the combined view.
`seat_balances` includes all returned seats with their credits, commits, and ledgers.
See [list customer contracts](https://docs.metronome.com/api-reference/contracts/list-customer-contracts-v2)
and [list seat balances](https://docs.metronome.com/api-reference/credits-and-commits/list-seat-balances).

`subscriptions` reads the subscription array from each contract detail. Quantity
history includes past changes, while future quantity schedules remain on the
subscription. Seat history returns schedule segments and assigned seat IDs.
`net_balances` queries each customer and pricing unit separately, including custom
units. `net_quantity_balances` queries quantity-based balances separately. These
are current snapshots and include draft invoice deductions under the API default.

`usage` reads daily aggregates for all customers and metrics in the selected
window without requesting truncated inline groupings. Rate card schedules include
every past and future segment. Contract rates reflect the schedule in effect when
the read runs. Invoice breakdowns emit daily windows. Spend breakdowns use the
API's default presentation groups.

Approval requests, revenue system configurations, historical balances, spend
breakdowns, and named schedules come from the
[official OpenAPI specification](https://api.metronome.com/v1/docs/openapi).
These include feature-gated and private-preview APIs. Enable only resources your
account supports. Contract named schedules use the listing endpoint and retain
property-qualified schedules and all segments.

Legacy Plans resources are optional for accounts that still use that deprecated
product. `legacy_contracts` retains the v1 initial, current, and amendment views.
`plan_details` adds minimums, overage rates, and plan credit-grant definitions.
`plan_customers` includes past, current, and upcoming assignments. Legacy grants
and ledgers exclude voided grants upstream. Legacy costs do not support plans
with UNIQUE billable metrics. See the
[legacy Plans reference](https://docs.metronome.com/api-reference/plans/list-plans).

### Coverage boundaries

The resource set reconciles the published Contracts and legacy Plans indexes
with the official OpenAPI read operations. Individual lookups for customers,
billable metrics, products, rate cards, invoices, packages, approval requests,
contracts, offset notifications, and contract named schedules repeat data
available through the included lists. Threshold-notification lists include
customer evaluation status and configuration. Filtered point-in-time lookup
variants are not separate resources.

Audit logs, invoice PDF downloads, and generated embeddable dashboard URLs are not
replicated.
Write operations, invoice simulations, webhook reception, and endpoints without
published request and response contracts are outside this source.

Lookups that need IDs or names the API cannot list are not replicated. These
cover event search by transaction ID, webhook delivery history, usage by a single
grouping key, customer and rate card named schedules, and point-in-time rate
lookups. The API offers no raw-event listing. For raw events and large accounts,
use Metronome's [data export](https://docs.metronome.com/guides/reporting-insights/data-export/overview)
to a warehouse or object store.

## Webhooks

With `ingestion` set to `webhooks` or `both`, the connection offers two
resources that hold the notifications Metronome pushes to a
[webhook destination](https://docs.metronome.com/guides/platform-configuration/webhooks/best-practices).
A `webhooks` connection needs no API token and offers only these resources.
With `both`, one pipeline can hold them and API resources together. Its schedule and
**Run** read the API resources, and **Start stream** reads the webhook
resources continuously. Webhooks also need the server settings described in
the [webhook source](https://filament.getgalaxy.io/pages/connectors/sources/webhook.md#setup).

Metronome creates the signing secret only after it has the delivery URL, and
the URL exists only once the connection does. After you create the connection,
Filament shows its delivery URL. In Metronome, open **Developer → Notifications
→ Webhooks**, choose **Add** and set that URL. Copy the secret Metronome shows
into **Signing key** and save it. To finish later, choose **Set up later**
and then **Add** in the connection's **Secrets** section. Filament does not
generate a secret for Metronome. One destination receives every notification
type, and Filament routes each one by its `type`. Each Metronome webhook has
its own secret and a connection verifies one, so point one webhook at each
connection. Sandbox and production need separate connections.

Metronome signs each request with HMAC-SHA256 over `X-Metronome-Date` and the
body. Filament rejects a request whose signature does not verify or whose date
is more than five minutes from the server's clock. The payload `id` names one
triggered notification and stays the same on every delivery attempt, so a
retried notification is stored once.

| Resource | Notification types | Shape |
| - | - | - |
| `system_notifications_webhook` | `contract.*`, `commit.*`, `credit.*` and `subscription.*` system and offset notifications, `invoice.void` | Fields at the top level |
| `notifications_webhook` | Every other type. Threshold alerts and their resolved notifications, `invoice.finalized`, `invoice.billing_provider_error`, `integration.issue`, marketplace and payment gating notifications | Fields under `properties` |

`system_notifications_webhook` columns are `id`, `type`, `timestamp`,
`environment_type`, `customer_id`, `contract_id`, `commit_id`, `credit_id`,
`subscription_id`, `invoice_id`, `invoice_type`, `segment_id`, `offset_id`,
`offset_duration`, `customer_custom_fields` and `contract_custom_fields`. An
offset notification carries its policy's type plus `offset_id` and
`offset_duration`. `notifications_webhook` columns are `id`, `type`, and
`customer_id`, `alert_id`, `invoice_id` and `timestamp` from `properties`, with
the whole `properties` object as JSON. Both end with `raw`, the fields the
manifest does not project.

A system or offset type Metronome adds later reaches `notifications_webhook`
with its fields in `raw`. Delivery is at least once, so upsert or merge on `id`
keeps one row per notification. Notifications are minimal. Join on their IDs to
the API resources for full records. Some types need Metronome to enable them,
such as `invoice.finalized`. A delivery whose body does not match its resource
is skipped and counted, as the [webhook source](https://filament.getgalaxy.io/pages/connectors/sources/webhook.md)
describes.

## Modes

All resources use full reads. Creation dates, usage windows, and effective dates
do not establish update-watermark semantics for mutable billing records.
Repeated full reads refresh edited invoices, balances, ledgers, and contracts.
Windowed reads cover only the configured interval.

Use full replace for keyless resources. These include rate rows, usage aggregates,
invoice breakdowns, seat-history segments, threshold and system notifications,
named schedules, plan assignments and adjustments, legacy ledger batches, and
legacy daily costs. Their upstream rows do not expose a suitable stable row ID.
Other resources support upsert by the declared ID or parent-scoped key.
Full upsert does not remove absent records. Full replace can reflect removals
only within the selected visibility, interval, and upstream retention.

## Behavior

* **Auth** uses bearer authentication against `https://api.metronome.com`.
* **Pagination** follows URL `next_page`, body `next_page`, or body `cursor` as
  specified by each endpoint. Null cursors end a read. General listings request
  50 rows, contracts request 20, commitment lists request 25, and seat history
  requests 10. Short pages do not end a read while a continuation cursor exists.
* **System notifications** use the documented single-request endpoint. Its
  schema contains a nullable cursor but documents no continuation parameter.
  A nonempty cursor fails the read instead of silently dropping more data.
  Such a response requires upstream clarification of the continuation contract.
* **Parents** are fetched for selected child resources even when the parent is
  not selected for output. Customer reads walk active and archived lists by
  default. Products, packages, contracts, commitments, billing configurations,
  and threshold notifications explicitly request archived data where supported.
  Other listings retain upstream visibility defaults.
* **Recovery** restarts child reads and configured lookup loops. Ordinary
  top-level cursor reads can resume saved pagination state. These checkpoints
  are not update-based incremental replication.
* **Rate limits** use the shared HTTP retry handling for 429 responses and server
  errors, honoring `Retry-After` when supplied. Metronome reports whether a
  throttle applies to the client or customer through
  `X-Metronome-Rate-Limit-Type`. See [API status codes](https://docs.metronome.com/api-reference/status-codes).
* **Errors** remain visible. Missing permissions and unavailable account features
  are not converted into empty data.
* **Consistency** follows the upstream reads. Requests across customers and API
  families do not form an atomic billing snapshot. Archived status can change
  while active and archived customer passes are running.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.