> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Datadog

> Datadog is an observability and monitoring platform - Serval connects to your Datadog organization with an API key and Application key so workflows can query metrics, logs, monitors, dashboards, and more on demand.

## About Datadog

Datadog is an observability and monitoring platform covering metrics, logs, monitors, dashboards, APM, and security monitoring. Serval connects to a Datadog organization using a Datadog API key plus an Application key, both stored as secrets and attached to every request Serval makes on your behalf. You select your Datadog site (US1, US3, US5, EU, AP1, or GOV) by entering the matching API domain, and an Instance Name distinguishes multiple Datadog connections on the same team.

**Authentication:** Datadog API key + Application key (custom header authentication). Both keys are stored as secrets and injected on every request as the DD-API-KEY and DD-APPLICATION-KEY headers. There is no OAuth flow and no token refresh - the keys are used as-is until you rotate them by editing the connection.

**Data sync:** On-demand only. Serval calls the Datadog API when a workflow step runs - there is no background sync, and the integration ships no pre-installed workflows.

## What the Datadog integration enables

| Capability                                | Description                                                                                                                                                                                             |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Query metrics and timeseries              | List active metrics, read metric metadata, and run timeseries queries.                                                                                                                                  |
| Search and aggregate logs                 | Search log events and manage log configuration such as indexes and pipelines.                                                                                                                           |
| Manage monitors and SLOs                  | Create, read, update, search, mute, and unmute monitors; read and manage SLO definitions, corrections, and history.                                                                                     |
| Manage dashboards, hosts, and events      | List and manage dashboards and dashboard lists, mute and unmute hosts, and post or query events.                                                                                                        |
| Read cases, on-call, and security signals | Access cases, on-call schedules and escalation policies, security monitoring rules and signals (including attaching signals to incidents), RUM, DORA metrics, CI visibility, error tracking, and teams. |
| Generic Datadog API access                | Call any supported Datadog v1 or v2 endpoint (385 typed paths) with full control over the request.                                                                                                      |

Anything defined in the [Datadog API](https://docs.datadoghq.com/api/latest/) can be accessed through Serval.

## Get your credentials

Serval needs two keys from Datadog: an **API key** (authenticates the connection to your organization) and an **Application key** (authorizes access to data like metrics, logs, and monitors). Both are created in Datadog under Organization Settings - see [Datadog: API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys/) for the official guide.

<Steps>
  <Step title="Log in to Datadog">
    Log in to your Datadog account. For the US1 site that is [https://app.datadoghq.com](https://app.datadoghq.com); if your organization is on another site, use your site's own app domain.
  </Step>

  <Step title="Create an API key">
    Navigate to **Organization Settings > API Keys**, click **New Key**, name it (e.g. "Serval Integration"), and copy the generated API key.
  </Step>

  <Step title="Create an Application key">
    Navigate to **Organization Settings > Application Keys**, click **New Key**, name it (e.g. "Serval App Key"), optionally edit its scopes, and copy the generated application key.
  </Step>

  <Step title="Note your Datadog site's API domain">
    Check your Datadog dashboard URL to identify your site, then note the matching API domain: api.datadoghq.com (US1), api.us3.datadoghq.com (US3), api.us5.datadoghq.com (US5), api.datadoghq.eu (EU), api.ap1.datadoghq.com (AP1), or api.ddog-gov.com (GOV).
  </Step>
</Steps>

<Warning>
  The Application key inherits the permissions of the Datadog user who creates it. Create it as a user (or service account) with the permissions your workflows need - if that user's permissions are later reduced, what Serval can access narrows with them. See the [Datadog RBAC permissions list](https://docs.datadoghq.com/account_management/rbac/permissions/) for what each permission grants.
</Warning>

<Tip>
  Getting the API domain right matters more than anything else on this page. Your keys only exist on your organization's site, so a US3 organization's keys will never work against the US1 domain.
</Tip>

## Connect in Serval

All four fields are required. Leaving the API Domain or Instance Name blank stops submission with "This field is required", and a submission missing either key is rejected by Serval with an error stating that the key is required.

<Steps>
  <Step title="Enter the API Domain">
    Enter your Datadog site's API host without https\://, e.g. "api.datadoghq.com". The helper text lists the valid options: "Your Datadog API domain (without https\://). Common options: api.datadoghq.com (US1), api.us3.datadoghq.com (US3), api.us5.datadoghq.com (US5), api.datadoghq.eu (EU), api.ap1.datadoghq.com (AP1), api.ddog-gov.com (GOV)". Anything else is rejected with "Must be a valid Datadog API domain (e.g., api.datadoghq.com, api.us3.datadoghq.com, api.datadoghq.eu)".
  </Step>

  <Step title="Enter the API Key">
    Paste the API key you created. This is a password-type field with the helper text "Your Datadog API key. You can generate one from Organization Settings > API Keys".
  </Step>

  <Step title="Enter the Application Key">
    Paste the Application key you created. This is a password-type field with the helper text "Your Datadog application key. Required for accessing metrics, logs, and other data. Generate from Organization Settings > Application Keys".
  </Step>

  <Step title="Enter an Instance Name">
    Give the connection a display name, e.g. "Production". The helper text reads "A name to identify this Datadog instance (e.g., 'Production', 'Engineering'). Required to distinguish between multiple Datadog connections."
  </Step>

  <Step title="Submit the form">
    Click **Submit** to create the connection. Serval stores both keys as secrets and verifies the connection with a health check against your Datadog site.
  </Step>
</Steps>

<Note>
  When editing an existing Datadog connection, any field you leave blank keeps its current value - only fields you fill in are overwritten. To rotate just the API key, fill in only that field. For security, existing key values are never displayed in the edit form.
</Note>

## Verifying the connection

When the connection is created, Serval runs a health check that confirms your API key is valid and your Datadog site is reachable. The integration also includes four named health-check workflows you can run at any time:

* **Validate Datadog API Connection** - confirms the API key is valid and the API is reachable. This check exercises only the API key, not the Application key. On success: "Successfully authenticated with Datadog API". On failure: "Unable to connect to Datadog API. Please verify your API token is valid and has the necessary permissions."
* **Check Datadog Organization Access** - verifies Serval can read your organization details. On success: "Successfully accessed organization: \[organization name]". If the API is reachable but returns no organization data: "Could not retrieve organization information from Datadog". On failure: "Failed to access organization information. Please verify your API token has the necessary permissions."
* **Check Datadog Metrics API Access** - counts metrics active in the last hour. On success: "Successfully accessed Metrics API. Found \[number] active metrics." On failure: "Failed to access Metrics API. Please verify your API token has the necessary permissions for metrics access."
* **Check Datadog Logs API Access** - counts your log pipelines. On success: "Successfully accessed Logs API. Found \[number] log pipelines." On failure: "Failed to access Logs API. Please verify your API token has the necessary permissions for logs access."

<Tip>
  A green connection check does not prove the Application key works - the initial health check and "Validate Datadog API Connection" only test the API key. If workflows get permission errors while the connection looks healthy, run the Organization, Metrics, and Logs health checks, which do exercise the Application key.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Site/region mismatch is the most common connect failure">
    The API Domain is a free-text field validated against exactly six api.\* domains - it is not auto-detected. If your Datadog organization is on US3 or US5 but you enter api.datadoghq.com (US1), the form accepts it and the connection saves, but every API call fails authentication because your keys only exist on your organization's site. Check your Datadog dashboard URL (e.g. us3.datadoghq.com) and use the matching API domain. Enter it without https\:// - the form requires the bare host, and Serval also strips any https\:// or http\:// prefix defensively.
  </Accordion>

  <Accordion title="A green connection check does not prove the Application key works">
    The install-time health check and the "Validate Datadog API Connection" workflow only verify the API key. Reading metrics, logs, monitors, and most other data also requires a valid Application key. If workflow calls return permission errors (403) while the connection looks healthy, check the Application key - and run the Organization, Metrics, and Logs health-check workflows, which do exercise it.
  </Accordion>

  <Accordion title="The Application key inherits its creator's permissions">
    What a Serval workflow can read or write in Datadog is bounded by the role and permissions of the Datadog user who created the Application key. Create the key from a user or service account with the permissions your workflows need, and remember that access narrows if that user's permissions are later reduced.
  </Accordion>

  <Accordion title="Editing the connection: blank fields keep existing values">
    When updating an existing Datadog connection, any field left blank (API Key, Application Key, API Domain, or Instance Name) retains its current value - only non-empty fields are overwritten. To rotate just the API key, fill in only that field. Existing key values are never displayed in the edit form.
  </Accordion>

  <Accordion title="v1 and v2 APIs paginate differently">
    Newer (v2) Datadog APIs, such as log event search, page through results with a cursor: each response includes a cursor value that must be passed into the next request until none is returned. Older (v1) APIs use offset-based paging instead. Some operations also require a specific request method - log search uses POST, not GET. Mixing these up is a common cause of missing results in workflows.
  </Accordion>

  <Accordion title="Instance Name is part of the connection identity">
    The connection's identity is built from the API domain plus the Instance Name, which is what lets you connect multiple Datadog organizations (or multiple key sets) to the same team. Pick a stable, meaningful name like "Production" - it is also the connection's display name.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Datadog integration.