Atlas Cost Explorer and Billing Data API
Parent: Atlas Billing Mechanics and Cost Visibility · Published reference · snapshot 2026-10-19 · skill mongodb-operations-expert/references/atlas-billing-mechanics-and-cost-visibility.md · viability 4.65 / 5 (research)
↓ Facts as markdownall context files
Atlas Cost Explorer is a visual interface in the Billing section of the Atlas UI for viewing and analyzing monthly Atlas usage, visible to the Organization Owner, Billing Admin and Organization Billing Viewer roles. The same billing data is exposed programmatically through the Atlas Administration API as an asynchronous Cost Explorer query (create a query, then poll with a token) and, in the FOCUS 1.3 format, through the FOCUS Data API (list invoices, request a report, retrieve a report); third-party FinOps tools such as OpenCost and DoiT Cloud Intelligence consume it with read-only billing credentials. This pack draws on 8 source pages across 4 host labels and covers definitions, structure, mechanism, parameters (including the FOCUS column reference), how-to, examples, measures, problems, comparisons and history.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
Definitions
- Cost Explorer is in the Billing section of the Atlas UI and is visible only to users with the Organization Owner, Billing Admin or Organization Billing Viewer role. [source]
- FOCUS provides a common vocabulary and billing structure, which helps you understand, reconcile, and integrate your Atlas billing data with FinOps and cross-vendor cost-management tools. [source]
- Cost Explorer is a new visual interface available in the Billing section of the Atlas UI that is meant to help you view and analyze your monthly MongoDB Atlas usage in one convenient location. [source]
- Creates a query process within the Cost Explorer for the given parameters. [source]
- The FinOps Open Cost and Usage Specification (FOCUS) establishes uniform requirements for technology billing datasets. MongoDB Atlas provides billing cost and usage data in the FOCUS 1.3 format. You can generate a FOCUS report from the Invoices page in the Atlas console or with the FOCUS Data API. [source]
- The FOCUS Data API provides programmatic access to your FOCUS-formatted cost and usage data. [source]
Structure and components
- Cost Explorer groups and filters usage by organization, project, cluster and service, showing a stacked-column Usage chart and a Usage By Month table. The organization filter requires cross-organization billing. [source]
- Base URL: /api/atlas/v2/orgs/{orgId}/associatedInvoices [source]
- Request a FOCUS Report requests generation of a FOCUS-formatted billing report. [source]
- Retrieve a FOCUS Report returns the status of that report and, when the report is ready, the URL to download it. [source]
- Every line item maps to standard Cloud Analytics dimensions for organization, project, cluster, region, service and SKU, and every Atlas resource tag comes through as a mongodb/ label. [source]
- Plus MongoDB Atlas labels Atlas resource tags as mongodb/<tag key> (for example mongodb/environment) [source]
- Organization, project, cluster, region, service, SKU and unit map to standard Cloud Analytics dimensions, so Atlas sits in the same reports as your other providers. Every Atlas resource tag is pulled in automatically as a mongodb/ label for reports and allocations. [source]
How it works
- Third-party tools consume Atlas billing data with read-only billing credentials. DoiT uses a service account with Organization Billing Viewer, Read Only and Member roles, imports six months on connect and then updates hourly. The OpenCost plugin uses an org API key pair and says MongoDB detailed costs are only retrievable for the current month. [source]
- The Atlas FOCUS Data API (FOCUS 1.3, CSV only) works as list invoices (GET /orgs/{orgId}/associatedInvoices), request report (POST /orgs/{orgId}/invoices/{invoiceId}/reports), then retrieve (GET .../reports/{reportId}). States run PENDING, RUNNING, SUCCEEDED or FAILED. Poll no more than every 5 seconds. The download URL lasts 15 minutes and the report 7 days. Each request covers one invoice for one organization. [source]
- The 'Return All Pending Invoices for One Organization' endpoint returns line items whose results.lineItems.tags field reflects applied resource tags, so FinOps tools can break spend down by environment or team. Atlas's published Go SDK examples also list historical invoices (with linked invoices) and export to CSV or JSON. [source]
- The Cost Explorer API is asynchronous: POST /api/atlas/v2/orgs/{orgId}/billing/costExplorer/usage (createOrgBillingCostExplorerUsageProcess) returns a 64-character token; GET .../costExplorer/usage/{token} (getOrgBillingCostExplorerUsage) returns results, or a 'processing' response telling the caller to retry later. [source]
- Requests generation of a billing report in the FOCUS standard format. Atlas generates the report asynchronously and returns a report ID that you use to poll for the report status. [source]
- Returns the status and details of a FOCUS report that you requested. Poll this endpoint until state is SUCCEEDED or FAILED. [source]
- Cost Explorer allows you to easily filter your Atlas usage data by what’s most important to you and your business, with filters to segment your view by organization (if you have cross-org billing enabled), projects, clusters, or services, within a time window of up to 18 months. [source]
- With Cost Explorer, you can now quickly pinpoint trends or outliers in your month-over-month usage to identify opportunities to potentially improve or optimize your Atlas usage going forward. If you’re looking for additional customization beyond what is available in Cost Explorer, you can also create your own billing dashboards in Atlas Charts that are fully tailored to your needs. [source]
- Cost Explorer is viewable for any Atlas user assigned the Organization Owner, Billing Admin, or Organization Billing Viewer roles. To learn more about Cost Explore and how to manage your Atlas billing, view our documentation on managing billing. [source]
- View costs in billing currency: Access BilledCost and EffectiveCost directly in billing currency, without manual conversion. [source]
- Cloud Intelligence™ imports your MongoDB Atlas cost and usage by organization, project, cluster, region and SKU, with your Atlas resource tags as labels. Right next to the rest of your cloud spend. [source]
Parameters and configuration
- FOCUS 1.3 column BilledCost: The cost, in billing currency, charged during the current invoicing period. [source] — FOCUS column
- FOCUS 1.3 column BillingAccountId: The Atlas organization ID for this invoice. (CSV equivalent field: Organization ID) [source] — FOCUS column
- FOCUS 1.3 column BillingAccountName: The Atlas organization name for this invoice. (CSV equivalent field: Organization Name) [source] — FOCUS column
- FOCUS 1.3 column BillingCurrency: The billing currency for this charge. [source] — FOCUS column
- FOCUS 1.3 column BillingPeriodEnd: The end date of the invoicing period. Billing period is exclusive of end date. (JSON equivalent field: "endDate" (invoice)) [source] — FOCUS column
- FOCUS 1.3 column BillingPeriodStart: The start date of the invoicing period. Billing period is inclusive of start date. (JSON equivalent field: "created" (invoice)) [source] — FOCUS column
- FOCUS 1.3 column ChargeCategory: Classification of a charge based on the nature of how it is billed. For example, "usage" denotes a charge based on the quantity of the service or resource consumed. [source] — FOCUS column
- FOCUS 1.3 column ChargeDescription: High-level context about the charge. (CSV equivalent field: Description) [source] — FOCUS column
- FOCUS 1.3 column ChargePeriodEnd: The end of the period when the charge was incurred. Billing period is exclusive of end date. (JSON equivalent field: "endDate" (lineItems)) [source] — FOCUS column
- FOCUS 1.3 column ChargePeriodStart: The start of the period when the charge was incurred. Billing period is inclusive of start date. (CSV equivalent field: Usage Date; JSON equivalent field: "startDate" (lineItems)) [source] — FOCUS column
- FOCUS 1.3 column ConsumedQuantity: The volume of a given SKU associated with a resource or service used, based on the consumed unit. (CSV equivalent field: Quantity; JSON equivalent field: "quantity") [source] — FOCUS column
- FOCUS 1.3 column ConsumedUnit: The unit used to meter a given SKU. (CSV equivalent field: Unit; JSON equivalent field: "unit") [source] — FOCUS column
- FOCUS 1.3 column ContractApplied: A set of properties that associate a charge with one or more contract commitments. Identifies the name of the Atlas Credit used to cover the consumed usage. [source] — FOCUS column
- FOCUS 1.3 column ContractedCost: Represents the cost calculated by multiplying contracted unit price and the corresponding pricing quantity. This field is denominated in billing currency. [source] — FOCUS column
- FOCUS 1.3 column ContractedUnitPrice: The agreed-upon unit price for a single pricing unit of the associated SKU, inclusive of discounts. This price is denominated in billing currency. [source] — FOCUS column
- FOCUS 1.3 column EffectiveCost: Represents the amortized cost of a charge after applying all reduced rates and discounts. This field is denominated in billing currency. [source] — FOCUS column
- FOCUS 1.3 column HostProviderName: The name of the entity that provides the underlying infrastructure where the service provider deploys its resources and services. For example, AWS, Azure, GCP. [source] — FOCUS column
- FOCUS 1.3 column InvoiceIssuer: The entity responsible for invoicing for the resources or services consumed. For example, MongoDB for customers who transact directly with MongoDB, or marketplace for customers that transact with Atlas through a marketplace. [source] — FOCUS column
- FOCUS 1.3 column ListCost: Represents the cost calculated by multiplying the list unit price and the corresponding pricing quantity. This field is denominated in billing currency. [source] — FOCUS column
- FOCUS 1.3 column ListUnitPrice: The suggested provider-published unit price for a single pricing unit of the associated SKU, exclusive of any discounts. This price is denominated in billing currency. [source] — FOCUS column
- FOCUS 1.3 column PricingCurrency: The metering currency for this charge, for example, Atlas Credits. [source] — FOCUS column
- FOCUS 1.3 column PricingCurrencyContractedUnitPrice: The agreed-upon unit price for a single pricing unit of the associated SKU, inclusive of discounts. This price is denominated in the pricing currency. [source] — FOCUS column
- FOCUS 1.3 column PricingCurrencyEffectiveCost: Represents the amortized cost of a charge after applying all reduced rates and discounts. This field is denominated in pricing currency. (CSV equivalent field: Amount; JSON equivalent field: "totalPriceCents") [source] — FOCUS column
- FOCUS 1.3 column PricingCurrencyListUnitPrice: Represents the cost calculated by multiplying the list unit price and the corresponding pricing quantity. This field is denominated in pricing currency. (CSV equivalent field: Unit Price; JSON equivalent field: "unitPriceDollars") [source] — FOCUS column
- FOCUS 1.3 column PricingQuantity: Represents the volume of a given SKU associated with a resource or service used or purchased, based on pricing unit. [source] — FOCUS column
- FOCUS 1.3 column PricingUnit: Represents a unit for determining unit prices, for example, GB-Hours. [source] — FOCUS column
- FOCUS 1.3 column RegionId: An identifier for an isolated geographic area where a resource is provisioned or a service is provided. For example, us-east-1. [source] — FOCUS column
- FOCUS 1.3 column RegionName: A name for an isolated geographic area where a resource is provisioned or a service is provided. For example, N. Virginia. (CSV equivalent field: Region) [source] — FOCUS column
- FOCUS 1.3 column ResourceName: For Atlas, this is the cluster name. (CSV equivalent field: Cluster; JSON equivalent field: "clusterName") [source] — FOCUS column
- FOCUS 1.3 column ServiceCategory: Highest-level classification as defined by FOCUS. This is "Databases" for MongoDB Atlas. [source] — FOCUS column
- FOCUS 1.3 column ServiceName: Represents an offering that can be purchased from a service provider, for example, MongoDB Atlas. [source] — FOCUS column
- FOCUS 1.3 column ServiceProviderName: Name of the entity that provides the resources or services available for usage or purchase. For example, MongoDB. [source] — FOCUS column
- FOCUS 1.3 column SkuId: A unique identifier for a Stock Keeping Unit (SKU), representing a distinct billable configuration. [source] — FOCUS column
- FOCUS 1.3 column SkuMeter: The unit of measurement for the associated SKU, indicating what is being measured, for example, GB, compute time, or requests. [source] — FOCUS column
- FOCUS 1.3 column SkuPriceDetails: The price dimensions of the price point that the charge was billed at, as key-value pairs in JSON. This column is empty when the charge has no price point or the price point specifies no dimensions. [source] — FOCUS column
- FOCUS 1.3 column SkuPriceId: A unique identifier for the price point that the charge was billed at. [source] — FOCUS column
- FOCUS 1.3 column SubAccountId: An identifier assigned to a sub account, which is a grouping based on organizational constructs. This equates to a Project in MongoDB Atlas. (CSV equivalent field: Project ID; JSON equivalent field: "groupId") [source] — FOCUS column
- FOCUS 1.3 column SubAccountName: The display name of sub account. This equates to a Project in MongoDB Atlas. (CSV equivalent field: Project; JSON equivalent field: "groupName") [source] — FOCUS column
- FOCUS 1.3 column Tags: Tags assigned to the associated resources. (CSV equivalent field: Tags/application; JSON equivalent field: "tags") [source] — FOCUS column
- FOCUS 1.3 column x_AtlasSku: The Atlas SKU that is being billed. (CSV equivalent field: SKU; JSON equivalent field: "sku") [source] — FOCUS column
- FOCUS 1.3 column x_BilledDateEnd: The end of the period when MongoDB billed the charge. (CSV equivalent field: Date; JSON equivalent field: "created" (lineItems)) [source] — FOCUS column
- FOCUS 1.3 column x_BilledDateStart: The start of the period when MongoDB billed the charge. [source] — FOCUS column
- FOCUS 1.3 column x_PricingCurrencyRate: The "price" of an Atlas Credit. Apply this rate to find the cost of an Atlas Credit in billing currency. [source] — FOCUS column
- FOCUS 1.3 column x_SkuCategory: Highest-level classification for the associated Atlas SKU. For example, Clusters, or Backup. [source] — FOCUS column
- The Cost Explorer query body requires startDate (inclusive) and endDate (exclusive), both of which must be the start of a month. Optional fields: organizations, projects, clusters (24-hex IDs), services (enum such as Clusters, Storage, Backup, Data Transfer, Support, Credits, AI Model APIs), groupBy (organizations|projects|clusters|services) and includePartialMatches (default false). A groupBy dimension needs at least one filter value for it. [source]
- Organization Billing Viewer, Organization Read Only and Organization Member. Creating it requires the Organization Owner permission in MongoDB, and we recommend a 365-day secret, which you can refresh later in the wizard. [source]
- PLUGIN_EXECUTABLE_DIR Should have the full path to the bin dir you set up [source]
- PLUGIN_CONFIG_DIR Should have the full path to the config dir [source]
How-to and procedures
- Service accounts (client ID/secret) are the authentication method shown in MongoDB's Go SDK billing examples; API key pairs also work (OpenCost). Cross-org billing: linked invoices are visible only to Organization Billing Admin or Owner of the paying organization. [source]
- The Atlas CLI exposes the Cost Explorer API as `atlas api invoices createCostExplorerProcess --orgId <id> --file request.json` (autogenerated 1:1 from the Admin API; version 2023-01-01). [source]
- All our requests to the Atlas API come from a fixed set of outbound IP addresses. Adding each one to the service account's API access list lets the connection through. [source]
- To view and download billing data, you must have the Organization Billing Admin, Organization Owner, or Organization Billing Viewer role. [source]
- You can download the FOCUS cost and usage report for an invoice from the Invoices page in the Atlas console. Select CSV FOCUS Cost & Usage Report when you choose the invoice format. [source]
- Open the MongoDB card in the integrations catalog and follow the wizard: create a service account in your Atlas organization, paste its client ID and secret, add our outbound IP addresses to its API access list, and test the connection. Repeat for each Atlas organization. [source]
- Visit https://github.com/opencost/opencost-plugins/releases and choose the most recent release [source]
- Create a sibling directory to OpenCost called plugins [source]
- In Atlas Access Manager, with billing viewer, read only and member permissions. [source]
Examples and snippets
Measurements and reference values
- The docs chart the past six months in Cost Explorer and allow access to billing data up to the past 18 months. The announcement blog describes 'up to 18 months' as the window. [source]
Problems, failure modes and limitations
- FOCUS reports cover usage-based costs only and exclude shortfall charges, tax line items and adjustments or refunds. Pending-month values are estimates, so re-pull after the month closes. BilledCost and EffectiveCost are already in billing currency; PricingCurrency* columns stay in Atlas Credits. [source]
- Tags in invoice CSVs and Admin API responses reflect the tag configuration at the moment of generation or the call. Changing tags mid-cycle makes the invoice show only the latest configuration, so retag history is not preserved in billing data. [source]
- Billing lag: usage at the end of a billing period can land on the next period's invoice (e.g. Oct 31 usage processed in November). Data transfer, private endpoint and backup costs can post days later because of cloud provider reporting lag. The invoice schema notes charges typically post the next day. [source]
- Atlas data transfer, private endpoint, and backup costs depend on your Cloud Service Provider. Due to reporting lag from Cloud Service Providers, usage of these services may be processed in the following days. [source]
- *** MongoDB detailed costs are currently only retrievable for the current month. Historical costs from prior months are queryable if previously obtained *** [source]
Comparisons and alternatives
- The PDF and CSV usage summaries present your invoice in MongoDB-specific formats. The FOCUS cost and usage report presents the same billing period in the standardized FOCUS format. You can download all three from the Invoices page in the Atlas console. [source]
- Work with standard industry terms: Use SubAccountName and other intuitive FOCUS terms instead of internal API terms such as groupName. [source]
Changes and history
- Historically, Atlas billing data has been provided in MongoDB-specific formats. Atlas customers, particularly large enterprises and partners, need to expend manual effort to convert Atlas Credit Units (ACUs) into billing currency. [source]
Related concepts
- FOCUS — is a part of Atlas Cost Explorer and Billing Data API
- service account — is a part of Atlas Cost Explorer and Billing Data API
- Cloud Intelligence import — is a instance of Atlas Cost Explorer and Billing Data API
- OpenCost — is a instance of Atlas Cost Explorer and Billing Data API
- FOCUS report lifecycle — is a part of Atlas Cost Explorer and Billing Data API
- asynchronous process — is a part of Atlas Cost Explorer and Billing Data API
- Atlas CLI — is a related of Atlas Cost Explorer and Billing Data API
- billing lag — is a problem of Atlas Cost Explorer and Billing Data API
- cross-organization billing — is a related of Atlas Cost Explorer and Billing Data API
- 18 months — is a measure of Atlas Cost Explorer and Billing Data API
- pending invoices endpoint — is a part of Atlas Cost Explorer and Billing Data API
- FinOps tool — is a instance of Atlas Cost Explorer and Billing Data API
- Admin API — is a related of Atlas Cost Explorer and Billing Data API
- query body — is a part of Atlas Cost Explorer and Billing Data API
- DoiT — is a instance of Atlas Cost Explorer and Billing Data API
- Atlas Charts billing dashboards — is a instance of Atlas Cost Explorer and Billing Data API
- tag snapshot — is a problem of Atlas Cost Explorer and Billing Data API
- shortfall charges — is a problem of Atlas Cost Explorer and Billing Data API
Children
- Atlas Charts billing dashboards (frontier)
Frontier under this node: Atlas Charts billing dashboards