---
title: "POST /TraceSummaries"
method: POST
path: "/TraceSummaries"
---

# POST /TraceSummaries

`POST /TraceSummaries`

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](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html) in the _Amazon Web Services X-Ray Developer Guide_.

## Query parameters

- `NextToken` string

## Request body

- object
  - `StartTime` string, date-time, required — The start of the time frame for which to retrieve traces.
  - `EndTime` string, 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.
  - `Sampling` boolean — Set to <code>true</code> to get summaries for only a subset of available traces.
  - `SamplingStrategy` object — The name and value of a sampling rule to apply to a trace summary.
    - `Name` 'PartialScan' | 'FixedRate' — The name of a sampling rule.
    - `Value` number, double — The value of a sampling rule.
  - `FilterExpression` string — Specify a filter expression to retrieve trace summaries for services or requests that meet certain requirements.
  - `NextToken` string — Specify the pagination token returned by a previous request to retrieve the next page of results.

## Response `200`

Success

- GetTraceSummariesResult
  - `TraceSummaries` TraceSummary[] — Trace IDs and annotations for traces that were found in the specified time frame.
    - `Id` string — The unique identifier for the request that generated the trace's segments and subsegments.
    - `Duration` number, double — The length of time in seconds between the start time of the root segment and the end time of the last segment that completed.
    - `ResponseTime` number, double — The length of time in seconds between the start and end times of the root segment. If the service performs work asynchronously, the response time measures the time before the response is sent to the user, while the duration measures the amount of time before the last traced activity completes.
    - `HasFault` boolean — The root segment document has a 500 series error.
    - `HasError` boolean — The root segment document has a 400 series error.
    - `HasThrottle` boolean — One or more of the segment documents has a 429 throttling error.
    - `IsPartial` boolean — One or more of the segment documents is in progress.
    - `Http` object — Information about the HTTP request served by the trace.
      - `HttpURL` string — The request URL.
      - `HttpStatus` integer — The response status.
      - `HttpMethod` string — The request method.
      - `UserAgent` string — The request's user agent string.
      - `ClientIp` string — The IP address of the requestor.
    - `Annotations` object — Annotations from the trace's segment documents.
    - `Users` TraceUser[] — Users from the trace's segment documents.
      - `UserName` string — The user's name.
      - `ServiceIds` ServiceId[] — Services that the user's request hit.
        - `Name` string — <p/>
        - `Names` String[] — <p/>
        - `AccountId` string — <p/>
        - `Type` string — <p/>
    - `ServiceIds` ServiceId[] — Service IDs from the trace's segment documents.
      - `Name` string — <p/>
      - `Names` String[] — <p/>
      - `AccountId` string — <p/>
      - `Type` string — <p/>
    - `ResourceARNs` ResourceARNDetail[] — A list of resource ARNs for any resource corresponding to the trace segments.
      - `ARN` string — The ARN of a corresponding resource.
    - `InstanceIds` InstanceIdDetail[] — A list of EC2 instance IDs for any instance corresponding to the trace segments.
      - `Id` string — The ID of a corresponding EC2 instance.
    - `AvailabilityZones` AvailabilityZoneDetail[] — A list of Availability Zones for any zone corresponding to the trace segments.
      - `Name` string — The name of a corresponding Availability Zone.
    - `EntryPoint` object — The root of a trace.
      - `Name` string — <p/>
      - `Names` String[] — <p/>
      - `AccountId` string — <p/>
      - `Type` string — <p/>
    - `FaultRootCauses` FaultRootCause[] — A collection of FaultRootCause structures corresponding to the trace segments.
      - `Services` FaultRootCauseService[] — A list of corresponding services. A service identifies a segment and it contains a name, account ID, type, and inferred flag.
        - `Name` string — The service name.
        - `Names` String[] — A collection of associated service names.
        - `Type` string — The type associated to the service.
        - `AccountId` string — The account ID associated to the service.
        - `EntityPath` FaultRootCauseEntity[] — The path of root cause entities found on the service.
          - `Name` string — The name of the entity.
          - `Exceptions` RootCauseException[] — The types and messages of the exceptions.
            - `Name` string — The name of the exception.
            - `Message` string — The message of the exception.
          - `Remote` boolean — A flag that denotes a remote subsegment.
        - `Inferred` boolean — A Boolean value indicating if the service is inferred from the trace.
      - `ClientImpacting` boolean — A flag that denotes that the root cause impacts the trace client.
    - `ErrorRootCauses` ErrorRootCause[] — A collection of ErrorRootCause structures corresponding to the trace segments.
      - `Services` ErrorRootCauseService[] — A list of services corresponding to an error. A service identifies a segment and it contains a name, account ID, type, and inferred flag.
        - `Name` string — The service name.
        - `Names` String[] — A collection of associated service names.
        - `Type` string — The type associated to the service.
        - `AccountId` string — The account ID associated to the service.
        - `EntityPath` ErrorRootCauseEntity[] — The path of root cause entities found on the service.
          - `Name` string — The name of the entity.
          - `Exceptions` RootCauseException[] — The types and messages of the exceptions.
            - `Name` string — The name of the exception.
            - `Message` string — The message of the exception.
          - `Remote` boolean — A flag that denotes a remote subsegment.
        - `Inferred` boolean — A Boolean value indicating if the service is inferred from the trace.
      - `ClientImpacting` boolean — A flag that denotes that the root cause impacts the trace client.
    - `ResponseTimeRootCauses` ResponseTimeRootCause[] — A collection of ResponseTimeRootCause structures corresponding to the trace segments.
      - `Services` ResponseTimeRootCauseService[] — A list of corresponding services. A service identifies a segment and contains a name, account ID, type, and inferred flag.
        - `Name` string — The service name.
        - `Names` String[] — A collection of associated service names.
        - `Type` string — The type associated to the service.
        - `AccountId` string — The account ID associated to the service.
        - `EntityPath` ResponseTimeRootCauseEntity[] — The path of root cause entities found on the service.
          - `Name` string — The name of the entity.
          - `Coverage` number, double — The type and messages of the exceptions.
          - `Remote` boolean — A flag that denotes a remote subsegment.
        - `Inferred` boolean — A Boolean value indicating if the service is inferred from the trace.
      - `ClientImpacting` boolean — A flag that denotes that the root cause impacts the trace client.
    - `Revision` integer — The revision number of a trace.
    - `MatchedEventTime` string, date-time — The matched time stamp of a defined event.
  - `ApproximateTime` string, date-time — The start time of this page of results.
  - `TracesProcessedCount` integer — The total number of traces processed, including traces that did not match the specified filter expression.
  - `NextToken` string — 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.

## Other responses

- `480` — InvalidRequestException
- `481` — ThrottledException

---

[API](https://skmtc.net/aws/apis/xray.md) · [All operations](https://skmtc.net/aws/apis/xray/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/xray/versions/4970909a360e/schema)