Trigger Synthetic tests

POST https://api.ap1.datadoghq.com/api/v1/synthetics/tests/triggerhttps://api.ap2.datadoghq.com/api/v1/synthetics/tests/triggerhttps://api.datadoghq.eu/api/v1/synthetics/tests/triggerhttps://api.ddog-gov.com/api/v1/synthetics/tests/triggerhttps://api.us2.ddog-gov.com/api/v1/synthetics/tests/triggerhttps://api.datadoghq.com/api/v1/synthetics/tests/triggerhttps://api.us3.datadoghq.com/api/v1/synthetics/tests/triggerhttps://api.us5.datadoghq.com/api/v1/synthetics/tests/trigger

Overview

Trigger a set of Synthetic tests. This endpoint requires the synthetics_write permission.

OAuth apps require the synthetics_write authorization scope to access this endpoint.

Request

Body Data (required)

The identifiers of the tests to trigger.

Expand All

Field

Type

Description

tests [required]

[object]

List of Synthetic tests.

metadata

object

Metadata for the Synthetic tests run.

ci

object

Description of the CI provider.

pipeline

object

Description of the CI pipeline.

url

string

URL of the pipeline.

provider

object

Description of the CI provider.

name

string

Name of the CI provider.

git

object

Git information.

branch

string

Branch name.

commitSha

string

The commit SHA.

public_id [required]

string

The public ID of the Synthetic test to trigger.

{
  "tests": [
    {
      "public_id": "123-abc-456"
    }
  ]
}

Response

OK

Object containing information about the tests triggered.

Expand All

Field

Type

Description

batch_id

string

The public ID of the batch triggered.

locations

[object]

List of Synthetic locations.

id

int64

Unique identifier of the location.

name

string

Name of the location.

results

[object]

Information about the tests runs.

device

string

The device ID.

location

int64

The location ID of the test run.

public_id

string

The public ID of the Synthetic test.

result_id

string

ID of the result.

triggered_check_ids

[string]

The public IDs of the Synthetic test triggered.

{
  "batch_id": "string",
  "locations": [
    {
      "id": "integer",
      "name": "string"
    }
  ],
  "results": [
    {
      "device": "chrome.laptop_large",
      "location": "integer",
      "public_id": "string",
      "result_id": "string"
    }
  ],
  "triggered_check_ids": []
}

Bad Request

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

Error response object.

Expand All

Field

Type

Description

errors [required]

[string]

Array of errors returned by the API.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                          ## default
# 

# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v1/synthetics/tests/trigger" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "tests": [ { "public_id": "aaa-aaa-aaa" } ] } EOF
// Trigger Synthetic tests returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV1"
)

func main() {
	// there is a valid "synthetics_api_test" in the system
	SyntheticsAPITestPublicID := os.Getenv("SYNTHETICS_API_TEST_PUBLIC_ID")

	body := datadogV1.SyntheticsTriggerBody{
		Tests: []datadogV1.SyntheticsTriggerTest{
			{
				PublicId: SyntheticsAPITestPublicID,
			},
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV1.NewSyntheticsApi(apiClient)
	resp, r, err := api.TriggerTests(ctx, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `SyntheticsApi.TriggerTests`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `SyntheticsApi.TriggerTests`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// Trigger Synthetic tests returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v1.api.SyntheticsApi;
import com.datadog.api.client.v1.model.SyntheticsTriggerBody;
import com.datadog.api.client.v1.model.SyntheticsTriggerCITestsResponse;
import com.datadog.api.client.v1.model.SyntheticsTriggerTest;
import java.util.Collections;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    SyntheticsApi apiInstance = new SyntheticsApi(defaultClient);

    // there is a valid "synthetics_api_test" in the system
    String SYNTHETICS_API_TEST_PUBLIC_ID = System.getenv("SYNTHETICS_API_TEST_PUBLIC_ID");

    SyntheticsTriggerBody body =
        new SyntheticsTriggerBody()
            .tests(
                Collections.singletonList(
                    new SyntheticsTriggerTest().publicId(SYNTHETICS_API_TEST_PUBLIC_ID)));

    try {
      SyntheticsTriggerCITestsResponse result = apiInstance.triggerTests(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SyntheticsApi#triggerTests");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
"""
Trigger Synthetic tests returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v1.api.synthetics_api import SyntheticsApi
from datadog_api_client.v1.model.synthetics_trigger_body import SyntheticsTriggerBody
from datadog_api_client.v1.model.synthetics_trigger_test import SyntheticsTriggerTest

# there is a valid "synthetics_api_test" in the system
SYNTHETICS_API_TEST_PUBLIC_ID = environ["SYNTHETICS_API_TEST_PUBLIC_ID"]

body = SyntheticsTriggerBody(
    tests=[
        SyntheticsTriggerTest(
            public_id=SYNTHETICS_API_TEST_PUBLIC_ID,
        ),
    ],
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = SyntheticsApi(api_client)
    response = api_instance.trigger_tests(body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# Trigger Synthetic tests returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V1::SyntheticsAPI.new

# there is a valid "synthetics_api_test" in the system
SYNTHETICS_API_TEST_PUBLIC_ID = ENV["SYNTHETICS_API_TEST_PUBLIC_ID"]

body = DatadogAPIClient::V1::SyntheticsTriggerBody.new({
  tests: [
    DatadogAPIClient::V1::SyntheticsTriggerTest.new({
      public_id: SYNTHETICS_API_TEST_PUBLIC_ID,
    }),
  ],
})
p api_instance.trigger_tests(body)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// Trigger Synthetic tests returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV1::api_synthetics::SyntheticsAPI;
use datadog_api_client::datadogV1::model::SyntheticsTriggerBody;
use datadog_api_client::datadogV1::model::SyntheticsTriggerTest;

#[tokio::main]
async fn main() {
    // there is a valid "synthetics_api_test" in the system
    let synthetics_api_test_public_id = std::env::var("SYNTHETICS_API_TEST_PUBLIC_ID").unwrap();
    let body = SyntheticsTriggerBody::new(vec![SyntheticsTriggerTest::new(
        synthetics_api_test_public_id.clone(),
    )]);
    let configuration = datadog::Configuration::new();
    let api = SyntheticsAPI::with_config(configuration);
    let resp = api.trigger_tests(body).await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * Trigger Synthetic tests returns "OK" response
 */

import { client, v1 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v1.SyntheticsApi(configuration);

// there is a valid "synthetics_api_test" in the system
const SYNTHETICS_API_TEST_PUBLIC_ID = process.env
  .SYNTHETICS_API_TEST_PUBLIC_ID as string;

const params: v1.SyntheticsApiTriggerTestsRequest = {
  body: {
    tests: [
      {
        publicId: SYNTHETICS_API_TEST_PUBLIC_ID,
      },
    ],
  },
};

apiInstance
  .triggerTests(params)
  .then((data: v1.SyntheticsTriggerCITestsResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"