--- title: Trigger tests from CI/CD pipelines description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Synthetics --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Trigger tests from CI/CD pipelines{% #trigger-tests-from-cicd-pipelines %} {% tab title="v1" %} | Datadog site | API endpoint | | ----------------- | --------------------------------------------------------------------- | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v1/synthetics/tests/trigger/ci | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v1/synthetics/tests/trigger/ci | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v1/synthetics/tests/trigger/ci | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v1/synthetics/tests/trigger/ci | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v1/synthetics/tests/trigger/ci | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v1/synthetics/tests/trigger/ci | | app.datadoghq.com | POST https://api.datadoghq.com/api/v1/synthetics/tests/trigger/ci | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v1/synthetics/tests/trigger/ci | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v1/synthetics/tests/trigger/ci | ### Overview Trigger a set of Synthetic tests for continuous integration. This endpoint requires the `synthetics_write` permission. OAuth apps require the `synthetics_write` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#synthetics) to access this endpoint. ### Request #### Body Data (required) Details of the test to trigger. {% tab title="Model" %} | Parent field | Field | Type | Description | | -------------------- | ---------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | | tests | [object] | List of Synthetic tests with overrides. | | tests | allowInsecureCertificates | boolean | Disable certificate checks in API tests. | | tests | basicAuth | | Object to handle basic authentication when performing the test. | | basicAuth | | object | Object to handle basic authentication when performing the test. | | | password | string | Password to use for the basic authentication. | | | type | enum | The type of basic authentication to use when performing the test. Allowed enum values: `web` | | | username | string | Username to use for the basic authentication. | | basicAuth | | object | Object to handle `SIGV4` authentication when performing the test. | | | accessKey [*required*] | string | Access key for the `SIGV4` authentication. | | | region | string | Region for the `SIGV4` authentication. | | | secretKey [*required*] | string | Secret key for the `SIGV4` authentication. | | | serviceName | string | Service name for the `SIGV4` authentication. | | | sessionToken | string | Session token for the `SIGV4` authentication. | | | type [*required*] | enum | The type of authentication to use when performing the test. Allowed enum values: `sigv4` | | basicAuth | | object | Object to handle `NTLM` authentication when performing the test. | | | domain | string | Domain for the authentication to use when performing the test. | | | password | string | Password for the authentication to use when performing the test. | | | type [*required*] | enum | The type of authentication to use when performing the test. Allowed enum values: `ntlm` | | | username | string | Username for the authentication to use when performing the test. | | | workstation | string | Workstation for the authentication to use when performing the test. | | basicAuth | | object | Object to handle digest authentication when performing the test. | | | password [*required*] | string | Password to use for the digest authentication. | | | type [*required*] | enum | The type of basic authentication to use when performing the test. Allowed enum values: `digest` | | | username [*required*] | string | Username to use for the digest authentication. | | basicAuth | | object | Object to handle `oauth client` authentication when performing the test. | | | accessTokenUrl [*required*] | string | Access token URL to use when performing the authentication. | | | audience | string | Audience to use when performing the authentication. | | | clientId [*required*] | string | Client ID to use when performing the authentication. | | | clientSecret [*required*] | string | Client secret to use when performing the authentication. | | | resource | string | Resource to use when performing the authentication. | | | scope | string | Scope to use when performing the authentication. | | | tokenApiAuthentication [*required*] | enum | Type of token to use when performing the authentication. Allowed enum values: `header,body` | | | type [*required*] | enum | The type of basic authentication to use when performing the test. Allowed enum values: `oauth-client` | | basicAuth | | object | Object to handle `oauth rop` authentication when performing the test. | | | accessTokenUrl [*required*] | string | Access token URL to use when performing the authentication. | | | audience | string | Audience to use when performing the authentication. | | | clientId | string | Client ID to use when performing the authentication. | | | clientSecret | string | Client secret to use when performing the authentication. | | | password [*required*] | string | Password to use when performing the authentication. | | | resource | string | Resource to use when performing the authentication. | | | scope | string | Scope to use when performing the authentication. | | | tokenApiAuthentication [*required*] | enum | Type of token to use when performing the authentication. Allowed enum values: `header,body` | | | type [*required*] | enum | The type of basic authentication to use when performing the test. Allowed enum values: `oauth-rop` | | | username [*required*] | string | Username to use when performing the authentication. | | basicAuth | | object | Object to handle JWT authentication when performing the test. | | | addClaims | object | Standard JWT claims to automatically inject. | | addClaims | exp | boolean | Whether to inject the `exp` (expiration) claim. | | addClaims | iat | boolean | Whether to inject the `iat` (issued at) claim. | | | algorithm [*required*] | enum | Algorithm to use for the JWT authentication. Allowed enum values: `HS256,RS256,ES256` | | | expiresIn | int64 | Token time-to-live in seconds. | | | header | string | Custom JWT header as a JSON string. | | | payload [*required*] | string | JWT claims as a JSON string. | | | secret [*required*] | string | Signing key for the JWT authentication. Use the shared secret for `HS256` or the private key (PEM format) for `RS256` and `ES256`. | | | tokenPrefix | string | Prefix added before the token in the `Authorization` header. Defaults to `Bearer`. | | | type [*required*] | enum | The type of authentication to use when performing the test. Allowed enum values: `jwt` | | tests | body | string | Body to include in the test. | | tests | bodyType | string | Type of the data sent in a Synthetic API test. | | tests | cookies | string | Cookies for the request. | | tests | deviceIds | [string] | For browser test, array with the different device IDs used to run the test. | | tests | followRedirects | boolean | For API HTTP test, whether or not the test should follow redirects. | | tests | headers | object | Headers to include when performing the test. | | additionalProperties | | string | A single Header. | | tests | locations | [string] | Array of locations used to run the test. | | tests | metadata | object | Metadata for the Synthetic tests run. | | metadata | ci | object | Description of the CI provider. | | ci | pipeline | object | Description of the CI pipeline. | | pipeline | url | string | URL of the pipeline. | | ci | provider | object | Description of the CI provider. | | provider | name | string | Name of the CI provider. | | metadata | git | object | Git information. | | git | branch | string | Branch name. | | git | commitSha | string | The commit SHA. | | tests | public_id [*required*] | string | The public ID of the Synthetic test to trigger. | | tests | retry | object | Object describing the retry strategy to apply to a Synthetic test. | | retry | count | int64 | Number of times a test needs to be retried before marking a location as failed. Defaults to 0. | | retry | interval | double | Time interval between retries (in milliseconds). Defaults to 300ms. | | tests | startUrl | string | Starting URL for the browser test. | | tests | variables | object | Variables to replace in the test. | | additionalProperties | | string | A single variable. | | tests | version | int64 | The version number of the Synthetic test version to trigger. | {% /tab %} {% tab title="Example" %} ```json { "tests": [ { "allowInsecureCertificates": false, "basicAuth": { "password": "PaSSw0RD!", "type": "web", "username": "my_username" }, "body": "string", "bodyType": "string", "cookies": "string", "deviceIds": [ "chrome.laptop_large" ], "followRedirects": false, "headers": { "": "string" }, "locations": [ "aws:eu-west-3" ], "metadata": { "ci": { "pipeline": { "url": "string" }, "provider": { "name": "string" } }, "git": { "branch": "string", "commitSha": "string" } }, "public_id": "aaa-aaa-aaa", "retry": { "count": "integer", "interval": "number" }, "startUrl": "string", "variables": { "": "string" }, "version": "integer" } ] } ``` {% /tab %} ### Response {% tab title="200" %} OK {% tab title="Model" %} Object containing information about the tests triggered. | Parent field | Field | Type | Description | | ------------ | ------------------- | -------- | ----------------------------------------------- | | | batch_id | string | The public ID of the batch triggered. | | | locations | [object] | List of Synthetic locations. | | locations | id | int64 | Unique identifier of the location. | | locations | name | string | Name of the location. | | | results | [object] | Information about the tests runs. | | results | device | string | The device ID. | | results | location | int64 | The location ID of the test run. | | results | public_id | string | The public ID of the Synthetic test. | | results | result_id | string | ID of the result. | | | triggered_check_ids | [string] | The public IDs of the Synthetic test triggered. | {% /tab %} {% tab title="Example" %} ```json { "batch_id": "string", "locations": [ { "id": "integer", "name": "string" } ], "results": [ { "device": "chrome.laptop_large", "location": "integer", "public_id": "string", "result_id": "string" } ], "triggered_check_ids": [] } ``` {% /tab %} {% /tab %} {% tab title="400" %} JSON format is wrong {% tab title="Model" %} Error response object. | Field | Type | Description | | ------------------------ | -------- | ------------------------------------ | | errors [*required*] | [string] | Array of errors returned by the API. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} Error response object. | Field | Type | Description | | ------------------------ | -------- | ------------------------------------ | | errors [*required*] | [string] | Array of errors returned by the API. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \## default # \# Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" \# Curl command curl -X POST "https://api.datadoghq.com/api/v1/synthetics/tests/trigger/ci" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "tests": [ { "public_id": "aaa-aaa-aaa" } ] } EOF ##### ```python """ Trigger tests from CI/CD pipelines 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_basic_auth_web import SyntheticsBasicAuthWeb from datadog_api_client.v1.model.synthetics_basic_auth_web_type import SyntheticsBasicAuthWebType from datadog_api_client.v1.model.synthetics_ci_batch_metadata import SyntheticsCIBatchMetadata from datadog_api_client.v1.model.synthetics_ci_batch_metadata_ci import SyntheticsCIBatchMetadataCI from datadog_api_client.v1.model.synthetics_ci_batch_metadata_git import SyntheticsCIBatchMetadataGit from datadog_api_client.v1.model.synthetics_ci_batch_metadata_pipeline import SyntheticsCIBatchMetadataPipeline from datadog_api_client.v1.model.synthetics_ci_batch_metadata_provider import SyntheticsCIBatchMetadataProvider from datadog_api_client.v1.model.synthetics_ci_test import SyntheticsCITest from datadog_api_client.v1.model.synthetics_ci_test_body import SyntheticsCITestBody from datadog_api_client.v1.model.synthetics_test_options_retry import SyntheticsTestOptionsRetry body = SyntheticsCITestBody( tests=[ SyntheticsCITest( basic_auth=SyntheticsBasicAuthWeb( password="PaSSw0RD!", type=SyntheticsBasicAuthWebType.WEB, username="my_username", ), device_ids=[ "chrome.laptop_large", ], locations=[ "aws:eu-west-3", ], metadata=SyntheticsCIBatchMetadata( ci=SyntheticsCIBatchMetadataCI( pipeline=SyntheticsCIBatchMetadataPipeline(), provider=SyntheticsCIBatchMetadataProvider(), ), git=SyntheticsCIBatchMetadataGit(), ), public_id="aaa-aaa-aaa", retry=SyntheticsTestOptionsRetry(), ), ], ) configuration = Configuration() configuration.access_token = environ["DD_BEARER_TOKEN"] with ApiClient(configuration) as api_client: api_instance = SyntheticsApi(api_client) response = api_instance.trigger_ci_tests(body=body) print(response) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" python3 "example.py" ##### ```ruby # Trigger tests from CI/CD pipelines returns "OK" response require "datadog_api_client" DatadogAPIClient.configure do |config| config.access_token = ENV["DD_BEARER_TOKEN"] end api_instance = DatadogAPIClient::V1::SyntheticsAPI.new body = DatadogAPIClient::V1::SyntheticsCITestBody.new({ tests: [ DatadogAPIClient::V1::SyntheticsCITest.new({ basic_auth: DatadogAPIClient::V1::SyntheticsBasicAuthWeb.new({ password: "PaSSw0RD!", type: DatadogAPIClient::V1::SyntheticsBasicAuthWebType::WEB, username: "my_username", }), device_ids: [ "chrome.laptop_large", ], locations: [ "aws:eu-west-3", ], metadata: DatadogAPIClient::V1::SyntheticsCIBatchMetadata.new({ ci: DatadogAPIClient::V1::SyntheticsCIBatchMetadataCI.new({ pipeline: DatadogAPIClient::V1::SyntheticsCIBatchMetadataPipeline.new({}), provider: DatadogAPIClient::V1::SyntheticsCIBatchMetadataProvider.new({}), }), git: DatadogAPIClient::V1::SyntheticsCIBatchMetadataGit.new({}), }), public_id: "aaa-aaa-aaa", _retry: DatadogAPIClient::V1::SyntheticsTestOptionsRetry.new({}), }), ], }) p api_instance.trigger_ci_tests(body) ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" rb "example.rb" ##### ```go // Trigger tests from CI/CD pipelines 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() { body := datadogV1.SyntheticsCITestBody{ Tests: []datadogV1.SyntheticsCITest{ { BasicAuth: &datadogV1.SyntheticsBasicAuth{ SyntheticsBasicAuthWeb: &datadogV1.SyntheticsBasicAuthWeb{ Password: datadog.PtrString("PaSSw0RD!"), Type: datadogV1.SYNTHETICSBASICAUTHWEBTYPE_WEB.Ptr(), Username: datadog.PtrString("my_username"), }}, DeviceIds: []string{ "chrome.laptop_large", }, Locations: []string{ "aws:eu-west-3", }, Metadata: &datadogV1.SyntheticsCIBatchMetadata{ Ci: &datadogV1.SyntheticsCIBatchMetadataCI{ Pipeline: &datadogV1.SyntheticsCIBatchMetadataPipeline{}, Provider: &datadogV1.SyntheticsCIBatchMetadataProvider{}, }, Git: &datadogV1.SyntheticsCIBatchMetadataGit{}, }, PublicId: "aaa-aaa-aaa", Retry: &datadogV1.SyntheticsTestOptionsRetry{}, }, }, } ctx := datadog.NewDefaultContext(context.Background()) ctx = context.WithValue(ctx, datadog.ContextAccessToken, os.Getenv("DD_BEARER_TOKEN")) configuration := datadog.NewConfiguration() apiClient := datadog.NewAPIClient(configuration) api := datadogV1.NewSyntheticsApi(apiClient) resp, r, err := api.TriggerCITests(ctx, body) if err != nil { fmt.Fprintf(os.Stderr, "Error when calling `SyntheticsApi.TriggerCITests`: %v\n", err) fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) } responseContent, _ := json.MarshalIndent(resp, "", " ") fmt.Fprintf(os.Stdout, "Response from `SyntheticsApi.TriggerCITests`:\n%s\n", responseContent) } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" go run "main.go" ##### ```java // Trigger tests from CI/CD pipelines 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.SyntheticsBasicAuth; import com.datadog.api.client.v1.model.SyntheticsBasicAuthWeb; import com.datadog.api.client.v1.model.SyntheticsBasicAuthWebType; import com.datadog.api.client.v1.model.SyntheticsCIBatchMetadata; import com.datadog.api.client.v1.model.SyntheticsCIBatchMetadataCI; import com.datadog.api.client.v1.model.SyntheticsCIBatchMetadataGit; import com.datadog.api.client.v1.model.SyntheticsCIBatchMetadataPipeline; import com.datadog.api.client.v1.model.SyntheticsCIBatchMetadataProvider; import com.datadog.api.client.v1.model.SyntheticsCITest; import com.datadog.api.client.v1.model.SyntheticsCITestBody; import com.datadog.api.client.v1.model.SyntheticsTestOptionsRetry; import com.datadog.api.client.v1.model.SyntheticsTriggerCITestsResponse; import java.util.Collections; public class Example { public static void main(String[] args) { ApiClient defaultClient = ApiClient.getDefaultApiClient(); defaultClient.setAccessToken(System.getenv("DD_BEARER_TOKEN")); SyntheticsApi apiInstance = new SyntheticsApi(defaultClient); SyntheticsCITestBody body = new SyntheticsCITestBody() .tests( Collections.singletonList( new SyntheticsCITest() .basicAuth( new SyntheticsBasicAuth( new SyntheticsBasicAuthWeb() .password("PaSSw0RD!") .type(SyntheticsBasicAuthWebType.WEB) .username("my_username"))) .deviceIds(Collections.singletonList("chrome.laptop_large")) .locations(Collections.singletonList("aws:eu-west-3")) .metadata( new SyntheticsCIBatchMetadata() .ci( new SyntheticsCIBatchMetadataCI() .pipeline(new SyntheticsCIBatchMetadataPipeline()) .provider(new SyntheticsCIBatchMetadataProvider())) .git(new SyntheticsCIBatchMetadataGit())) .publicId("aaa-aaa-aaa") .retry(new SyntheticsTestOptionsRetry()))); try { SyntheticsTriggerCITestsResponse result = apiInstance.triggerCITests(body); System.out.println(result); } catch (ApiException e) { System.err.println("Exception when calling SyntheticsApi#triggerCITests"); 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](https://docs.datadoghq.com/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" java "Example.java" ##### ```rust // Trigger tests from CI/CD pipelines returns "OK" response use datadog_api_client::datadog; use datadog_api_client::datadogV1::api_synthetics::SyntheticsAPI; use datadog_api_client::datadogV1::model::SyntheticsBasicAuth; use datadog_api_client::datadogV1::model::SyntheticsBasicAuthWeb; use datadog_api_client::datadogV1::model::SyntheticsBasicAuthWebType; use datadog_api_client::datadogV1::model::SyntheticsCIBatchMetadata; use datadog_api_client::datadogV1::model::SyntheticsCIBatchMetadataCI; use datadog_api_client::datadogV1::model::SyntheticsCIBatchMetadataGit; use datadog_api_client::datadogV1::model::SyntheticsCIBatchMetadataPipeline; use datadog_api_client::datadogV1::model::SyntheticsCIBatchMetadataProvider; use datadog_api_client::datadogV1::model::SyntheticsCITest; use datadog_api_client::datadogV1::model::SyntheticsCITestBody; use datadog_api_client::datadogV1::model::SyntheticsTestOptionsRetry; #[tokio::main] async fn main() { let body = SyntheticsCITestBody::new().tests(vec![SyntheticsCITest::new("aaa-aaa-aaa".to_string()) .basic_auth(SyntheticsBasicAuth::SyntheticsBasicAuthWeb(Box::new( SyntheticsBasicAuthWeb::new() .password("PaSSw0RD!".to_string()) .type_(SyntheticsBasicAuthWebType::WEB) .username("my_username".to_string()), ))) .device_ids(vec!["chrome.laptop_large".to_string()]) .locations(vec!["aws:eu-west-3".to_string()]) .metadata( SyntheticsCIBatchMetadata::new() .ci(SyntheticsCIBatchMetadataCI::new() .pipeline(SyntheticsCIBatchMetadataPipeline::new()) .provider(SyntheticsCIBatchMetadataProvider::new())) .git(SyntheticsCIBatchMetadataGit::new()), ) .retry(SyntheticsTestOptionsRetry::new())]); let configuration = datadog::Configuration::new(); let api = SyntheticsAPI::with_config(configuration); let resp = api.trigger_ci_tests(body).await; if let Ok(value) = resp { println!("{:#?}", value); } else { println!("{:#?}", resp.unwrap_err()); } } ``` #### Instructions First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands: DD_SITE="datadoghq.com" DD_API_KEY="" DD_APP_KEY="" cargo run ##### ```typescript /** * Trigger tests from CI/CD pipelines returns "OK" response */ import { client, v1 } from "@datadog/datadog-api-client"; const configuration = client.createConfiguration({ authMethods: { AuthZ: { accessToken: process.env.DD_BEARER_TOKEN as string, }, }, }); const apiInstance = new v1.SyntheticsApi(configuration); const params: v1.SyntheticsApiTriggerCITestsRequest = { body: { tests: [ { basicAuth: { password: "PaSSw0RD!", type: "web", username: "my_username", }, deviceIds: ["chrome.laptop_large"], locations: ["aws:eu-west-3"], metadata: { ci: { pipeline: {}, provider: {}, }, git: {}, }, publicId: "aaa-aaa-aaa", retry: {}, }, ], }, }; apiInstance .triggerCITests(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](https://docs.datadoghq.com/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands: DD_SITE="datadoghq.com" DD_BEARER_TOKEN="" tsc "example.ts" {% /tab %}