API testing template variables

Test type

Variables

Overview

Template variables allow you to insert dynamic values from your test results and configuration into Synthetic Monitoring notification messages for API tests. These variables are accessed using the synthetics.attributes prefix.

Use the filters above to view variables by protocol type and variable category.

This section covers three categories of variables:

HTTP Protocol Variables

    synthetics.attributes.variables.extracted.request
    Information about the request
    synthetics.attributes.variables.extracted.request.method
    The HTTP method
    synthetics.attributes.variables.extracted.request.body
    The request body if set
    synthetics.attributes.variables.extracted.request.headers
    The request headers
    synthetics.attributes.variables.extracted.response
    Information about the response
    synthetics.attributes.variables.extracted.response.body
    The response body as string (truncated if too big)
    synthetics.attributes.variables.extracted.response.bodySize
    The size of the full response body
    synthetics.attributes.variables.extracted.response.cacheHeaders
    A dictionary of caching-related headers
    synthetics.attributes.variables.extracted.response.cdn
    The response CDN info if any
    synthetics.attributes.variables.extracted.response.cdn.provider
    The CDN provider name (for example, akamai, cloudflare)
    synthetics.attributes.variables.extracted.response.cdn.cache
    The cache info
    synthetics.attributes.variables.extracted.response.cdn.cache.cached
    If the data was cached
    synthetics.attributes.variables.extracted.response.cdn.cache.status
    The cache status as provided in associated cache header
    synthetics.attributes.variables.extracted.response.headers
    The response headers
    synthetics.attributes.variables.extracted.response.httpVersion
    The HTTP version
    synthetics.attributes.variables.extracted.response.redirects
    A list of redirections if any
    synthetics.attributes.variables.extracted.response.redirects.statusCode
    The HTTP status code for the redirect
    synthetics.attributes.variables.extracted.response.redirects.location
    The returned location to redirect to
    synthetics.attributes.variables.extracted.response.statusCode
    The response HTTP status code
    synthetics.attributes.variables.extracted.timings.authentication
    The time spent for the authentication challenge (for example, NTLM)
    synthetics.attributes.variables.extracted.timings.download
    The time spent downloading the response
    synthetics.attributes.variables.extracted.timings.firstByte
    The time spent waiting for the first byte of response to be received
    synthetics.attributes.variables.extracted.timings.redirect
    The time spent in HTTP redirections
    synthetics.attributes.variables.extracted.timings.ssl
    The duration of the TLS handshake (only when testing an HTTPS endpoint)

    DNS Protocol Variables

    synthetics.attributes.variables.extracted.response.records.type
    DNS record type
    synthetics.attributes.variables.extracted.response.records.values
    DNS record values

    SSL Protocol Variables

      synthetics.attributes.variables.extracted.cert
      SSL certificate information
      synthetics.attributes.variables.extracted.cert.cipher
      Cipher suite used (for example, TLS_AES_128_GCM_SHA256)
      synthetics.attributes.variables.extracted.cert.extKeyUsage
      Extended key usage data
      synthetics.attributes.variables.extracted.cert.fingerprint
      SHA-1 digest of the DER encoded certificate
      synthetics.attributes.variables.extracted.cert.fingerprint256
      SHA-256 digest of the DER encoded certificate
      synthetics.attributes.variables.extracted.cert.issuer
      Information about the certificate authority that signed the certificate
      synthetics.attributes.variables.extracted.cert.issuer.C
      Country code
      synthetics.attributes.variables.extracted.cert.issuer.ST
      Street
      synthetics.attributes.variables.extracted.cert.issuer.L
      Locality
      synthetics.attributes.variables.extracted.cert.issuer.O
      Organization
      synthetics.attributes.variables.extracted.cert.issuer.OU
      Organizational unit
      synthetics.attributes.variables.extracted.cert.issuer.CN
      Common name
      synthetics.attributes.variables.extracted.cert.subject
      Information about the certificate subject (same fields as issuer)
      synthetics.attributes.variables.extracted.cert.subject.altName
      All domains for which the certificate is valid (Subject Alternative Name)
      synthetics.attributes.variables.extracted.cert.protocol
      SSL/TLS protocol version
      synthetics.attributes.variables.extracted.cert.serialNumber
      Certificate serial number
      synthetics.attributes.variables.extracted.cert.tlsVersion
      TLS version parsed from protocol, if available
      synthetics.attributes.variables.extracted.cert.valid.from
      Certificate validity start date (millisecond-based epoch)
      synthetics.attributes.variables.extracted.cert.valid.to
      Certificate validity end date (millisecond-based epoch)
      synthetics.attributes.variables.extracted.cert.exponent
      RSA key exponent (for RSA keys)
      synthetics.attributes.variables.extracted.cert.modulus
      RSA key modulus as a hexadecimal string (for RSA keys)
      synthetics.attributes.variables.extracted.ocsp
      OCSP (Online Certificate Status Protocol) information
      synthetics.attributes.variables.extracted.timings.handshake
      SSL handshake timing

      WebSocket Protocol Variables

        synthetics.attributes.variables.extracted.timings.open
        Time to open connection (in milliseconds)
        synthetics.attributes.variables.extracted.timings.receive
        Time to receive response
        synthetics.attributes.variables.extracted.handshake.request
        Handshake request data
        synthetics.attributes.variables.extracted.handshake.request.headers
        Headers sent during the handshake
        synthetics.attributes.variables.extracted.handshake.response
        Handshake response data
        synthetics.attributes.variables.extracted.handshake.response.headers
        Headers received during the handshake
        synthetics.attributes.variables.extracted.handshake.response.statusCode
        HTTP status code of the handshake response
        synthetics.attributes.variables.extracted.request.message
        WebSocket request message
        synthetics.attributes.variables.extracted.response.message
        WebSocket response message
        synthetics.attributes.variables.extracted.close.reason
        Connection close reason
        synthetics.attributes.variables.extracted.close.statusCode
        Connection close status code

        UDP Protocol Variables

          synthetics.attributes.variables.extracted.request.message
          UDP request message
          synthetics.attributes.variables.extracted.response.message
          UDP response message
          synthetics.attributes.variables.extracted.timings.message
          Message timing

          TCP Protocol Variables

            synthetics.attributes.variables.extracted.connectionOutcome
            Connection result (established, refused, or timeout)
            synthetics.attributes.variables.extracted.netpath.routers.ip
            Router IP addresses from network path data
            synthetics.attributes.variables.extracted.traceroute
            Traceroute hop data, available when Track number of network hops (TTL) is enabled in the test
            synthetics.attributes.variables.extracted.traceroute.routers.ip
            Router IP address for the hop
            synthetics.attributes.variables.extracted.traceroute.routers.resolvedHost
            Resolved hostname for the router IP, if available
            synthetics.attributes.variables.extracted.traceroute.packetsSent
            Number of network packets sent
            synthetics.attributes.variables.extracted.traceroute.packetsReceived
            Number of packets received
            synthetics.attributes.variables.extracted.traceroute.packetLossPercentage
            Ratio of packet loss (float between 0 and 1)
            synthetics.attributes.variables.extracted.traceroute.latency.min
            Minimum latency
            synthetics.attributes.variables.extracted.traceroute.latency.max
            Maximum latency
            synthetics.attributes.variables.extracted.traceroute.latency.avg
            Average latency
            synthetics.attributes.variables.extracted.traceroute.latency.stddev
            Standard deviation
            synthetics.attributes.variables.extracted.traceroute.latency.values
            Latency values array

            ICMP Protocol Variables

              synthetics.attributes.variables.extracted.traceroute
              Traceroute data (same structure as TCP traceroute)
              synthetics.attributes.variables.extracted.request.host
              Target host
              synthetics.attributes.variables.extracted.ping
              Ping result data
              synthetics.attributes.variables.extracted.ping.packetsSent
              Number of network packets sent
              synthetics.attributes.variables.extracted.ping.packetsReceived
              Number of packets received
              synthetics.attributes.variables.extracted.ping.packetLossPercentage
              Ratio of packet loss (float between 0 and 1)
              synthetics.attributes.variables.extracted.ping.packetSize
              Packet size
              synthetics.attributes.variables.extracted.ping.resolvedIP
              Resolved IP address of the pinged host
              synthetics.attributes.variables.extracted.ping.latency.min
              Minimum latency
              synthetics.attributes.variables.extracted.ping.latency.max
              Maximum latency
              synthetics.attributes.variables.extracted.ping.latency.avg
              Average latency
              synthetics.attributes.variables.extracted.ping.latency.stddev
              Standard deviation
              synthetics.attributes.variables.extracted.ping.latency.values
              Latency values array

              gRPC Protocol Variables

              synthetics.attributes.variables.extracted.callType
              Call type (unary or healthcheck)
              synthetics.attributes.variables.extracted.timings.rpc
              RPC call timing
                synthetics.attributes.variables.extracted.response.healthcheck.status
                Health check status (UNKNOWN = 0, SERVING = 1, NOT_SERVING = 2, SERVICE_UNKNOWN = 3)
                synthetics.attributes.variables.extracted.response.healthcheck.message.service
                Name of the called service, if provided
                synthetics.attributes.variables.extracted.response.metadata
                Dictionary of gRPC response metadata
                synthetics.attributes.variables.extracted.request.message
                gRPC request message
                synthetics.attributes.variables.extracted.request.service
                The called service
                synthetics.attributes.variables.extracted.response.message
                gRPC response message (as JSON string)
                synthetics.attributes.variables.extracted.response.metadata
                Dictionary of gRPC response metadata

                Common Variables

                These variables are available for all API test protocols.

                  synthetics.attributes.variables.extracted.assertions
                  List of configured assertions for the test
                  synthetics.attributes.variables.extracted.assertions.actual
                  The evaluated value of the assertion
                  synthetics.attributes.variables.extracted.assertions.expected
                  The expected value configured for the assertion (for example, 1000)
                  synthetics.attributes.variables.extracted.assertions.operator
                  The assertion operator (for example, lessThan)
                  synthetics.attributes.variables.extracted.assertions.type
                  The assertion type (for example, responseTime)
                  synthetics.attributes.variables.extracted.assertions.valid
                  Whether the assertion passed (boolean)
                  synthetics.attributes.variables.extracted.dnsResolution.resolvedIp
                  The IP address called for the test (available when testing a domain rather than an IP)
                  synthetics.attributes.variables.extracted.dnsResolution.server
                  The DNS server used for resolution
                  synthetics.attributes.variables.extracted.timings.total
                  Total time of the test in milliseconds (same as result.duration)
                  synthetics.attributes.variables.extracted.timings.dns
                  Duration of the DNS lookup in milliseconds (available when testing a domain rather than an IP)
                  synthetics.attributes.variables.extracted.timings.tcp
                  Time to establish the TCP connection in milliseconds (HTTP, TCP, SSL, and WebSocket subtypes)

                  Execution results

                  Path: synthetics.attributes

                  Use these variables to access test execution results, status, duration, and step counts.

                    {{synthetics.attributes.result}}
                    The result object contains information about the executed test run
                    {{synthetics.attributes.result.id}}
                    Unique result ID
                    {{synthetics.attributes.result.status}}
                    Test execution status (for example, passed or failed)
                    {{synthetics.attributes.result.duration}}
                    Test duration in milliseconds
                    {{synthetics.attributes.result.testStartedAt}}, {{synthetics.attributes.result.testFinishedAt}}, {{synthetics.attributes.result.testTriggeredAt}}
                    Epoch timestamps in milliseconds
                    {{synthetics.attributes.result.failure}}
                    The failure object contains information about why the test failed
                    {{synthetics.attributes.result.failure.message}}
                    The failure message
                    {{synthetics.attributes.result.failure.code}}
                    The failure code

                    For a complete list of API test error codes, see API Testing Errors. Review the conditional alerting page for an example of how to use the synthetics.attributes.result.failure variable in a notification.

                    {{synthetics.attributes.count}}
                    The count object contains step statistics about the test
                    {{synthetics.attributes.count.steps.total}}
                    The total number of steps
                    {{synthetics.attributes.count.steps.completed}}
                    The number of steps that were run
                    {{synthetics.attributes.count.errors}}
                    The total number of errors that occurred while running the test. For multistep and mobile tests, this is the number of failed steps. For browser tests, this is the sum of all browser errors.
                    {{synthetics.attributes.count.hops}}
                    The number of traceroute hops for TCP and ICMP tests

                    Test metadata

                    Path: synthetics.attributes

                    Use these variables to access test configuration and execution location information.

                      {{synthetics.attributes.test}}
                      The test object contains information about the test like its name, type, subtype, and id
                      {{synthetics.attributes.test.name}}
                      The name of the test
                      {{synthetics.attributes.test.type}}
                      Test type (for example, api)
                      {{synthetics.attributes.test.subType}}
                      Subtype for API tests (for example, http, dns, and multi)
                      {{synthetics.attributes.test.id}}
                      The test's public ID (for example, abc-def-ghi)
                      {{synthetics.attributes.location}}
                      The location object contains information about the location of where the test is run from
                      {{synthetics.attributes.location.id}}
                      Location ID (for example, aws:eu-central-1)
                      {{synthetics.attributes.location.name}}
                      Name of the location (for example, Frankfurt (AWS))
                      {{synthetics.attributes.location.privateLocation}}
                      true for Private Locations

                      Extracted variables

                      Path: synthetics.attributes.variables.extracted

                      These are step execution metadata and results containing detailed information about how each step ran, including response data, timing metrics, and protocol-specific details. These values are only available for successful test results and can only be used in Recovery notifications.

                      General step properties:

                      synthetics.attributes.variables.extracted.steps.allowFailure
                      Whether the step is allowed to fail without failing the entire test
                      synthetics.attributes.variables.extracted.steps.duration
                      Step execution duration in milliseconds
                      synthetics.attributes.variables.extracted.steps.failure
                      Failure information object containing .code and .message
                      synthetics.attributes.variables.extracted.steps.id
                      Unique step identifier
                      synthetics.attributes.variables.extracted.steps.isCritical
                      Whether the step is critical to the test
                      synthetics.attributes.variables.extracted.steps.status
                      Step execution status
                      synthetics.attributes.variables.extracted.steps.type
                      Type of step being executed

                      Step summary

                      Path: synthetics.attributes.result.steps

                      Access step data by index, name, or ID to reference specific steps in your notification messages. Use these reference methods when working with step-related variables throughout this documentation.

                      Each step exposes the following properties: .id, .status, .type, .duration, .description, .failure.message, .code, and .url.

                      You can reference steps in three ways:

                        Use positive numbers to count from the beginning, or negative numbers to count from the end:

                        synthetics.attributes.result.steps.0
                        First step
                        synthetics.attributes.result.steps.1
                        Second step
                        synthetics.attributes.result.steps.-1
                        Last step
                        synthetics.attributes.result.steps.-2
                        Second to last step

                        Example: {{synthetics.attributes.result.steps.-1.status}} returns the status of the last step.

                        Use the step name in brackets:

                        synthetics.attributes.result.steps[Click button]
                        References the step named "Click button"

                        Example: {{synthetics.attributes.result.steps[Click button].status}} returns the status of the step named "Click button".

                        Use the step's unique identifier:

                        synthetics.attributes.result.steps.abc-def-ghi
                        References the step with ID "abc-def-ghi"

                        Example: {{synthetics.attributes.result.steps.abc-def-ghi.status}} returns the status of the step with step ID "abc-def-ghi".

                        Review the conditional alerting page for an example of how to use the synthetics.attributes.result.step variable in a Slack notification based on a failed step.

                        Accessing step properties

                        Combine any reference method with a property:

                        • {{synthetics.attributes.result.steps.-1.status}} - Status of the last step
                        • {{synthetics.attributes.result.steps[Click button].status}} - Status of the step named "Click button"
                        • {{synthetics.attributes.result.steps.abc-def-ghi.status}} - Status of the step with step ID "abc-def-ghi"

                        Local & Global Variables

                        Use these variables to access locally configured variables and globally defined variables in your notifications.

                          Path: synthetics.attributes.result.variables.config

                          These are local variables configured for API tests or defined outside individual steps in step-based tests. This also includes variables created by JavaScript code execution.

                          {{synthetics.attributes.result.variables.config.name}}
                          Variable name
                          {{synthetics.attributes.result.variables.config.type}}
                          Variable type
                          {{synthetics.attributes.result.variables.config.secure}}
                          Whether the variable value is obfuscated
                          {{synthetics.attributes.result.variables.config.value}}
                          Variable value (non-obfuscated only)

                          Path: synthetics.attributes.result.variables.extracted

                          These are extracted variables whose value updates a global variable value.

                          Available only for successful test results and recovery notifications.

                          {{synthetics.attributes.result.variables.extracted.id}}
                          Global variable ID
                          {{synthetics.attributes.result.variables.extracted.name}}
                          Variable name
                          {{synthetics.attributes.result.variables.extracted.secure}}
                          Whether the variable value is obfuscated
                          {{synthetics.attributes.result.variables.extracted.val}}
                          Variable value (note: uses .val, not .value)

                          Review the advanced notifications page for an example of how to use local variables in a notification.

                          Further reading

                          Additional helpful documentation, links, and articles: