# Connect Datadog

Costfluent reads your Datadog spend from Datadog's usage API, with an API key and an application
key you create for it. One connection is one Datadog parent organization, and the cost of every
child organization under it.

## How Costfluent connects

Costfluent stores both keys encrypted, and the site with them; the site, which is no secret, is
also shown with the connection. When you connect, it asks Datadog which
organization the keys belong to, which needs no permission, and reads the running month's cost
estimate, which needs the two cost permissions. The organization is the connection's identity, so
you do not enter it. After that the keys are used only to read that organization's cost.

The site is chosen from Datadog's own list, never typed, and Costfluent calls Datadog only at the
API address of that site.

:::caution
An application key acts for the user or service account that owns it. Scope it to `usage_read` and
`billing_read`, and create it for Costfluent alone, best on a service account, so you can revoke it
without touching anything else.
:::

## Prerequisites

1. The Owner or Integration owner organization role in Costfluent.
2. A Datadog parent organization on a Pro or Enterprise plan: Datadog answers cost only to the
   parent organization, and its usage API is available to those plans only. Keys of a child
   organization are refused.
3. An administrator of that organization, to create the two keys there:
   - an API key, under "Organization Settings" → "API Keys";
   - an application key for Costfluent alone, best one of a service account ("Organization
     Settings" → "Service Accounts"), with the scopes `usage_read` and `billing_read`.
4. The organization's site: the address you sign in at, without `app.`. Signing in at
   `app.datadoghq.eu` means the site `datadoghq.eu`. The sites are `datadoghq.com`,
   `us3.datadoghq.com`, `us5.datadoghq.com`, `datadoghq.eu`, `ap1.datadoghq.com`,
   `ap2.datadoghq.com`, `uk1.datadoghq.com`, `ddog-gov.com` and `us2.ddog-gov.com`.

## Connect

<Stepper>

1. Open **Settings**, then **Integrations**, select **Datadog**, and open the **Connect** tab.
2. Select **Add keys**, keep the suggested **Display name** or enter your own, paste the API key
   into **API key** and the application key into **Application key**, and choose the
   organization's site in **Datadog site**. It starts on `datadoghq.com`.
3. Select **Test connection** to see each check, or **Connect** to save.

</Stepper>

Costfluent reads the running month's cost before storing anything, so a connection that saves can
read your cost. A connection with the same organization as an existing one is refused. If Datadog
does not answer the cost read during that check, the connection is saved anyway and checked again
automatically.

:::note
Datadog cost your organization uploaded to a [custom provider](/connect/custom-provider) is
counted twice once the connection imports the same days, until you delete those uploads
([Update or disconnect](/connect/custom-provider#update-or-disconnect)).
:::

## Data and freshness

Connecting imports as far back as your plan's backfill reaches, and at most six months
([Manage connections](/connect/manage-connections#how-it-behaves)), as long as Datadog reports cost
that far back. Cost arrives in US dollars.

- **The current and the previous month** arrive by UTC day, as Datadog's estimates. Datadog states
  each day as the month's running total so far, and Costfluent records the day as the difference
  from the day before. Datadog's estimates arrive up to 72 hours late and change until Datadog
  closes the month, so a day can come out negative when Datadog lowers a running total; the month
  still adds up to Datadog's figure.
- **The previous month's final cost**, which Datadog publishes by the 16th of the following month,
  is read once Datadog states it for every organization. The daily estimates stay, and each charge
  whose final cost differs from its estimate gets one more line on the month's 1st that carries the
  difference, so the month adds up to Datadog's final figure. The line is a usage charge of the
  same month, described as the charge's true-up to Datadog's final figure.
- **Older months** arrive as one figure per month, dated the 1st, from Datadog's historical cost.

Every sync reads the running month again, and the previous month until the 20th, so a changed
estimate or final cost replaces the one before it.

## Reporting dimensions

- **Account** is the Datadog organization the cost was charged to: the parent, or a child
  organization under it, named as in Datadog.
- **Service** is the Datadog product, as Datadog names it, such as `infra_host`. **SKU** is the
  product too.
- The charge description is the product and its charge type, so a product's committed and on-demand
  charges stay two lines.
- **Pricing category** is `Committed` for Datadog's committed charges and `Standard` for the rest.
- **Service category** is Management and Governance, and **Service subcategory** is Observability,
  for every Datadog product.
- Datadog's cost carries no usage quantity, so there is no usage unit.
- The billing account is the connected parent organization, and the billing period is the calendar
  month.

## Update or disconnect

### After connecting

The **Manage** tab lists the connection by its display name, with its **Organization ID**: the
public ID of the Datadog organization the keys belong to. Open the gear icon beside it to see
whether the cost is still readable, which workspaces the connection feeds, and which months have
been imported. **Run checks** runs the checks again on request.

### Rotating or removing access

Select **Update credentials** on the connection page and paste a new API key and application key
of the same organization: **Datadog site** opens on the connection's own. Then revoke the old keys in
Datadog. A key pair of another organization is refused: connect that organization as a new
connection instead.

To retire the connection, remove it in Costfluent and revoke both keys in Datadog. Removing it
erases the cost it imported ([Remove a connection](/connect/manage-connections#remove-a-connection)).

## Troubleshooting

- **Datadog refused these keys on datadoghq.com.** The message names the site you chose. The two
  keys belong to different organizations, one of them was revoked, or the organization is on
  another site: check the address you sign in at.
- **Datadog refused the cost read for these keys (HTTP 403).** The application key lacks
  `usage_read` or `billing_read`, or the keys belong to a child organization. Create the
  application key with both scopes in the parent organization.
