Datadog Connector

Overview

Connects to Datadog to fetch monitored hosts for syncing into Xurrent's CMDB.

Prerequisites

• A Datadog account on any supported site.
• An API key from Organization Settings → API Keys (docs).
• An Application key from Organization Settings → Application Keys that carries the hosts_read scope.

Authentication

Header-based. Each outbound request carries DD-API-KEY and DD-APPLICATION-KEY, populated from the connection's API Key and Application Key credential fields. No OAuth flow is involved.

Configuration

Pick a Region matching your Datadog site. The connector routes all calls to the region's API host:

Triggers

None — this connector is outbound only.

Actions

Fetch hosts

Retrieves all hosts from Datadog with pagination support using the Hosts API (v1).

Use case: populate or refresh the list of Datadog-monitored hosts in Xurrent's CMDB. Use the From field to fetch only hosts reported at or after a specific time, which is useful for incremental CMDB updates.

Input Parameters

Example Input

{
"page_size": 100,
"from": 1771410150,
"filter": "my-host",
"sort_dir": "asc"
}

Output

Host object fields

Example Output

{
"total_matching": 1,
"total_returned": 1,
"has_next_page": false,
"host_list": [
  {
    "id": 123145537712914,
    "name": "Xurrent-FNX2Y3Q7FK",
    "host_name": "Xurrent-FNX2Y3Q7FK",
    "aliases": ["Xurrent-FNX2Y3Q7FK"],
    "apps": ["agent", "ntp"],
    "sources": ["agent"],
    "up": true,
    "is_muted": false,
    "mute_timeout": null,
    "last_reported_time": 1770967634,
    "tags_by_source": {
      "Datadog": ["host:Xurrent-FNX2Y3Q7FK"]
    },
    "meta": {
      "cpu_cores": 12,
      "agent_version": "7.75.3",
      "timezones": ["IST"],
      "platform": "darwin",
      "machine": "arm64",
      "processor": "Apple M4 Pro",
      "install_method": {
        "installer_version": null,
        "tool": null,
        "tool_version": "install_script_mac"
      },
      "logs_agent": {
        "transport": ""
      },
      "agent_flavor": "agent",
      "host_id": 123145537712914,
      "gohai": {
        "cpu": { "cpu_cores": "12", "model_name": "Apple M4 Pro" },
        "memory": { "swap_total": "2097152kB", "total": "25769803776" }
      }
    },
    "metrics": {
      "cpu": 8.087143,
      "iowait": 0,
      "load": 0.1817419
    }
  }
]
}

Error Handling

The job fails immediately on 400 / 401 / 403 responses (invalid input or credential/scope issue). On 429 (rate limited) or 5xx server errors, the connector waits for the time in X-RateLimit-Reset and retries automatically.

Best Practices

• Incremental: Use from set to the epoch-seconds of your last successful sync; store the max last_reported_time seen in this run for the next run's from.
• Full metadata off by default: Set include_hosts_metadata = true only when you need agent / OS / Gohai details — otherwise leave it off to reduce payload.
• Deterministic paging: Set sort_field = "name" and sort_dir = "asc" to page through hosts in a stable order across runs.
• Paginate to completion: Call until has_next_page = false — the connector manages the cursor internally.

Rate Limiting

Datadog applies per-endpoint rate limits that vary by site and plan, surfaced on rate-limited endpoints via X-RateLimit-* headers (reference). The connector reads the limit off those headers and backs off automatically. Higher limits can be requested through a Datadog support ticket.

Best Practices

• Incremental syncs: Set the from input on Fetch hosts to the epoch-seconds timestamp of your last sync — returns only hosts that have reported since then.
• Track sync state: Store the max last_reported_time seen in this run and use it as the next from input.
• Filter noise: Use the filter input (free-text match) or combine with sort_field / sort_dir to narrow results when you don't need the full host list.
• Scope metadata: Leave include_hosts_metadata = false unless you specifically need the meta field (agent / OS / Gohai details) — it's a larger payload per host.
• Match Region to your Datadog site: Set the connection's Region to match your Datadog account's site. API keys are scoped to a single site, so a mismatched region returns 403 Forbidden.

Common Use Cases

• CMDB sync — mirror Datadog-monitored hosts into Xurrent's CMDB as Configuration Items.
• Incident enrichment — on incident creation, look up the affected host's agent version, OS, and last-reported time.
• Fleet inventory — periodic pull of all hosts with up, is_muted, and metrics for monitoring dashboards.
• Compliance reporting — track reporting vs. non-reporting hosts by filtering on up and last_reported_time.

References

• Datadog Hosts API (v1)
• Rate limits
• Sites and URLs
• API and application keys