Getting Started with API Tests
Incident Management is now generally available! Incident Management is now generally available!

Getting Started with API Tests

Create an API test

API tests help you monitor your API endpoints and alert you when they are failing or too slow. These checks verify that your applications are responding to requests and meet any conditions you define, such as response time, HTTP status code, and header or body contents. Use the Datadog API to see the full list.

In this example, an API test is created to ensure your website is constantly up and providing responses in a specific amount of time.

Configure the request

  1. In the Datadog application, hover over UX Monitoring in the left hand menu and select Synthetic Test.

  2. In the top right corner, click the New Test button.

  3. Select API test.

  4. Define the configuration of your API test:

    • Add the URL of the endpoint you want to monitor. If you don’t know what to start with, you can use, which is a test web application.
    • Select Advanced Options to use custom request headers, authentication credentials, body content, or cookies.
    • Add some tags to help organize and filter tests.
    • Select locations for testing.
    • Click the Test URL button.

Define your alert conditions

Now that the test is completed, if you did not create any assertions, they are automatically populated. API tests require at least one assertion to be monitored by Datadog. An assertion is defined by a parameter, an optional property, a comparator, and a target value.

In this example, three default assertions are populated when testing the URL:

These assertions define the alert condition and can be customized. To add a custom assertion, click on any response header in the response preview. You can also click the New Assertion button to add an assertion manually (e.g., body contains

Browser test failure

You can set up an alerting condition in order to only be alerted if your endpoint goes down for three minutes, on two different locations:

An alert is triggered if your test fails for 3 minutes from any 2 of 13 locations

You can also decide after how many failures you want a location to be considered as fail. Retries will be run immediately after the location fails. You can configure the test using the option below:

Retry x time before location is marked as failed

Note: By default, there is a 300ms wait before retrying a test that failed. This interval can be configured via the API.

Once alert conditions are set, create a message for the alert and specify what services and team members receive the alert notification email and click Save Test. You can also use integrations, such as Slack, PagerDuty, webhooks, etc., to receive alert notifications.

Test results

An API test homepage will automatically populate after save. This page includes property information, historical graphs for response time and uptime, sample results, and all events and test results.

To troubleshoot a failed test, scroll to the Test Results section and click on the Test Results tab. Click on the failed test, labeled as Alert, to view detailed test results. Review the failed assertions and response details such as returned status code, response time, and associated headers and body to resolve the issue.

Datadog also has an APM integration with Synthetic Monitoring which allows you to go from a test run that failed to the root cause of the issue by looking at the trace generated by that test run.