API Tests
New announcements from Dash: Incident Management, Continuous Profiler, and more! New announcements from Dash!

API Tests

Overview

API tests are useful to help you monitor your API endpoints and alert you when they are failing or too slow. These tests verify that your applications are responding to requests, as well as that they 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.

Configuration

API tests configuration depends on the type of API test you want to create: HTTP test, SSL test, TCP test, or DNS test.

Make a request

Define the HTTP, SSL, TCP, or DNS request you want to be executed by Datadog:

Define the request you want to be executed by Datadog:

  1. Choose a request type: HTTP.
  2. Choose the Method and URL to query. Available methods are: GET, POST, PATCH, PUT, HEAD, DELETE, and OPTIONS.
  3. Add Advanced Options (optional) to your test:

    • Follow redirects: Toggle to have the monitored endpoint follow up to ten redirects.
    • Allow insecure server certificates: Toggle to have your HTTP test go on with connection even if there is an error when validating the certificate.
    • Client certificate: Authenticate through mTLS by uploading your client certificate and associated private key.
    • Request headers: Defined headers override the default browser headers. For example, set the User Agent in the header to identify Datadog scripts.
    • Cookies: Defined cookies are added to the default browser cookies. Set multiple cookies using the format <COOKIE_NAME1>=<COOKIE_VALUE1>; <COOKIE_NAME2>=<COOKIE_VALUE2>.
    • HTTP Basic Auth: HTTP basic authentication with username and password.
    • Request body: Request body and body type (text/plain, application/json, text/xml, text/html, or None). Note: The request body is limited to a maximum size of 50 kilobytes.
    • Proxy URL: URL of the proxy the HTTP request should go through (http://<YOUR_USER>:<YOUR_PWD>@<YOUR_IP>:<YOUR_PORT>).
    • Proxy Header: Headers to include in the HTTP request to the proxy.
  4. Name: The name of your API test.

  5. Select your tags: The tags attached to your browser test. Use the <KEY>:<VALUE> format to filter on a <VALUE> for a given <KEY> on the Synthetic Monitoring page.

  6. Locations: The Datadog managed locations to run the test from. Many AWS locations from around the world are available. The full list is retrievable through the Datadog API. You can also set up a Private Location to run a Synthetic API test on a private endpoint not accessible from the public internet.

  7. How often should Datadog run the test? Intervals are available between every one minute to once per week.

  8. Click on Test URL to try out the request configuration. You should see a response preview show up on the right side of your screen.

  1. Choose a request type: SSL.
  2. Specify the Host and the SSL Port. By default, the port is set to 443.
  3. Add Advanced Options (optional) to your test:

    • Accept self-signed certificates: Bypass errors related to self-signed certificate.
    • Client certificate: Authenticate through mTLS by uploading your client certificate and associated private key.
  4. Name: The name of your SSL test.

  5. Select your tags: The tags attached to your SSL test. Use the <KEY>:<VALUE> format to filter on a <VALUE> for a given <KEY> on the Synthetic Monitoring page.

  6. Locations: The Datadog managed locations to run the test from. Many AWS locations from around the world are available. The full list is retrievable through the Datadog API. You can also set up a Private Location to run your Synthetic SSL test on a private host not accessible from the public internet.

  7. How often should Datadog run the test? Intervals are available between every one minute to once per week.

  8. Click on Test Connection to try out the request configuration. You should see a response preview show up on the right side of your screen.

  1. Choose a request type: TCP.
  2. Specify the Host and the TCP Port.
  3. Name: The name of your TCP test.
  4. Select your tags: The tags attached to your TCP test. Use the <KEY>:<VALUE> format to filter on a <VALUE> for a given <KEY> on the Synthetic Monitoring page.
  5. Locations: The Datadog managed locations to run the test from. Many AWS locations from around the world are available. The full list is retrievable through the Datadog API. You can also set up a Private Location to run your Synthetic TCP test on a private host or port not accessible from the public internet.
  6. How often should Datadog run the test? Intervals are available between every one minute to once per week.
  7. Click Test URL to try the request configuration and see a response preview on the righthand side.
  1. Choose a request type: DNS.
  2. Specify the Domain and optional DNS Server to use.
  3. Name: The name of your DNS test.
  4. Select your tags: The tags attached to your DNS test. Use the <KEY>:<VALUE> format to filter on a <VALUE> for a given <KEY> on the Synthetic Monitoring page.
  5. Locations: The Datadog managed locations to run the test from. Many AWS locations from around the world are available. The full list is retrievable through the Datadog API. You can also set up a Private Location to run a Synthetic DNS test on a private domain that cannot be resolved from the public internet.
  6. How often should Datadog run the test? Intervals are available between every one minute to once per week.
  7. Click Test URL to try the request configuration and see a response preview on the righthand side.

Assertions

When running an API test, you must define at least one assertion that should be monitored by Datadog. An assertion is defined by a parameter, an optional property, a comparator, and a target value.

TypeOperatorValue type
bodycontains, does not contain, is, is not,
matches, does not match,
jsonpath
String
Regex
String, Regex
headercontains, does not contain, is, is not,
matches, does not match
String
Regex
response timeis less thanInteger (ms)
status codeis, is notInteger

Note: HTTP tests can uncompress bodies with the following content-encoding headers: br, deflate, gzip, and identity.

If you click on Test URL, then the basic assertions are automatically filled:

  • response time is less than 1000 ms
  • status code is “returned value”
  • header content-type is “returned value”
TypeOperatorValue type
certificateexpires in more than, expires in less thanInteger (number of days)
propertycontains, does not contain, is, is not,
matches, does not match
String
Regex
response timeis less thanInteger (ms)

If you click on Test URL, then the basic assertion is automatically filled:

  • certificate expires in more than 10 days
  • response time is less than 1000 ms.
TypeOperatorValue type
response timeis less thanInteger (ms)

If you click on Test URL, then the basic assertion is automatically filled:

  • response time is less than 1000 ms.
TypeRecord typeOperatorValue type
response timeis less thanInteger (ms)
every recordof type A, of type AAAAis, contains,
matches, does not match
String
Regex
at least one recordof type A, of type AAAAis, contains,
matches, does not match
String
Regex

If you click on Test URL, then the basic assertions are automatically filled:

  • response time is less than 1000 ms
  • at least one record of type A is “returned value” (when returned)
  • at least one record of type AAAA is “returned value” (when returned)

You can create up to 10 assertions per API test by clicking on Add new assertion or by clicking directly on the response preview:

Alert Conditions

Set alert conditions to determine the circumstances under which you want a test to fail and trigger an alert.

Alerting Rule

When you set the alert conditions to: An alert is triggered if any assertion fails for X minutes from any n of N locations, an alert is triggered if:

  • At least one location was in failure (at least one assertion failed) during the last X minutes, and
  • At one moment during the last X minutes, at least n locations were in failure.

The uptime bar is displayed differently on your test result: location uptime is displayed on a per-evaluation basis (whether the last test was up or down). Total uptime is displayed based on the configured alert conditions. Notifications sent are based on the total uptime bar.

Fast Retry

You can decide the number of retries needed to consider a location as failed. By default, Synthetic tests do not retry after a failed result for a given location.

Use global variables

You can use the global variables defined in the Settings in the URL, Advanced Options, and in the assertions of your API tests. To display your list of variables, type {{ in your desired field.

Notify your team

A notification is sent according to the set of alerting conditions. To configure notifications:

  1. Select users and/or services to receive notifications. Note: @-notifications are available in the message field, similar to monitors.
  2. Enter a message for the API test. This field allows standard Markdown formatting and supports the following conditional variables:

    Conditional VariableDescription
    {{#is_alert}}Show when monitor alerts
    {{^is_alert}}Show unless monitor alerts
    {{#is_recovery}}Show when monitor recovers from either ALERT
    {{^is_recovery}}Show unless monitor recovers from either ALERT

    Notification messages include the message defined in this section and information about which assertion failed and why.

  3. Specify a renotification frequency. To prevent renotification on failing tests, leave the option as Never renotify if the monitor has not been resolved.

  4. Click Save.

Notifications example:

Network timings

The Synthetic test details page displays the following network timings:

TimingDescription
DNSTime spent resolving the DNS name of the last request.
ConnectTime spent establishing a connection to the server.
SSLTime spent for the TLS handshake. If the last request is not over HTTPS, this metric does not appear.
TTFB (time to first byte)Time spent waiting for the first byte of response to be received.
DownloadTime spent downloading the response.

Response time is the sum of these network timings.

Test Failure

A test is considered FAILED if it does not satisfy its assertions or if the request failed for another reason. These reasons include:

ErrorDescription
CONNRESETThe connection was abruptly closed by the remote server. Possible causes include the webserver encountering an error or crashing while responding, or loss of connectivity of the webserver.
DNSDNS entry not found for the check URL. Possible causes include misconfigured check URL, wrong configuration of your DNS entries, etc.
INVALID_REQUESTThe configuration of the check is invalid (for example, a typo in the URL).
SSLThe SSL connection couldn’t be performed. See the dedicated error page for more information.
TIMEOUTThe request couldn’t be completed in a reasonable time. Two types of TIMEOUT can happen. TIMEOUT: The request couldn’t be completed in a reasonable time. indicates that the timeout happened at the TCP socket connection level. TIMEOUT: Retrieving the response couldn’t be completed in a reasonable time. indicates that the timeout happened on the overall run (which includes TCP socket connection, data transfer, and assertions).

If a test fails, the uptime directly considers the endpoint to be down. It is not retested until the next test run.

Further Reading