Export your costs in FOCUS format

Brimble can return your costs as FOCUS 1.2 records: one record per resource, per meter, per day. FOCUS is the open format that cost tools read, so you can see Brimble next to your other providers.

What you get

Usage records for each project, database, sandbox and bucket: CPU, memory, volume storage, object storage, backup storage and connection pooling, one record per day.
Bandwidth as one record per day for the whole account.
Plan fees and add-ons, tax, discounts and account credit, one record each.

Records for an invoice that has been finalized add up to that invoice exactly. The billing cycle you are still in has not been invoiced, so its records are estimates: each carries x_Estimated: "true", and the response has complete: false. Ask for the same dates again after the invoice is issued to get the final records.

Create an API key

The export needs an API key with the billing.read scope. This scope is not part of the read-only preset, so select it explicitly.

Open API keys in the dashboard. Use your team’s settings for a team key.
Create a key and select billing.read.
Copy the key. It is shown once.

A personal key reads your own account. A team key reads that team.

Request a window

Send the start and end of the period you want. The end is exclusive, and a window can cover at most 366 days.

curl "https://core.brimble.io/v1/billing/focus?charge_period_start=2026-10-01T00:00:00Z&charge_period_end=2026-11-01T00:00:00Z" \
  -H "x-brimble-key: $BRIMBLE_API_KEY"

{
  "message": "Billing data fetched successfully",
  "data": {
    "focus_version": "1.2",
    "charge_period_start": "2026-10-01T00:00:00+00:00",
    "charge_period_end": "2026-11-01T00:00:00+00:00",
    "complete": true,
    "rows": [
      {
        "BillingAccountId": "cus_123",
        "BillingCurrency": "USD",
        "BillingPeriodStart": "2026-09-27T22:12:00+00:00",
        "BillingPeriodEnd": "2026-10-27T22:12:00+00:00",
        "ChargePeriodStart": "2026-10-06T00:00:00+00:00",
        "ChargePeriodEnd": "2026-10-07T00:00:00+00:00",
        "ChargeCategory": "Usage",
        "ChargeDescription": "CPU · api",
        "Provider": "brimble",
        "ServiceName": "Compute",
        "ServiceCategory": "Compute",
        "ResourceId": "6a4a4fce5fed1a67d9108e73",
        "ResourceName": "api",
        "ResourceType": "Project",
        "RegionId": "eu-central",
        "BilledCost": "0.033462",
        "EffectiveCost": "0.033462",
        "ListCost": "0.033300",
        "ConsumedQuantity": "0.0333",
        "ConsumedUnit": "vCPU-months",
        "InvoiceId": "in_123",
        "Tags": { "project": "api", "service_type": "web" }
      }
    ]
  }
}

Costs and quantities are strings, so no precision is lost. To export a single invoice instead of a window, send invoice_id:

curl "https://core.brimble.io/v1/billing/focus?invoice_id=in_123" \
  -H "x-brimble-key: $BRIMBLE_API_KEY"

How records are dated

A record belongs to the window that contains its ChargePeriodStart. Consecutive windows never repeat a record and never drop one, so you can export day by day or month by month and get the same result.

A usage record covers one day of one resource.
A plan fee is dated at the start of the period it pays for.
Tax, discounts and account credit are dated when the invoice was issued.

What the costs mean

Field	Meaning
`BilledCost`	What you were charged, after anything your plan includes.
`EffectiveCost`	The same as `BilledCost`. Brimble has no commitments to amortize.
`ListCost`	The usage at the current rate, before anything your plan includes.

Usage on a finalized invoice is shared across your resources in proportion to what each one used, so the records for an invoice line always add up to that line.

Tag	On	Value
`project`	Project and database records	The project’s name.
`service_type`	Project and database records	The kind of project, such as `web` or `database`.
`environment`	Project and database records	The environment the project belongs to.
`tag:<name>`	Project and database records	`"true"` for each tag assigned to the project. A project tagged `payments` has `tag:payments`.
`sandbox`	Sandbox records	The sandbox’s name.
`bucket`	Bucket records	The bucket’s name.
`team`	Team accounts	The team’s name.

Send the records to CostGraph

CostGraph accepts FOCUS records over its push API. Create a FOCUS push connection in CostGraph, copy its connection id, and create a CostGraph API key with the focus:write scope. Then forward a window:

curl -s "https://core.brimble.io/v1/billing/focus?charge_period_start=2026-10-01T00:00:00Z&charge_period_end=2026-11-01T00:00:00Z" \
  -H "x-brimble-key: $BRIMBLE_API_KEY" \
  | jq --arg id "$COSTGRAPH_CONNECTION_ID" '.data | del(.complete) + {connection_id: $id, overwrite: true}' \
  | curl -X POST https://api.costgraph.ai/api/v1/tenant/billing/focus \
      -H "X-API-Key: $COSTGRAPH_API_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @-

overwrite: true replaces whatever CostGraph already holds for that window, so sending a window again is safe. A good routine is to send yesterday once a day, and send the whole month again after its invoice is issued so estimates are replaced with final records.

Limits

Bandwidth is measured for the account, not per project.
Before an invoice is issued, backup storage records show a list cost but a billed cost of zero. They get their final amounts once the invoice is finalized.
Records are in USD.

See the API reference for every parameter.

Getting started

Brimble Agent

Brimble MCP

CLI

Projects

Databases

Config as code

Sandboxes

Volumes

Object storage

Domains

Environments

Networking

Scaling

Observability

Analytics

Workspaces and teams

Security

Billing

Notifications

Webhooks

Log Drains

Troubleshooting

Reference

Export your costs in FOCUS format

What you get

Create an API key

Request a window

How records are dated

What the costs mean

Tags

Send the records to CostGraph

Limits

​What you get

​Create an API key

​Request a window

​How records are dated

​What the costs mean

​Tags

​Send the records to CostGraph

​Limits

What you get

Create an API key

Request a window

How records are dated

What the costs mean

Tags

Send the records to CostGraph

Limits