> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costory.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Billing Data
> Set up cloud billing data sources in Costory via Terraform or manual configuration. Supports AWS CUR 2.0, GCP BigQuery, Azure Cost Management, Oracle Cloud, Snowflake, Scaleway, Cloudflare, and SaaS providers.
Connect your cloud and SaaS billing data so Costory can ingest and normalize it into [Explorer](/features/cost-explorer). You get one schema across providers, with no pipelines to build or maintain.
Once a datasource is added, Costory ingests automatically and maps everything to [Standard Columns](/docs/standard-columns), so you can group and filter costs by service, account, region, resource, and tags across all providers in a single view. Once data is flowing, you can also ask the [Costory MCP](/features/mcp) questions like "what drove the AWS increase last week" directly from your assistant.
## Supported providers
Click a provider to jump to the setup steps.
CUR 2.0 exports via Terraform or manual setup. **\~5 min.**
BigQuery billing export with detailed usage costs. **\<5 min.**
Azure Cost Management exports with SAS access. **\~5 min.**
Native cost reports with an API signing key. **\~5 min.**
Import FOCUS tables from BigQuery. **\<5 min.**
Connect Confluent Cloud invoice data. **\<5 min.**
Sync Aiven billing via service account. **\<5 min.**
Admin API key for usage charges. **\<5 min.**
Claude Console Admin API or claude.ai Enterprise Analytics. **\<5 min.**
Admin API key for Platform organization costs. **\<5 min.**
Management API key for organization costs. **\<5 min.**
Workspace API key for usage by product. **\<5 min.**
Open Platform API key for unit deductions. **\<5 min.**
IAM Access Key for BytePlus account bill details (includes Seedance / ModelArk). **\<5 min.**
Commitments metadata from BigQuery exports. **\<5 min.**
Pull Datadog usage and billing estimates. **\<5 min.**
Organization API key and Organization ID for Elastic Cloud billing. **\<5 min.**
Snowflake integration (key-pair auth), then billing datasource. **\<5 min.**
ClickHouse Cloud API key for compute, storage, and transfer. **\<5 min.**
IAM secret key and Organization ID for Scaleway consumption. **\<5 min.**
API token and Account ID for Cloudflare PayGo usage. **\<5 min.**
**Coming soon:** MongoDB, Databricks, and more. [Contact us](mailto:contact@costory.io) if your provider is missing.
## Before you start
* A Costory account.
* Admin billing access to the providers you want to connect (AWS Billing console, GCP Billing Admin, Azure Cost Management, OCI tenancy admin for the reader-user policy). See [Your permissions](#your-permissions) below.
* Read-only access only. Costory never writes to your cloud accounts or modifies your infrastructure. See [Security](/docs/security).
* Connect as many AWS accounts, GCP projects, Azure subscriptions, Oracle Cloud tenancies, and SaaS providers as you need within one organization.
Every provider can be connected from the Costory UI; Terraform examples are provided for infrastructure-as-code workflows. If you use Terraform, generate a Costory API token under your org name (top-right) > **API Tokens**. Full reference: [Costory Terraform Provider](https://registry.terraform.io/providers/costory-io/costory/latest/docs).
Already export CUR 2.0 (AWS), BigQuery billing (GCP), or Cost Management data (Azure) for another tool? Reuse it. Grant Costory read access to the existing bucket, dataset, or container instead of creating a second export.
**Time to first data:** SaaS providers (Cursor, Anthropic, OpenAI, OpenRouter, ElevenLabs, Kling AI, BytePlus, Datadog, Elastic Cloud, Snowflake, Scaleway, Cloudflare, etc.) sync in about **10 minutes**. AWS takes up to **12 hours** for the first CUR export. Costory notifies you by email when data arrives. See [Data Refresh](/docs/data-refresh) for ongoing cadence details.
### Your permissions
To perform the setup, **you** need the following permissions on your cloud account (separate from the read-only access Costory uses afterwards):
| Provider | Permissions you need |
| - | - |
| **AWS** | `iam:CreateRole`, `s3:CreateBucket`, Billing console access (to create CUR exports) |
| **GCP** | BigQuery Admin on the billing dataset, Billing Admin |
| **Azure** | Cost Management Contributor, Storage Account Contributor |
| **Oracle Cloud** | Permission to create a dedicated IAM user and attach the cost-report endorse policy on the root compartment |
***
## Historical data backfill
Each provider has different backfill capabilities. Costory ingests whatever history is available in the export:
| Provider | Backfill depth | How |
| - | - | - |
| **AWS** | Up to **12 months** | Automatic via `aws:createdBy` tag backfill. For longer periods, open an AWS Support request. |
| **GCP** | **Current + previous month** | GCP only backfills 2 months by default. |
| **Azure** | Up to **13 months** | Use **Export selected dates** in the portal (1-month chunks) or the Terraform `run_backfill` variable. |
| **SaaS providers** | Up to **12 months** | Automatic on first sync (depends on provider data retention). |
| **BytePlus Platform** | Up to **24 months** (earliest 2022-01) | Automatic on first sync. Optional start date caps lookback. |
| **Oracle Cloud** | Whatever Oracle already stored under `reports/cost-csv` | Costory copies existing native cost reports. No start-date cap on first sync. |
| **Elastic Cloud** | **\~6 months** on first sync | [Product-line costs](/setup/billing/elastic-cloud#data-in-costory) per project from the [Elastic Cloud Billing API](/setup/billing/elastic-cloud); incremental sync afterward. |
***
## What happens after setup
Costory normalizes your billing into [Standard Columns](/docs/standard-columns) and prepares [Dimensions](/features/tagging/dimensions) to detect, merge, and clean up your cost allocation tags across providers. Costs are ready in [Explorer](/features/cost-explorer) within minutes (up to 12 hours for the first AWS export).
From there, follow the [Quickstart guide](https://docs.costory.io/get-started/quickstart) to build your first dashboard and set up alerts.
## Next steps
Overlay usage data on your costs for unit economics and root-cause analysis.
Link deploys, incidents, and other engineering events for full context.
## FAQ
Costory requires **read-only** access. Here is the minimal permission set per provider:
| Provider | Permissions |
| - | - |
| **AWS** | `s3:ListBucket`, `s3:GetObject` on the CUR export bucket (via federated IAM role) |
| **GCP** | `roles/bigquery.dataViewer`, `roles/bigquery.metadataViewer` on the billing dataset |
| **Azure** | `Read` + `List` on the storage container (via SAS token) |
| **Oracle Cloud** | API signing key on a reader user with read on Oracle cost reports in the `bling` bucket (`reports/cost-csv`) |
| **Datadog** | `usage_read`, `billing_read`, `ci_visibility_read` (optional), `timeseries_query` (optional) |
| **Elastic Cloud** | Elastic Cloud Organization API key with access to the Billing API (see [Elastic Cloud setup](/setup/billing/elastic-cloud)) |
| **Confluent** | Billing read access on the API key |
| **Aiven** | `organization:billing:read` on the application user |
| **Cursor** | Admin API key (organization-scoped, not billing-specific) |
| **Anthropic Claude Code** | Admin API key (`sk-ant-admin01-…`) with usage and cost access |
| **Anthropic Claude AI** | Analytics API key (`sk-ant-api01-…`, scope `read:analytics`). Primary owner on claude.ai |
| **OpenAI** | Read-only Admin API key (`sk-admin-...`) with **Usage** (`api.usage.read`). **API keys + Projects** (`api.management.read`) recommended so names appear instead of raw ids |
| **OpenRouter** | Management API key (not a chat / inference key `sk-or-v1-...`) |
| **ElevenLabs** | Workspace API key (`sk_...`) with **Workspace analytics, full read** (`workspace_analytics_full_read`) |
| **Kling AI** | Open Platform API key (`Authorization: Bearer`). Unit Deduction Detail access. Not AccessKey + SecretKey |
| **BytePlus Platform** | IAM Access Key ID + Secret with **BillingCenterReadOnlyAccess**. Not a ModelArk / Seedance API key |
| **Scaleway** | IAM **BillingReadOnly** at Organization scope (secret key + Organization ID) |
| **Cloudflare** | API token with **Account / Billing / Read**, plus Account ID (PayGo accounts only) |
Costory never writes to your cloud accounts. See [Security](/docs/security) for details.
* **AWS**: Yes. Connect a single CUR export from your **management (payer) account** to cover all member accounts in the organization.
* **GCP**: Yes. The billing export covers **all projects** under the billing account automatically.
* **Azure**: Exports can be scoped at the Management Group or Billing Account level, but this is often restricted by customer agreements. Per-subscription exports are the most common setup.
* **Oracle Cloud**: Yes. Native cost reports are tenancy-wide. Connect one datasource per tenancy.
Costory stores ingested billing data in **GCP EU** by default. If you need US residency, [contact us](mailto:contact@costory.io) to update your configuration. For full details on compliance and certifications, see [Security](/docs/security).
* **AWS**: No rotation needed. Costory uses a federated IAM role (web identity), so there are no long-lived credentials to manage.
* **GCP**: No rotation needed. Access is granted via a GCP service account.
* **Azure**: You can update the SAS token in-place from the Costory UI or via Terraform. The default Terraform config sets a 900-day expiry, so no action is needed for nearly 3 years.
* **SaaS providers** (Datadog, Confluent, Aiven, Cursor, Anthropic, OpenAI, OpenRouter, ElevenLabs, Kling AI, BytePlus, Elastic Cloud, Scaleway, Cloudflare): Rotate the key from **Integrations** when the provider supports it, or create a new datasource with the new API key and delete the old one. No data gap or re-ingestion occurs.
* **Oracle Cloud**: Rotate from **Integrations**. Costory generates a new key pair. Upload the new public key on the same reader user. Destination and tenancy stay the same.
Yes, you can delete a datasource from the Costory UI or via `terraform destroy`. **All ingested data for that datasource is permanently deleted.** If you need to restore it, [contact us](mailto:contact@costory.io).
Delete the datasource in Costory first, then clean up the cloud-side resources:
* **AWS**: Delete the S3 bucket, IAM role, and CUR export, or revert the CloudFormation stack if you used that path.
* **GCP**: Revoke the BigQuery dataset access granted to the Costory service account.
* **Azure**: Delete the storage account, Cost Management exports, and resource group.
* **Oracle Cloud**: Delete the API key from the reader user, then remove the user, group, and endorse policy if you created them only for Costory.
If you used **Terraform**, `terraform destroy` handles all cloud-side and Costory-side cleanup automatically.
Yes. If you already have a billing export for another tool, you do not need a second one:
* **AWS**: Reuse your existing CUR 2.0 export (Parquet format). Skip the bucket/export creation and only create the federated IAM role so Costory can read the data.
* **GCP**: There is only one BigQuery billing export table per billing account, so Costory always uses the same table as any other tool.
* **Azure**: Reuse your existing Cost Management export (Parquet format). Skip the export creation and only generate a SAS token for Costory.
* **Oracle Cloud**: Oracle already writes native cost reports to the `bling` bucket. You only create a reader user and upload Costory's public API key.
No. Costory accesses your data over the **public internet** using the credentials you provide (IAM role, SAS token, or API key). No IP allowlisting, firewall rules, or private connectivity setup is needed on your side.
The cloud-side costs are **negligible**. You only pay for storage (and minor egress) on the export bucket or dataset:
* **AWS**: S3 storage for CUR exports. Use **overwrite mode** (enabled by default) to keep storage flat.
* **GCP**: BigQuery storage for the billing export table.
* **Azure**: Blob storage for the export container.
* **Oracle Cloud**: No extra export to create. Costory reads Oracle-managed cost reports in the `bling` bucket.
Most billing exports we see across customers are between **500 MB and 2 GB per month**.
Open [Integrations](https://app.costory.io/integration). Each billing datasource lists the period of billing data Costory has received, for example **from Mar. 1st 2026 to Jul. 24th 2026**.
* The **from** date is the earliest day Costory has for that source.
* The **to** date is the latest day Costory has for that source.
* If the **to** date is current (or matches the expected delay for that provider), ingestion is healthy.
Costory does not send proactive alerts for ingestion failures today (planned for a future release). For sync frequency and expected freshness per provider, see [Data Refresh Schedule](/docs/data-refresh).
The first CUR export can take up to **12 hours**. Costory sends you an email when data is received. If nothing arrives after 12 hours, contact AWS Support to force-trigger the export. This is rare but can happen.
A common pitfall is **forgetting to backfill historical data**: AWS only exports going forward. Use the `aws:createdBy` tag backfill (up to 12 months) or open an AWS Support request for longer periods.
Costory **validates the connection** when you add a datasource, both via the UI and Terraform. If credentials or permissions are misconfigured (e.g., wrong IAM role trust, invalid SAS token), you'll receive an immediate error message before any sync is attempted.
If your question isn't answered here, [contact us](mailto:billy@costory.io). We typically respond within a few hours.
***
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.