Sign in

v1

latestOpenAPI 3.0.0Apache 2.0 License2026-07-1430232150.8 KB

Retrieves IDs and annotations for traces available for a specified time frame using an optional filter. To get the full traces, pass the trace IDs to BatchGetTraces.

A filter expression can target traced requests that hit specific service nodes or edges, have errors, or come from a known user. For example, the following filter expression targets traces that pass through api.example.com:

service("api.example.com")

This filter expression finds traces that have an annotation named account with the value 12345:

annotation.account = "12345"

For a full list of indexed fields and keywords that you can use in filter expressions, see Using Filter Expressions in the Amazon Web Services X-Ray Developer Guide.

post/TraceSummaries

Query parameters

NextTokenstring

Pagination token

Request body

StartTimestring date-time required

The start of the time frame for which to retrieve traces.

EndTimestring date-time required

The end of the time frame for which to retrieve traces.

TimeRangeType'TraceId' | 'Event'

A parameter to indicate whether to query trace summaries by TraceId or Event time.

Samplingboolean

Set to <code>true</code> to get summaries for only a subset of available traces.

FilterExpressionstring

Specify a filter expression to retrieve trace summaries for services or requests that meet certain requirements.

NextTokenstring

Specify the pagination token returned by a previous request to retrieve the next page of results.

Response

Success

ApproximateTimestring date-time

The start time of this page of results.

TracesProcessedCountinteger

The total number of traces processed, including traces that did not match the specified filter expression.

NextTokenstring

If the requested time frame contained more than one page of results, you can use this token to retrieve the next page. The first page contains the most recent results, closest to the end of the time frame.