For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/apm-trace/get-a-pruned-trace-by-id.md. A documentation index is available at /llms.txt.
homeHomedocsDocsapiAPI
Language
Datadog site

Get a pruned trace by ID

WARNINGNote: This endpoint is in preview and is subject to change. If you have any feedback, contact Datadog support.
GEThttps://api.datadoghq.com/api/v2/pruned_trace/{trace_id}https://api.us3.datadoghq.com/api/v2/pruned_trace/{trace_id}https://api.us5.datadoghq.com/api/v2/pruned_trace/{trace_id}https://api.datadoghq.eu/api/v2/pruned_trace/{trace_id}https://api.ap1.datadoghq.com/api/v2/pruned_trace/{trace_id}https://api.ap2.datadoghq.com/api/v2/pruned_trace/{trace_id}https://api.uk1.datadoghq.com/api/v2/pruned_trace/{trace_id}https://api.ddog-gov.com/api/v2/pruned_trace/{trace_id}https://api.us2.ddog-gov.com/api/v2/pruned_trace/{trace_id}

Overview

Retrieve a pruned, hierarchical view of an APM trace by its trace ID. The trace is summarized as a tree of spans rooted at the trace root and reduced in size to keep rendering large traces in the UI practical. A 400 Bad Request response means the trace ID is malformed. A 404 Not Found response means no trace with this ID is available, such as when the trace is outside the retention period. This endpoint is rate limited to 60 requests per minute per organization.

This endpoint requires the apm_read permission.

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

Arguments

Path Parameters

Name
Type
Description
trace_id [required]
string

The trace ID. Accepts either a hexadecimal string of up to 32 characters (128-bit trace ID) or a decimal string of up to 39 digits. Hexadecimal IDs are case-insensitive, and shorter values are left-padded with zeros. Use the trace_id attribute of a span returned by the Search spans or Get a list of spans endpoints. Values in any other format, such as UUIDs, return 400 Bad Request. A well-formed ID with no matching trace returns 404 Not Found.

Query Strings

Name
Type
Description
expand_span_id
integer

Span ID to expand and preserve in the pruned tree even when its branch would normally be summarized.

time_hint
integer

Optional Unix time hint, in seconds, used to optimize the lookup of the trace in long-term storage.

force_source
string

Force the trace to be loaded from a specific source. When unset, the API picks the source automatically.

include_path
array

Restrict the pruned tree to spans matching the given key:value pairs. Values may be passed as repeated query parameters.

tag_include
array

Regex patterns of tag keys whose values must be included in the pruned spans. Values may be passed as repeated query parameters.

tag_exclude
array

Regex patterns of tag keys whose values must be excluded from the pruned spans. Values may be passed as repeated query parameters.

only_service_entry_spans
boolean

When set to true, only service entry spans are included in the pruned tree.

Response

OK

Response containing a single pruned trace.

Field
Type
Description
data [required]
object

A pruned trace resource document.

Code Example

Get a pruned trace by ID
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"
# Path parameters
export trace_id="0000000000000000abc1230000000000"

# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X GET "https://api.${DD_SITE}/api/v2/pruned_trace/${trace_id}" \
-H "Accept: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}"