> ## 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.

# Datadog Billing Setup

> Connect Datadog usage and billing estimates to Costory.

Costory connects to Datadog billing with a Datadog API key and application key. It uses Datadog usage endpoints and billing endpoints to convert Datadog product usage into cost rows in [Explorer](/features/cost-explorer).

If you also want to import operational metrics from Datadog, see [Datadog usage metrics](/setup/usage-metrics/datadog).

<Tabs>
  <Tab title="Terraform">
    Not supported.
  </Tab>

  <Tab title="Manual setup">
    Open Costory and go to **Integrations > Datadog**. The stepper guides you through each field.

    1. Generate a Datadog API key and application key with the following permissions:
       * `usage_read` (required): read Datadog product usage volumes.
       * `billing_read` (required): access the billing endpoints Costory uses for cost estimates.
       * `timeseries_query` (optional): query Datadog metrics when the same integration is used for usage metrics.
       * `ci_visibility_read` (optional): import Datadog CI visibility metrics.
    2. Enter the API key and application key in the Costory stepper. Costory tests the connection and starts syncing.
    3. If Datadog billing data does not appear after **24 hours**, see [Missing marketplace billing data](#missing-marketplace-billing-data).

    On first sync, Costory backfills up to **12 months** of historical usage data.
  </Tab>
</Tabs>

## Data Costory imports

Costory maps Datadog billing rows into [Standard Columns](/docs/standard-columns), so you can compare Datadog spend with AWS, GCP, Azure, and other billing datasources.

Costory includes:

* Usage-based billing estimates across Datadog products, including infrastructure, APM, logs, and similar usage lines.
* Per-product cost breakdowns. In **Explorer**, group by **Service name** to review each Datadog product.
* Historical usage data for trend analysis.

Costory does not include:

* Final Datadog invoices, taxes, credits, or support fees that Datadog does not expose through its billing and usage APIs.
* Contract-specific pricing terms that are not available through the Datadog APIs.
* Custom metrics pricing beyond what the Datadog usage API exposes.

## Why billing\_read matters

Datadog usage APIs tell Costory what you used. Datadog billing APIs provide the cost context required to create Datadog billing rows.

An API key can pass `usage_read` and `timeseries_query` checks while Datadog billing endpoints remain unavailable to Costory. When this happens, Costory can read usage or metric data, but it cannot map Datadog usage into costs.

## API reference

Costory calls these [Datadog Usage Metering API](https://docs.datadoghq.com/api/latest/usage-metering/) endpoints. The base URL depends on your Datadog site (for example `https://api.datadoghq.com` for US1). Costory sends your API key and application key on every request.

| Use case                                  | Endpoint                            | Required scope |
| ----------------------------------------- | ----------------------------------- | -------------- |
| Usage volumes by product family           | `GET /api/v2/usage/hourly_usage`    | `usage_read`   |
| Current and previous month cost estimates | `GET /api/v2/usage/estimated_cost`  | `billing_read` |
| Historical monthly costs                  | `GET /api/v2/usage/historical_cost` | `billing_read` |

`hourly_usage` returns usage measurements (for example host counts, log volume) that Costory uses to build usage context. `estimated_cost` covers the current and previous month, with data delayed by up to 72 hours. `historical_cost` covers earlier months and is typically available by the 16th of the following month.

<Note>
  Billing endpoints (`estimated_cost`, `historical_cost`) may return **403 Forbidden** even when `usage_read` works. This is common for accounts billed through AWS Marketplace or GCP Marketplace. See [Missing marketplace billing data](#missing-marketplace-billing-data).
</Note>

## Missing marketplace billing data

In rare cases, customers who subscribe to Datadog through AWS Marketplace or GCP Marketplace cannot access Datadog billing data through Costory's Datadog connector.

The connector can still access usage and timeseries data, but Datadog billing data does not appear in Costory after **24 hours**. This means Costory can see what was used, but cannot create Datadog billing rows because the `billing_read` scope is blocked or the billing endpoints are unavailable for the account.

This is account-specific and does not mean every <Tooltip tip="Third-party software bought through AWS, GCP, or Azure Marketplace. These often appear on your cloud bill but can still require vendor-specific billing APIs for product-level cost details." cta="See Glossary" href="/docs/glossary#marketplace-purchases">marketplace subscription</Tooltip> has the same limitation. Datadog support can usually confirm the exact reason quickly. If the issue is a Datadog-side bug, they may also provide a workaround that Costory can implement.

Use this checklist before contacting Datadog support:

1. Confirm the application key user has the `billing_read` scope in Datadog.
2. Confirm the API key and application key belong to the Datadog site you selected in Costory.
3. Ask Datadog support why `billing_read` is blocked for your account.

You can send Datadog support this message:

```text theme={null}
We granted usage_read, timeseries_query, and billing_read to the Datadog application key used by Costory.

Usage and timeseries data is available in Costory, but Datadog billing data is still missing after 24 hours.

Why is billing_read blocked for our account?

Could this be related to how our Datadog subscription is linked through AWS Marketplace or GCP Marketplace?

If this is a Datadog-side bug, is there a supported workaround that Costory can implement?
```

If Datadog confirms that Billing APIs are unavailable for the account, Costory cannot ingest Datadog billing from that key. You can still use [Datadog usage metrics](/setup/usage-metrics/datadog) as non-cost metrics, but they will not create Datadog cost rows.

## Related

<CardGroup cols={2}>
  <Card title="Billing Data overview" icon="database" href="/setup/billing">
    Review all billing datasources and shared setup concepts.
  </Card>

  <Card title="Datadog usage metrics" icon="chart-line" href="/setup/usage-metrics/datadog">
    Import Datadog timeseries metrics for allocation and analysis.
  </Card>

  <Card title="Explorer" icon="chart-simple" href="/features/cost-explorer">
    Explore Datadog costs with the rest of your billing data.
  </Card>

  <Card title="Standard Columns" icon="book" href="/docs/standard-columns">
    See how Datadog fields map into Costory's normalized schema.
  </Card>
</CardGroup>