Back to Blog
Using the Datadog API for Testing and Monitoring
·UptimePulse Team

Using the Datadog API for Testing and Monitoring

Learn how to use the Datadog API for automated testing, custom monitoring, and integrating Datadog into your CI/CD pipelines.

datadog apiAPI testingautomationCI/CD

The Datadog API unlocks automation possibilities beyond the UI. From custom integrations to automated testing, the API lets you embed Datadog into your workflows and build tailored monitoring solutions.

Datadog API Fundamentals

Authentication

Every API request needs authentication:

# Using API key
curl -X POST "https://api.datadoghq.com/api/v1/series" \
  -H "Content-Type: application/json" \
  -H "DD-API-KEY: YOUR_API_KEY" \
  -d '{"series":[{"metric":"custom.metric","points":[[1626000000,42]]}]}'

# Using client token (for browser RUM)
curl -X POST "https://api.datadoghq.com/api/v1/rum/events" \
  -H "Content-Type: application/json" \
  -H "DD-CLIENT-TOKEN: YOUR_CLIENT_TOKEN" \
  -d '{}'

API Key vs. Client Token

Key TypeUse CaseSecurity
API KeyServer-side integrationsKeep secret
Client TokenBrowser/mobile RUMSafe for client-side
Application KeyUser-level operationsRequires API key

Base URLs

Choose the correct endpoint for your site:

  • US1: https://api.datadoghq.com
  • US3: https://api.us3.datadoghq.com
  • EU: https://api.datadoghq.eu
  • US1-Federal: https://api.ddog-gov.com

Datadog API Testing

Custom Health Checks

Create health checks beyond standard monitors:

import requests

DATADOG_API_KEY = "YOUR_API_KEY"
DATADOG_SITE = "datadoghq.com"

def check_api_health(endpoint, expected_status=200):
    """Custom health check with Datadog reporting"""
    try:
        response = requests.get(endpoint, timeout=10)
        success = response.status_code == expected_status

        # Report to Datadog
        requests.post(
            f"https://api.{DATADOG_SITE}/api/v1/series",
            headers={
                "DD-API-KEY": DATADOG_API_KEY,
                "Content-Type": "application/json"
            },
            json={
                "series": [{
                    "metric": "custom.health.check",
                    "points": [[int(time.time()), 1 if success else 0]],
                    "tags": [f"endpoint:{endpoint}"]
                }]
            }
        )
        return success
    except Exception as e:
        # Report failure
        report_error(str(e))
        return False

API Response Time Monitoring

Track API performance with custom metrics:

const monitorApiPerformance = async (apiUrl) => {
  const startTime = Date.now();

  const response = await fetch(apiUrl);
  const duration = Date.now() - startTime;

  // Send metric to Datadog
  await fetch(`https://api.datadoghq.com/api/v1/series`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'DD-API-KEY': process.env.DD_API_KEY
    },
    body: JSON.stringify({
      series: [{
        metric: 'api.response.time',
        points: [[Math.floor(Date.now() / 1000), duration]],
        tags: [`api:${apiUrl}`, `status:${response.status}`]
      }]
    })
  });

  return { duration, status: response.status };
};

Load Testing Integration

Report load test results to Datadog:

import locust

class WebsiteUser(locust.HttpUser):
    @events.request_success.add_listener
    def on_request(self, request_type, name, response_time, response_length):
        # Report to Datadog
        send_metric(
            metric="loadtest.response.time",
            value=response_time,
            tags=[f"endpoint:{name}", f"method:{request_type}"]
        )

    @events.request_failure.add_listener
    def on_failure(self, request_type, name, response_time, exception):
        send_metric(
            metric="loadtest.errors",
            value=1,
            tags=[f"endpoint:{name}", f"error:{str(exception)}"]
        )

Datadog API Key Management

Creating API Keys

  1. Go to Organization Settings > API Keys
  2. Click New Key
  3. Give it a descriptive name
  4. Copy and store securely

Best Practices

Rotate keys regularly:

  • Create new key
  • Update integrations
  • Verify data flow
  • Revoke old key

Use environment variables:

# Never hardcode keys
export DD_API_KEY="your-key-here"

Limit key scope:

  • Create separate keys for different services
  • Use application keys for user operations
  • Monitor key usage in audit logs

Datadog API Documentation

Key API Endpoints

Metrics:

  • POST /api/v1/series — submit metrics
  • GET /api/v1/query — query metrics
  • GET /api/v1/metrics — list metrics

Events:

  • POST /api/v1/events — create events
  • GET /api/v1/events — query events

Monitors:

  • GET /api/v1/monitor — list monitors
  • POST /api/v1/monitor — create monitor
  • PUT /api/v1/monitor/{id} — update monitor

Logs:

  • POST /api/v2/logs — send logs
  • GET /api/v2/logs/events/search — search logs

Using Swagger

Access interactive API documentation:

https://docs.datadoghq.com/api/

Test endpoints directly in the browser with your API key.

CI/CD Integration

GitHub Actions

# .github/workflows/datadog.yml
name: Report to Datadog
on:
  push:
    branches: [main]

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - name: Send deployment event
        uses: DataDog/datadog-ci@v2
        with:
          sites: us1
          api-key: ${{ secrets.DD_API_KEY }}
          level: application
          service: my-service
          env: production
          start: ${{ github.event.head_commit.timestamp }}
          end: ${{ github.event.head_commit.timestamp }}

GitLab CI

# .gitlab-ci.yml
deploy:
  script:
    - |
      curl -X POST "https://api.datadoghq.com/api/v1/events" \
        -H "Content-Type: application/json" \
        -H "DD-API-KEY: $DD_API_KEY" \
        -d '{
          "title": "Deployment: $CI_COMMIT_SHA",
          "text": "Deployed to production",
          "tags": ["env:production", "service:my-service"],
          "alert_type": "info"
        }'

Jenkins Pipeline

pipeline {
    stages {
        stage('Deploy') {
            steps {
                script {
                    sh '''
                        curl -X POST "https://api.datadoghq.com/api/v1/events" \
                          -H "Content-Type: application/json" \
                          -H "DD-API-KEY: ${DD_API_KEY}" \
                          -d '{"title":"Jenkins Deploy","text":"Deployed ${BUILD_NUMBER}"}'
                    '''
                }
            }
        }
    }
}

Custom Dashboards via API

Programmatic Dashboard Creation

import requests

def create_dashboard(api_key, dashboard_config):
    response = requests.post(
        "https://api.datadoghq.com/api/v1/dashboard",
        headers={
            "DD-API-KEY": api_key,
            "Content-Type": "application/json"
        },
        json=dashboard_config
    )
    return response.json()

# Example dashboard config
dashboard = {
    "title": "API Performance Dashboard",
    "widgets": [{
        "definition": {
            "type": "timeseries",
            "requests": [{
                "q": "avg:api.response.time{service:my-api}"
            }]
        }
    }],
    "layout_type": "ordered"
}

Bulk Dashboard Export/Import

def export_all_dashboards(api_key):
    response = requests.get(
        "https://api.datadoghq.com/api/v1/dashboard",
        headers={"DD-API-KEY": api_key}
    )
    return response.json()["dashboards"]

def import_dashboard(api_key, dashboard):
    requests.post(
        "https://api.datadoghq.com/api/v1/dashboard",
        headers={"DD-API-KEY": api_key},
        json=dashboard
    )

API Rate Limits

Datadog enforces rate limits:

EndpointRate Limit
Metrics submission1000 requests/second
Events submission1000 requests/second
Logs ingestion1000000 events/second
Dashboard API100 requests/minute

Handling Rate Limits

import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session_with_retries():
    session = requests.Session()
    retries = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504]
    )
    session.mount("https://", HTTPAdapter(max_retries=retries))
    return session

Common API Use Cases

Custom Alerting

Send alerts to custom channels:

def send_custom_alert(message, severity="warning"):
    requests.post(
        "https://api.datadoghq.com/api/v1/events",
        headers={"DD-API-KEY": API_KEY},
        json={
            "title": f"Custom Alert: {severity}",
            "text": message,
            "alert_type": severity,
            "tags": ["source:custom-api"]
        }
    )

Data Enrichment

Add context to metrics:

def submit_enriched_metric(metric_name, value, context):
    requests.post(
        "https://api.datadoghq.com/api/v1/series",
        headers={"DD-API-KEY": API_KEY},
        json={
            "series": [{
                "metric": metric_name,
                "points": [[int(time.time()), value]],
                "tags": [
                    f"service:{context['service']}",
                    f"version:{context['version']}",
                    f"environment:{context['env']}"
                ]
            }]
        }
    )

Getting Started

  1. Get your API key from Datadog
  2. Test with a simple curl command
  3. Build a custom health check
  4. Integrate with your CI/CD pipeline
  5. Create programmatic dashboards

The Datadog API opens up unlimited possibilities for custom monitoring and automation. Start with simple integrations and expand as your needs grow.