How to Use Datadog API

Whether you're integrating custom applications, automating workflows, or extending Datadog's functionality, understanding how to leverage the API is essential for maximizing the platform's potential.

Mark Ponomarev

Mark Ponomarev

12 April 2025

How to Use Datadog API
💡
When working with the Datadog API or any other APIs, having a powerful API development and testing platform is crucial. Apidog stands out as an excellent Postman alternative offering a comprehensive suite of tools for API development.
button

Introduction to the Datadog API

Datadog's API provides programmatic access to the platform's robust monitoring and analytics capabilities. This RESTful API allows developers to send data, build visualizations, and manage their Datadog accounts through code. Whether you're integrating custom applications, automating workflows, or extending Datadog's functionality, understanding how to leverage the API is essential for maximizing the platform's potential.

The Datadog API is designed with a resource-oriented architecture that uses standard HTTP response codes, accepts and returns JSON in all requests, and utilizes standard HTTP methods. This makes it intuitive for developers familiar with RESTful web services. The API's comprehensive functionality enables both read and write operations, allowing you to not only retrieve monitoring data but also configure various aspects of your Datadog environment.

By mastering the Datadog API, you'll be able to:

Getting Started with the Datadog API Authentication

Before making any API calls, you'll need to properly set up authentication to ensure secure access to your Datadog resources.

Obtaining Datadog API and Application Keys

To start using the Datadog API, you'll need two types of keys:

  1. API Key: This identifies your Datadog account and is required for all API requests.
  1. Application Key: Required for many management endpoints, this provides additional authentication and specifies access permissions.

Setting Up Datadog API Authentication Headers

When making API requests, you'll need to include these keys as headers:

Here's an example of a basic authenticated request:

curl -X GET "<https://api.datadoghq.com/api/v1/dashboard>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here"

Managing Datadog API Key Security

Given the significant access these keys provide, following security best practices is crucial:

Core Datadog API Concepts

Understanding the foundational concepts of the Datadog API will help you navigate its extensive capabilities more effectively.

Datadog API Endpoints Structure

The Datadog API is logically organized into functional areas that mirror the platform's capabilities:

Making Your First Datadog API Call

Let's start with a common use case: submitting a custom metric. This example demonstrates how to send a simple gauge metric with tags:

import requests
import time
import json

api_key = "your_api_key_here"
current_time = int(time.time())

payload = {
    "series": [
        {
            "metric": "custom.application.performance",
            "points": [[current_time, 100]],
            "type": "gauge",
            "tags": ["environment:production", "application:web", "region:us-east"]
        }
    ]
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/series>",
                        headers=headers,
                        data=json.dumps(payload))

print(f"Response Status Code: {response.status_code}")
print(f"Response Body: {response.json()}")

This code snippet:

Understanding Datadog API Response Format

Datadog API responses typically follow a consistent JSON format:

{
  "status": "ok",
  "errors": [],
  "data": {
    "id": "abc-123-xyz",
    "name": "Example Resource",
    "created_at": "2023-06-01T12:00:00.000Z",
    "modified_at": "2023-06-02T15:30:00.000Z",
    ...
  }
}

Key fields include:

Common Datadog API Use Cases and Examples

Let's explore practical applications of the Datadog API through detailed examples covering key functionality.

Retrieving Datadog API Dashboard Information

Dashboards are central to Datadog's visualization capabilities. Here's how to retrieve details about a specific dashboard:

curl -X GET "<https://api.datadoghq.com/api/v1/dashboard/dashboard_id>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here"

To create a new dashboard programmatically:

import requests
import json

api_key = "your_api_key_here"
app_key = "your_app_key_here"

dashboard_payload = {
    "title": "API Generated Dashboard",
    "description": "Created via the Datadog API",
    "widgets": [
        {
            "definition": {
                "type": "timeseries",
                "requests": [
                    {
                        "q": "avg:system.cpu.user{*} by {host}",
                        "display_type": "line"
                    }
                ],
                "title": "CPU Usage by Host"
            }
        }
    ],
    "layout_type": "ordered"
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key,
    "DD-APPLICATION-KEY": app_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/dashboard>",
                        headers=headers,
                        data=json.dumps(dashboard_payload))

print(f"Dashboard created with ID: {response.json().get('id')}")

Creating a Monitor with the Datadog API

Monitors are essential for proactive alerting. Here's how to create a monitor that alerts when CPU usage exceeds a threshold:

import requests
import json

api_key = "your_api_key_here"
app_key = "your_app_key_here"

monitor_payload = {
    "name": "High CPU Usage Alert",
    "type": "metric alert",
    "query": "avg(last_5m):avg:system.cpu.user{*} > 80",
    "message": "CPU usage is above 80% for the last 5 minutes. @slack-alerts-channel @email.address@example.com",
    "tags": ["app:web", "env:production", "team:infrastructure"],
    "priority": 3,
    "options": {
        "notify_no_data": True,
        "no_data_timeframe": 10,
        "new_host_delay": 300,
        "evaluation_delay": 60,
        "thresholds": {
            "critical": 80,
            "warning": 70
        },
        "include_tags": True,
        "notify_audit": False,
        "require_full_window": False
    }
}

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key,
    "DD-APPLICATION-KEY": app_key
}

response = requests.post("<https://api.datadoghq.com/api/v1/monitor>",
                        headers=headers,
                        data=json.dumps(monitor_payload))

print(f"Response Status: {response.status_code}")
print(f"Monitor created: {response.json()}")

This example:

Integrating with AWS using the Datadog API

Connecting Datadog with cloud services extends its monitoring capabilities. Here's how to create an AWS integration:

curl -X POST "<https://api.datadoghq.com/api/v1/integration/aws>" \\\\
-H "Content-Type: application/json" \\\\
-H "DD-API-KEY: your_api_key_here" \\\\
-H "DD-APPLICATION-KEY: your_app_key_here" \\\\
-d '{
  "account_id": "your_aws_account_id",
  "role_name": "DatadogAWSIntegrationRole",
  "access_key_id": "your_access_key",
  "secret_access_key": "your_secret_key",
  "filter_tags": ["env:production", "service:critical"],
  "host_tags": ["account:main", "region:us-east-1"],
  "account_specific_namespace_rules": {
    "auto_scaling": true,
    "opsworks": false,
    "elasticache": true
  },
  "excluded_regions": ["us-west-2", "ca-central-1"]
}'

This integration setup:

Sending Logs via the Datadog API

Logs provide critical contextual information for troubleshooting. Here's how to send logs directly to Datadog:

import requests
import json
import datetime

api_key = "your_api_key_here"

logs_payload = [{
    "ddsource": "python",
    "ddtags": "env:production,service:payment-processor,version:1.2.3",
    "hostname": "payment-service-01",
    "message": "Payment transaction completed successfully for order #12345",
    "service": "payment-service",
    "status": "info",
    "timestamp": datetime.datetime.now().isoformat(),
    "attributes": {
        "transaction_id": "tx_789012345",
        "amount": 99.95,
        "currency": "USD",
        "customer_id": "cust_123456",
        "payment_method": "credit_card"
    }
}]

headers = {
    "Content-Type": "application/json",
    "DD-API-KEY": api_key
}

response = requests.post("<https://http-intake.logs.datadoghq.com/v1/input>",
                        headers=headers,
                        data=json.dumps(logs_payload))

print(f"Log submission response: {response.status_code}")

This example:

Working with Datadog API Rate Limits

Datadog enforces rate limits to ensure platform stability and fair usage across customers. Understanding and respecting these limits is crucial for reliable API integration.

Understanding Datadog API Rate Limiting

Different endpoints have different rate limits based on their resource intensity and typical usage patterns:

Monitoring Datadog API Rate Limit Headers

When making API requests, check these response headers to understand your current rate limit status:

Implementing Rate Limit Handling in Datadog API Calls

Here's a robust implementation for handling rate limits with exponential backoff:

import requests
import time
import random

def make_api_request_with_backoff(url, headers, payload=None, max_retries=5):
    retries = 0
    while retries < max_retries:
        response = requests.post(url, headers=headers, json=payload) if payload else requests.get(url, headers=headers)

        if response.status_code == 429:  # Too Many Requests
            # Extract rate limit information
            limit = response.headers.get('X-RateLimit-Limit', 'Unknown')
            remaining = response.headers.get('X-RateLimit-Remaining', 'Unknown')
            reset = int(response.headers.get('X-RateLimit-Reset', 60))

            print(f"Rate limit hit: {remaining}/{limit} requests remaining. Reset in {reset} seconds.")

            # Calculate backoff time with jitter
            backoff_time = min(2 ** retries + random.uniform(0, 1), reset)
            print(f"Backing off for {backoff_time:.2f} seconds")
            time.sleep(backoff_time)
            retries += 1
        else:
            return response

    raise Exception(f"Failed after {max_retries} retries due to rate limiting")

Using Datadog API Client Libraries

For convenience, Datadog offers official client libraries in multiple languages, simplifying authentication and request formatting.

Python Datadog API Client

The official Python client provides a clean, idiomatic interface to the Datadog API:

pip install datadog-api-client

Here's an example of submitting metrics using the client:

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v1.api.metrics_api import MetricsApi
from datadog_api_client.v1.model.metrics_payload import MetricsPayload
from datadog_api_client.v1.model.metrics_series import MetricsSeries
from datadog_api_client.v1.model.point import Point
import time

configuration = Configuration()
configuration.api_key["apiKeyAuth"] = "your_api_key_here"
configuration.api_key["appKeyAuth"] = "your_app_key_here"

with ApiClient(configuration) as api_client:
    api_instance = MetricsApi(api_client)
    body = MetricsPayload(
        series=[
            MetricsSeries(
                metric="application.request.duration",
                points=[
                    Point([int(time.time()), 250.0])
                ],
                type="gauge",
                host="web-server-01",
                tags=["endpoint:login", "environment:staging"]
            )
        ]
    )
    response = api_instance.submit_metrics(body=body)
    print(f"Metrics submission successful: {response}")

Ruby Datadog API Client

For Ruby applications, the official client library streamlines API interactions:

gem install datadog_api_client -v 2.31.1

Example usage for creating a monitor:

require 'datadog_api_client'

DatadogAPIClient.configure do |config|
  config.api_key = 'your_api_key_here'
  config.application_key = 'your_app_key_here'
end

api_instance = DatadogAPIClient::V1::MonitorsAPI.new
body = {
  'name' => 'API test monitor',
  'type' => 'metric alert',
  'query' => 'avg(last_5m):avg:system.cpu.user{*} > 75',
  'message' => 'CPU usage is high',
  'tags' => ['test:api', 'monitor:automated'],
  'options' => {
    'thresholds' => {
      'critical' => 75,
      'warning' => 65
    }
  }
}

begin
  result = api_instance.create_monitor(body)
  puts "Monitor created successfully with ID: #{result['id']}"
rescue DatadogAPIClient::APIError => e
  puts "Error creating monitor: #{e}"
end

Best Practices for Datadog API Usage

Following these guidelines will help you build more reliable, secure, and efficient integrations with the Datadog API.

Securing Your Datadog API Keys

The security of your API keys is paramount:

Using Tags Effectively in Datadog API Calls

Tags are a powerful mechanism for organizing and filtering your Datadog data:

Implementing Error Handling for Datadog API Requests

Robust error handling ensures your integrations remain reliable:

def send_to_datadog(endpoint, payload, headers):
    try:
        response = requests.post(endpoint,
                                json=payload,
                                headers=headers,
                                timeout=10)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.Timeout:
        print("Request timed out - Datadog API may be experiencing delays")
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 400:
            print(f"Bad request: {e.response.json().get('errors', [])}")
        elif e.response.status_code == 403:
            print("Authentication error - check your API and application keys")
        elif e.response.status_code == 429:
            print("Rate limit reached - implement backoff and retry")
        else:
            print(f"HTTP error: {e.response.status_code}")
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")

    return None

Testing in Sandbox Environments with the Datadog API

Before implementing in production:

Monitoring Datadog API Usage

Track your API usage to detect issues early:

Conclusion: Mastering the Datadog API

The Datadog API provides powerful capabilities for extending and customizing your monitoring and analytics platform. By understanding the authentication process, core concepts, and best practices outlined in this guide, you'll be well-equipped to integrate Datadog into your applications and automate your workflows effectively.

Whether you're sending custom metrics, creating monitors, or building complex dashboards, the API offers the flexibility to tailor Datadog to your specific needs. As your usage matures, consider implementing more advanced patterns like:

The programmatic capabilities provided by the Datadog API enable you to build a monitoring ecosystem that scales with your infrastructure and adapts to your organization's unique requirements.

Remember to check Datadog's official API documentation regularly, as new endpoints and features are frequently added to expand the platform's capabilities. With the knowledge gained from this guide, you're ready to build sophisticated, automated monitoring solutions that leverage the full power of Datadog's observability platform.

button

Explore more

15 Best Open-Source RAG Frameworks in 2025

15 Best Open-Source RAG Frameworks in 2025

Large Language Models (LLMs) are revolutionary, but they have a fundamental limitation: their knowledge is frozen in time, limited to the data they were trained on. They can't access your private documents, query real-time data, or cite their sources. This is where Retrieval-Augmented Generation (RAG) comes in. RAG is the architectural pattern that gives LLMs a superpower: the ability to retrieve relevant information from external knowledge bases before answering a question. This simple but pow

6 June 2025

Stagehand Review: Best AI Browser Automation Framework?

Stagehand Review: Best AI Browser Automation Framework?

Browser automation has long been a cornerstone of modern software development, testing, and data extraction. For years, frameworks like Selenium, Puppeteer, and more recently, Playwright, have dominated the landscape. These tools offer granular control over browser actions, but they come with a steep learning curve and a significant maintenance burden. Scripts are often brittle, breaking with the slightest change in a website's UI. On the other end of the spectrum, a new wave of AI-native agents

6 June 2025

15 Best Browser Automation Tools for Web Testing and Scraping in 2025

15 Best Browser Automation Tools for Web Testing and Scraping in 2025

The world of web automation is in the middle of a seismic shift. For years, the landscape was dominated by powerful-but-complex frameworks that demanded deep coding knowledge. Today, a new generation of AI-driven tools is emerging, promising to make automation more intuitive, resilient, and accessible than ever before. In 2025, the best tool is no longer just about having the most features; it's about providing the right balance of control, flexibility, and intelligence for the task at hand. Wh

6 June 2025

Practice API Design-first in Apidog

Discover an easier way to build and use APIs