Metrics & integrations

Metrics in Balcony are the quantitative layer of mechanism health. They answer the question the component-level assessment alone cannot: not just "does a metrics component exist" but "are the metrics actually reading the values you need them to?"

Three ways to get data in

API ingestion

For systems that generate governance-relevant data programmatically — monitoring pipelines, risk scoring systems, audit event streams — the metrics ingest endpoint allows you to push data directly from your systems into Balcony. This is the lowest-friction path for continuous data: once set up, metric values arrive automatically on whatever cadence your pipeline runs.

See API reference for the full endpoint specification, authentication, and request format.

Manual entry

For metrics that do not have a programmatic source — periodic assessments, qualitative scores, compliance review outcomes — values can be entered directly within the mechanism editor. Navigate to the metrics section of a mechanism and add a value point manually.

Manual entry is appropriate when the governance process itself is manual (a quarterly review, a sign-off checklist) and when the relevant data does not exist in a system that can be queried programmatically.

CSV upload

For bulk historical data, or for metrics sourced from external tools that export but do not support real-time integration, Balcony supports CSV upload to a metric. This is useful for seeding a new metric with historical values, or for one-time imports from spreadsheet-based tracking tools.

[Screenshot needed] TODO: confirm exact CSV upload UI — verify field name and location in the mechanism metrics section

How metrics feed the rest of the platform

Metric data in Balcony flows into two places:

Mechanism health. When a metric has a defined target value, it contributes to the Metrics component health state. A metric that is consistently below its target, or that has not received any data recently, will show as Partial rather than Functioning. This makes metric health part of the overall mechanism diagnostic.

Dashboards. Any metric defined on a mechanism or chain can be displayed in a dashboard widget. Dashboards pull live values from the same metric store that powers health indicators — so a dashboard widget and a health badge are always reading the same underlying data.

API keys

API ingestion uses workspace-scoped API keys for authentication. Keys are managed in your workspace settings. Each key is associated with a specific workspace; metric points submitted via a key can only be written to metrics within that workspace.

Keys should be treated as credentials — store them securely and rotate them if they are exposed. A key's last-used timestamp is updated on each successful request, which helps you identify keys that are no longer in use.