Getting started overview

Integrating with the Datadog API allows programmatic interaction with the Datadog platform, which is designed for full-stack observability. This guide outlines the essential steps to get started: account creation, credential generation, and executing a foundational API request. The Datadog API supports various operations, from submitting custom metrics and events to configuring monitors and dashboards, and retrieving performance data. Key steps involve setting up an account, generating API and Application keys, and making a test call. Datadog provides comprehensive API documentation and client libraries in multiple programming languages to facilitate integration.

Before making any API calls, developers must ensure they meet the prerequisites, primarily having a Datadog account and generating the necessary authentication tokens. These tokens ensure that all requests are authorized and correctly associated with your organization's Datadog instance. Understanding the authentication mechanism is critical for secure and functional API usage.

Create an account and get keys

To begin using the Datadog API, the initial step is to establish a Datadog account. Datadog offers various pricing tiers, including a free tier for several products with usage limits, allowing developers to test functionality without immediate financial commitment. Upon account creation, you will gain access to the Datadog web application, which serves as the central hub for managing your monitoring activities and generating API credentials.

Account Registration

Navigate to the Datadog homepage and follow the sign-up process. This typically involves providing an email address, setting a password, and agreeing to terms of service. Once registered, you will be directed to your Datadog dashboard.

Generating API and Application Keys

Datadog API authentication relies on two primary keys: an API Key and an Application Key. The API Key identifies your organization, while the Application Key identifies the specific user or application making the request. This two-key system enhances security by separating organizational access from user-specific permissions.

  1. Access the Integrations Page: From your Datadog dashboard, navigate to the Organization Settings > API Keys section.
  2. API Key: An API Key is typically generated automatically upon account creation. You can view existing keys or generate a new one if needed. Keep this key secure, as it grants access to your organization's data.
  3. Application Key: In the same API Keys section, look for the 'Application Keys' tab. Click 'New Key' to generate a new application key. Provide a descriptive name for the key to easily identify its purpose later.

It is crucial to handle these keys securely. Avoid hardcoding them directly into your application code and never expose them in client-side code or public repositories. Environment variables or a secure secret management system are recommended for storing and accessing these credentials. For more secure practices regarding API keys, consult developer best practices for API key security.

Your first request

With your API and Application keys in hand, you can now make your first API request. This example demonstrates fetching a list of active monitors using curl, a common command-line tool for making HTTP requests.

Request Endpoint

The Datadog API base URL varies depending on your Datadog site. For most users, it will be api.datadoghq.com. Check your Datadog site information to confirm your specific API endpoint.

Example: List Monitors

This curl command will retrieve a list of all active monitors configured in your Datadog account. Replace <YOUR_API_KEY> and <YOUR_APPLICATION_KEY> with your actual keys.

curl -X GET \
  "https://api.datadoghq.com/api/v1/monitor" \
  -H "Accept: application/json" \
  -H "DD-API-KEY: <YOUR_API_KEY>" \
  -H "DD-APPLICATION-KEY: <YOUR_APPLICATION_KEY>"

Upon successful execution, the API will return a JSON array containing details of your monitors. A successful response typically has an HTTP status code 200 OK.

Quick Reference: Getting Started Steps

Step What to Do Where
1. Create Account Register for a Datadog account. Datadog Homepage
2. Get API Key Locate or generate your API Key. Datadog Account Settings > API Keys
3. Get Application Key Generate a new Application Key. Datadog Account Settings > Application Keys
4. Make First Request Execute a curl command with your keys. Command Line (e.g., as shown in this guide)

Common next steps

After successfully making your first API call, you can explore the extensive capabilities of the Datadog API. Common next steps include:

  • Sending Custom Metrics: Integrate your applications to send custom metrics to Datadog. This allows you to track application-specific performance indicators not covered by standard integrations. The Submit Metrics endpoint is key for this.
  • Managing Monitors: Programmatically create, update, or delete monitors to automate alert configuration based on your infrastructure or application performance. Refer to the Monitors API documentation.
  • Querying Data: Retrieve historical metrics, events, and log data for custom analysis or integration with other systems. The Query Timeseries Points API is frequently used for this purpose.
  • Using Official Client Libraries: For more complex integrations, leverage one of Datadog's official client libraries (SDKs) available for Python, Go, Java, Ruby, C#, and Node.js. These libraries abstract away HTTP request complexities, allowing developers to focus on application logic.
  • Exploring Webhooks: Configure webhooks to receive notifications from Datadog in external systems, enabling real-time integration with incident management or chat platforms. Datadog's webhook integrations provide details.
  • Security Best Practices: Review and implement security best practices for API key management, such as rotating keys regularly and using least privilege principles for application keys.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

  • Check API and Application Keys: Ensure both DD-API-KEY and DD-APPLICATION-KEY headers are correctly set and contain the exact keys copied from your Datadog account. Typos or missing characters are common culprits. Double-check for any leading or trailing spaces.
  • Verify Endpoint URL: Confirm that the base URL used in your curl command matches your specific Datadog site (e.g., api.datadoghq.com, us5.api.datadoghq.com, eu.api.datadoghq.com). An incorrect endpoint will result in connection errors or 404 Not Found responses. Refer to Datadog site information for clarity.
  • HTTP Status Codes:
    • 401 Unauthorized: Typically indicates an issue with your API or Application Key. One or both keys may be incorrect or missing.
    • 403 Forbidden: Your keys are valid, but they lack the necessary permissions to perform the requested action. Review the permissions associated with your Application Key in Datadog.
    • 400 Bad Request: The request body or parameters are malformed. Check the API documentation for the specific endpoint you are calling to ensure the request format is correct.
    • 404 Not Found: The requested resource does not exist, or the endpoint URL is incorrect.
  • Network Connectivity: Ensure your machine has active internet connectivity and that no firewall rules are blocking outgoing requests to Datadog's API endpoints.
  • Consult Datadog API Docs: The official Datadog API reference provides detailed information on each endpoint, expected request/response formats, and potential error codes.
  • Use Datadog Support: If issues persist, collect the HTTP request details (headers, body, response) and consult Datadog's support resources.