Build a billing integration
Implement the SuperPenguin FOCUS AI Provider Profile for usage and billed-cost exports.
This guide is for inference, speech, gateway, and agent providers that want SuperPenguin (and other FinOps clients) to pull customer usage and billed costs from a stable API.
Status: Draft v0.1. Semantic baseline: FOCUS 1.4. Implementing this profile does not by itself imply full FOCUS Cost and Usage dataset conformance.
Design goals
- Easy to implement: three REST endpoints, ordinary JSON, fixed UTC windows.
- Extensible: FOCUS fields plus
x_AI dimensions and meters. - Secure: read-only account binding, narrow scopes, revocation, OAuth upgrade path.
Implementation path
Understand datasets, grains, retention, dimensions, and auth methods. Start with this page and Authentication.
Preferred for interactive customer connections. Optionally support scoped bearer tokens for initial or machine-to-machine setups.
GET /v1/finops/capabilities must describe actual behavior.
See Usage data and Cost data.
Use the black-box runner in Conformance testing.
Provide SuperPenguin a sandbox credential and base URL for validation.
Endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /v1/finops/capabilities | Declare datasets, grains, retention, dimensions, auth |
GET | /v1/finops/usage | Export meter-per-row usage over a UTC window |
GET | /v1/finops/costs | Export provider-reported billed costs |
All export queries use half-open UTC windows: start inclusive, end exclusive. Supported granularities in v0.1 are 1h and 1d.
Normative assets (existing public URLs)
These remain available on superpenguin.ai and must stay stable:
| Asset | URL |
|---|---|
| Normative profile | /specs/provider-billing/v0.1/profile.md |
| OpenAPI 3.1 | /specs/provider-billing/v0.1/openapi.yaml |
| Usage example | /specs/provider-billing/v0.1/examples/usage.json |
| Cost example | /specs/provider-billing/v0.1/examples/costs.json |
| Conformance runner | /specs/provider-billing/v0.1/conformance.mjs |
Generated endpoint docs: API Reference.