Cloud Billing (FOCUS)

The cost estimates elsewhere in this section are list-price calculations. To work with your actual billed spend, connect a FOCUS billing export, the open FOCUS billing format that AWS, GCP, and Azure can all emit. Stategraph syncs the export on a schedule and stores it so the console's cost views can show real spend alongside the estimates.

Billing sources are admin-only and managed per tenant, either from the console's Billing Connections page or the CLI below.

Connect a Billing Source

  1. Create a FOCUS export in your cloud provider (see Provider Setup).
  2. Point a Stategraph billing source at the exported files:
stategraph cost billing-source add \
  --tenant <tenant-id> \
  --provider aws \
  --source-uri "s3://my-bucket/focus/data/**/*.parquet"

{
  "id": "aef4bd07-…",
  "provider": "aws",
  "source_uri": "s3://my-bucket/focus/data/**/*.parquet",
  "region": "us-east-1",
  "window_months": 2,
  "enabled": true,
  "created_at": "2026-06-09T12:01:17Z",
  "updated_at": "2026-06-09T12:01:17Z"
}

Once enabled, the source syncs on a schedule. Trigger one immediately with sync. Credentials resolve ambiently, from an instance role, workload identity, az login, or the standard provider environment variables, so you do not hand secrets to Stategraph.

Options for add:

Option Required Description
--provider Yes aws, gcp, or azure
--source-uri Yes Location of the exported files (Parquet or CSV; globs allowed)
--region No Bucket region (AWS). Omit to resolve ambiently
--window-months No Trailing months reloaded on each sync (default 2: current plus previous)
--disabled No Create the source without enabling scheduled sync

Provider Setup

Configure a FOCUS export in your cloud provider, then use its location as --source-uri. First files typically arrive within about 24 hours and refresh daily.

AWS

In Billing and Cost Management > Data Exports, create a FOCUS 1.0 standard export (Parquet) to an S3 bucket.

GCP

Enable detailed billing export to BigQuery, then export the FOCUS view to a GCS bucket (Parquet or CSV) and point the source at that bucket.

Azure

In Cost Management > Exports, create an export with the Cost and usage details (FOCUS) dataset (Parquet) to a storage account.

Manage Sources

# List billing sources in a tenant
stategraph cost billing-source list --tenant <tenant-id>

# Trigger a sync now (optionally backfill from a date)
stategraph cost billing-source sync --tenant <tenant-id> <source-id> [--from 2026-01-01]

# Change settings (omitted fields are unchanged)
stategraph cost billing-source update --tenant <tenant-id> <source-id> --window-months 3

# Pause or resume scheduled sync
stategraph cost billing-source disable --tenant <tenant-id> <source-id>
stategraph cost billing-source enable  --tenant <tenant-id> <source-id>

# Remove a source and its loaded billing rows
stategraph cost billing-source remove --tenant <tenant-id> <source-id>

list reports each source's last_status, last_synced_at, and last_row_count, so you can confirm syncs are landing. remove deletes the source and the billing rows it loaded; it prompts for confirmation, or pass --auto-approve to skip the prompt.

API

The CLI wraps admin endpoints under /api/v1/tenants/{tenant_id}/billing-sources. A non-admin caller receives 403.

Method Path Description
GET /api/v1/tenants/{tenant_id}/billing-sources List sources
POST /api/v1/tenants/{tenant_id}/billing-sources Create a source
PUT /api/v1/tenants/{tenant_id}/billing-sources/{id} Update a source
POST /api/v1/tenants/{tenant_id}/billing-sources/{id}/sync Trigger a sync
DELETE /api/v1/tenants/{tenant_id}/billing-sources/{id} Delete a source

Next Steps