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

# Export your costs in FOCUS format

> Read what each project, database, sandbox and bucket cost per day as FOCUS 1.2 records, for cost tools such as CostGraph.

Brimble can return your costs as [FOCUS 1.2](https://focus.finops.org) 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.

1. Open [API keys](https://paper.brimble.io/security/api-keys.md) in the dashboard. Use your team's settings for a team key.
2. Create a key and select **billing.read**.
3. 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.

```bash theme={null}
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"
```

```json theme={null}
{
  "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`:

```bash theme={null}
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.

## Tags

Each usage record carries tags you can group by.

| 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](https://paper.brimble.io/environments/overview.md) 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. |

Sandbox records also carry any [labels](https://paper.brimble.io/sandboxes/pricing.md#labels) the sandbox was created with, under the keys you chose.

## Send the records to CostGraph

CostGraph accepts FOCUS records over its [push API](https://docs.costgraph.ai/costgraph/integrations/focus-push). 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:

```bash theme={null}
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](https://paper.brimble.io/api-reference/billing/export-costs-as-focus-rows.md) for every parameter.


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