Amazon X-Ray

Amazon X-Ray TraceSummaries API

The TraceSummaries API from Amazon X-Ray — 1 operation(s) for tracesummaries.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.aws.amazon.com/xray/latest/api/
📖
GettingStarted
https://aws.amazon.com/xray/getting-started/
📖
Authentication
https://docs.aws.amazon.com/xray/latest/api/CommonParameters.html
📖
APIReference
https://docs.aws.amazon.com/xray/latest/api/Welcome.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/amazon-xray/refs/heads/main/openapi/amazon-xray-tracesummaries-api-openapi.yml

Code Examples

💻
CodeExamples
https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-sample.html

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/amazon-xray/refs/heads/main/json-schema/xray-trace-summary-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/amazon-xray/refs/heads/main/json-ld/amazon-xray-context.jsonld
🔗
Pricing
https://aws.amazon.com/xray/pricing/
🔗
SDKs
https://aws.amazon.com/tools/
🔗
StatusPage
https://status.aws.amazon.com/
🔗
FAQ
https://aws.amazon.com/xray/faqs/
🔗
Security
https://docs.aws.amazon.com/xray/latest/devguide/security.html

OpenAPI Specification

amazon-xray-tracesummaries-api-openapi.yml Raw ↑ 
openapi: 3.0.0
info:
  version: '2016-04-12'
  x-release: v4
  title: AWS X-Ray CreateGroup TraceSummaries API
  description: Amazon Web Services X-Ray provides APIs for managing debug traces and retrieving service maps and other data created by processing those traces.
  x-logo:
    url: https://twitter.com/awscloud/profile_image?size=original
    backgroundColor: '#FFFFFF'
  termsOfService: https://aws.amazon.com/service-terms/
  contact:
    name: Mike Ralphson
    email: mike.ralphson@gmail.com
    url: https://github.com/mermade/aws2openapi
    x-twitter: PermittedSoc
  license:
    name: Apache 2.0 License
    url: http://www.apache.org/licenses/
  x-providerName: amazonaws.com
  x-serviceName: xray
  x-origin:
  - contentType: application/json
    url: https://raw.githubusercontent.com/aws/aws-sdk-js/master/apis/xray-2016-04-12.normal.json
    converter:
      url: https://github.com/mermade/aws2openapi
      version: 1.0.0
    x-apisguru-driver: external
  x-apiClientRegistration:
    url: https://portal.aws.amazon.com/gp/aws/developer/registration/index.html?nc2=h_ct
  x-apisguru-categories:
  - cloud
  x-preferred: true
servers:
- url: http://xray.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The AWS X-Ray multi-region endpoint
- url: https://xray.{region}.amazonaws.com
  variables:
    region:
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - us-gov-west-1
      - us-gov-east-1
      - ca-central-1
      - eu-north-1
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-south-1
      - af-south-1
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - ap-southeast-1
      - ap-southeast-2
      - ap-east-1
      - ap-south-1
      - sa-east-1
      - me-south-1
      default: us-east-1
  description: The AWS X-Ray multi-region endpoint
- url: http://xray.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The AWS X-Ray endpoint for China (Beijing) and China (Ningxia)
- url: https://xray.{region}.amazonaws.com.cn
  variables:
    region:
      description: The AWS region
      enum:
      - cn-north-1
      - cn-northwest-1
      default: cn-north-1
  description: The AWS X-Ray endpoint for China (Beijing) and China (Ningxia)
security:
- hmac: []
tags:
- name: TraceSummaries
paths:
  /TraceSummaries:
    parameters:
    - $ref: '#/components/parameters/X-Amz-Content-Sha256'
    - $ref: '#/components/parameters/X-Amz-Date'
    - $ref: '#/components/parameters/X-Amz-Algorithm'
    - $ref: '#/components/parameters/X-Amz-Credential'
    - $ref: '#/components/parameters/X-Amz-Security-Token'
    - $ref: '#/components/parameters/X-Amz-Signature'
    - $ref: '#/components/parameters/X-Amz-SignedHeaders'
    post:
      operationId: GetTraceSummaries
      description: <p>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 <code>BatchGetTraces</code>.</p> <p>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 <code>api.example.com</code>:</p> <p> <code>service("api.example.com")</code> </p> <p>This filter expression finds traces that have an annotation named <code>account</code> with the value <code>12345</code>:</p> <p> <code>annotation.account = "12345"</code> </p> <p>For a full list of indexed fields and keywords that you can use in filter expressions, see <a href="https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html">Using Filter Expressions</a> in the <i>Amazon Web Services X-Ray Developer Guide</i>.</p>
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTraceSummariesResult'
        '480':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '481':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      parameters:
      - name: NextToken
        in: query
        schema:
          type: string
        description: Pagination token
        required: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - StartTime
              - EndTime
              properties:
                StartTime:
                  description: The start of the time frame for which to retrieve traces.
                  type: string
                  format: date-time
                EndTime:
                  description: The end of the time frame for which to retrieve traces.
                  type: string
                  format: date-time
                TimeRangeType:
                  description: A parameter to indicate whether to query trace summaries by TraceId or Event time.
                  type: string
                  enum:
                  - TraceId
                  - Event
                Sampling:
                  description: Set to <code>true</code> to get summaries for only a subset of available traces.
                  type: boolean
                SamplingStrategy:
                  description: The name and value of a sampling rule to apply to a trace summary.
                  type: object
                  properties:
                    Name:
                      allOf:
                      - $ref: '#/components/schemas/SamplingStrategyName'
                      - description: The name of a sampling rule.
                    Value:
                      allOf:
                      - $ref: '#/components/schemas/NullableDouble'
                      - description: The value of a sampling rule.
                FilterExpression:
                  description: Specify a filter expression to retrieve trace summaries for services or requests that meet certain requirements.
                  type: string
                NextToken:
                  description: Specify the pagination token returned by a previous request to retrieve the next page of results.
                  type: string
      summary: Amazon X-Ray Get Trace Summaries
      tags:
      - TraceSummaries
components:
  schemas:
    RootCauseExceptions:
      type: array
      items:
        $ref: '#/components/schemas/RootCauseException'
    GetTraceSummariesResult:
      type: object
      properties:
        TraceSummaries:
          allOf:
          - $ref: '#/components/schemas/TraceSummaryList'
          - description: Trace IDs and annotations for traces that were found in the specified time frame.
        ApproximateTime:
          allOf:
          - $ref: '#/components/schemas/Timestamp'
          - description: The start time of this page of results.
        TracesProcessedCount:
          allOf:
          - $ref: '#/components/schemas/NullableLong'
          - description: The total number of traces processed, including traces that did not match the specified filter expression.
        NextToken:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: 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.
    TraceId:
      type: string
      minLength: 1
      maxLength: 35
    String:
      type: string
    ResponseTimeRootCauseEntityPath:
      type: array
      items:
        $ref: '#/components/schemas/ResponseTimeRootCauseEntity'
    ResourceARNDetail:
      type: object
      properties:
        ARN:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The ARN of a corresponding resource.
      description: A list of resources ARNs corresponding to the segments in a trace.
    ErrorRootCauseServices:
      type: array
      items:
        $ref: '#/components/schemas/ErrorRootCauseService'
    NullableInteger:
      type: integer
    TraceUser:
      type: object
      properties:
        UserName:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The user's name.
        ServiceIds:
          allOf:
          - $ref: '#/components/schemas/ServiceIds'
          - description: Services that the user's request hit.
      description: Information about a user recorded in segment documents.
    ValuesWithServiceIds:
      type: array
      items:
        $ref: '#/components/schemas/ValueWithServiceIds'
    NullableBoolean:
      type: boolean
    ErrorRootCauseEntity:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The name of the entity.
        Exceptions:
          allOf:
          - $ref: '#/components/schemas/RootCauseExceptions'
          - description: The types and messages of the exceptions.
        Remote:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A flag that denotes a remote subsegment.
      description: A collection of segments and corresponding subsegments associated to a trace summary error.
    ResponseTimeRootCauseServices:
      type: array
      items:
        $ref: '#/components/schemas/ResponseTimeRootCauseService'
    ServiceNames:
      type: array
      items:
        $ref: '#/components/schemas/String'
    TraceAvailabilityZones:
      type: array
      items:
        $ref: '#/components/schemas/AvailabilityZoneDetail'
    InstanceIdDetail:
      type: object
      properties:
        Id:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The ID of a corresponding EC2 instance.
      description: 'A list of EC2 instance IDs corresponding to the segments in a trace. '
    ErrorRootCauseService:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The service name.
        Names:
          allOf:
          - $ref: '#/components/schemas/ServiceNames'
          - description: A collection of associated service names.
        Type:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The type associated to the service.
        AccountId:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The account ID associated to the service.
        EntityPath:
          allOf:
          - $ref: '#/components/schemas/ErrorRootCauseEntityPath'
          - description: 'The path of root cause entities found on the service. '
        Inferred:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A Boolean value indicating if the service is inferred from the trace.
      description: A collection of fields identifying the services in a trace summary error.
    ResponseTimeRootCause:
      type: object
      properties:
        Services:
          allOf:
          - $ref: '#/components/schemas/ResponseTimeRootCauseServices'
          - description: A list of corresponding services. A service identifies a segment and contains a name, account ID, type, and inferred flag.
        ClientImpacting:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A flag that denotes that the root cause impacts the trace client.
      description: The root cause information for a response time warning.
    ResponseTimeRootCauses:
      type: array
      items:
        $ref: '#/components/schemas/ResponseTimeRootCause'
    Annotations:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/ValuesWithServiceIds'
    ServiceIds:
      type: array
      items:
        $ref: '#/components/schemas/ServiceId'
    FaultRootCauseServices:
      type: array
      items:
        $ref: '#/components/schemas/FaultRootCauseService'
    ServiceId:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: <p/>
        Names:
          allOf:
          - $ref: '#/components/schemas/ServiceNames'
          - description: <p/>
        AccountId:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: <p/>
        Type:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: <p/>
      description: <p/>
    FaultRootCauses:
      type: array
      items:
        $ref: '#/components/schemas/FaultRootCause'
    AvailabilityZoneDetail:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The name of a corresponding Availability Zone.
      description: A list of Availability Zones corresponding to the segments in a trace.
    TraceUsers:
      type: array
      items:
        $ref: '#/components/schemas/TraceUser'
    ValueWithServiceIds:
      type: object
      properties:
        AnnotationValue:
          allOf:
          - $ref: '#/components/schemas/AnnotationValue'
          - description: Values of the annotation.
        ServiceIds:
          allOf:
          - $ref: '#/components/schemas/ServiceIds'
          - description: Services to which the annotation applies.
      description: Information about a segment annotation.
    ErrorRootCauses:
      type: array
      items:
        $ref: '#/components/schemas/ErrorRootCause'
    RootCauseException:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The name of the exception.
        Message:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The message of the exception.
      description: The exception associated with a root cause.
    ResponseTimeRootCauseService:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The service name.
        Names:
          allOf:
          - $ref: '#/components/schemas/ServiceNames'
          - description: A collection of associated service names.
        Type:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The type associated to the service.
        AccountId:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The account ID associated to the service.
        EntityPath:
          allOf:
          - $ref: '#/components/schemas/ResponseTimeRootCauseEntityPath'
          - description: 'The path of root cause entities found on the service. '
        Inferred:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A Boolean value indicating if the service is inferred from the trace.
      description: A collection of fields identifying the service in a response time warning.
    ErrorRootCauseEntityPath:
      type: array
      items:
        $ref: '#/components/schemas/ErrorRootCauseEntity'
    ResponseTimeRootCauseEntity:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The name of the entity.
        Coverage:
          allOf:
          - $ref: '#/components/schemas/NullableDouble'
          - description: The type and messages of the exceptions.
        Remote:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A flag that denotes a remote subsegment.
      description: A collection of segments and corresponding subsegments associated to a response time warning.
    NullableDouble:
      type: number
      format: double
    Http:
      type: object
      properties:
        HttpURL:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The request URL.
        HttpStatus:
          allOf:
          - $ref: '#/components/schemas/NullableInteger'
          - description: The response status.
        HttpMethod:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The request method.
        UserAgent:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The request's user agent string.
        ClientIp:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The IP address of the requestor.
      description: Information about an HTTP request.
    ThrottledException: {}
    FaultRootCause:
      type: object
      properties:
        Services:
          allOf:
          - $ref: '#/components/schemas/FaultRootCauseServices'
          - description: A list of corresponding services. A service identifies a segment and it contains a name, account ID, type, and inferred flag.
        ClientImpacting:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A flag that denotes that the root cause impacts the trace client.
      description: The root cause information for a trace summary fault.
    InvalidRequestException: {}
    FaultRootCauseEntity:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The name of the entity.
        Exceptions:
          allOf:
          - $ref: '#/components/schemas/RootCauseExceptions'
          - description: The types and messages of the exceptions.
        Remote:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A flag that denotes a remote subsegment.
      description: A collection of segments and corresponding subsegments associated to a trace summary fault error.
    ErrorRootCause:
      type: object
      properties:
        Services:
          allOf:
          - $ref: '#/components/schemas/ErrorRootCauseServices'
          - description: A list of services corresponding to an error. A service identifies a segment and it contains a name, account ID, type, and inferred flag.
        ClientImpacting:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A flag that denotes that the root cause impacts the trace client.
      description: The root cause of a trace summary error.
    FaultRootCauseService:
      type: object
      properties:
        Name:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The service name.
        Names:
          allOf:
          - $ref: '#/components/schemas/ServiceNames'
          - description: A collection of associated service names.
        Type:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The type associated to the service.
        AccountId:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: The account ID associated to the service.
        EntityPath:
          allOf:
          - $ref: '#/components/schemas/FaultRootCauseEntityPath'
          - description: 'The path of root cause entities found on the service. '
        Inferred:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: A Boolean value indicating if the service is inferred from the trace.
      description: A collection of fields identifying the services in a trace summary fault.
    Integer:
      type: integer
    Timestamp:
      type: string
      format: date-time
    FaultRootCauseEntityPath:
      type: array
      items:
        $ref: '#/components/schemas/FaultRootCauseEntity'
    NullableLong:
      type: integer
    TraceResourceARNs:
      type: array
      items:
        $ref: '#/components/schemas/ResourceARNDetail'
    TraceSummary:
      type: object
      properties:
        Id:
          allOf:
          - $ref: '#/components/schemas/TraceId'
          - description: The unique identifier for the request that generated the trace's segments and subsegments.
        Duration:
          allOf:
          - $ref: '#/components/schemas/NullableDouble'
          - description: 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:
          allOf:
          - $ref: '#/components/schemas/NullableDouble'
          - description: 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:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: The root segment document has a 500 series error.
        HasError:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: The root segment document has a 400 series error.
        HasThrottle:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: One or more of the segment documents has a 429 throttling error.
        IsPartial:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: One or more of the segment documents is in progress.
        Http:
          allOf:
          - $ref: '#/components/schemas/Http'
          - description: Information about the HTTP request served by the trace.
        Annotations:
          allOf:
          - $ref: '#/components/schemas/Annotations'
          - description: Annotations from the trace's segment documents.
        Users:
          allOf:
          - $ref: '#/components/schemas/TraceUsers'
          - description: Users from the trace's segment documents.
        ServiceIds:
          allOf:
          - $ref: '#/components/schemas/ServiceIds'
          - description: Service IDs from the trace's segment documents.
        ResourceARNs:
          allOf:
          - $ref: '#/components/schemas/TraceResourceARNs'
          - description: A list of resource ARNs for any resource corresponding to the trace segments.
        InstanceIds:
          allOf:
          - $ref: '#/components/schemas/TraceInstanceIds'
          - description: A list of EC2 instance IDs for any instance corresponding to the trace segments.
        AvailabilityZones:
          allOf:
          - $ref: '#/components/schemas/TraceAvailabilityZones'
          - description: A list of Availability Zones for any zone corresponding to the trace segments.
        EntryPoint:
          allOf:
          - $ref: '#/components/schemas/ServiceId'
          - description: The root of a trace.
        FaultRootCauses:
          allOf:
          - $ref: '#/components/schemas/FaultRootCauses'
          - description: A collection of FaultRootCause structures corresponding to the trace segments.
        ErrorRootCauses:
          allOf:
          - $ref: '#/components/schemas/ErrorRootCauses'
          - description: A collection of ErrorRootCause structures corresponding to the trace segments.
        ResponseTimeRootCauses:
          allOf:
          - $ref: '#/components/schemas/ResponseTimeRootCauses'
          - description: A collection of ResponseTimeRootCause structures corresponding to the trace segments.
        Revision:
          allOf:
          - $ref: '#/components/schemas/Integer'
          - description: The revision number of a trace.
        MatchedEventTime:
          allOf:
          - $ref: '#/components/schemas/Timestamp'
          - description: The matched time stamp of a defined event.
      description: Metadata generated from the segment documents in a trace.
    TraceSummaryList:
      type: array
      items:
        $ref: '#/components/schemas/TraceSummary'
    SamplingStrategyName:
      type: string
      enum:
      - PartialScan
      - FixedRate
    TraceInstanceIds:
      type: array
      items:
        $ref: '#/components/schemas/InstanceIdDetail'
    AnnotationValue:
      type: object
      properties:
        NumberValue:
          allOf:
          - $ref: '#/components/schemas/NullableDouble'
          - description: Value for a Number annotation.
        BooleanValue:
          allOf:
          - $ref: '#/components/schemas/NullableBoolean'
          - description: Value for a Boolean annotation.
        StringValue:
          allOf:
          - $ref: '#/components/schemas/String'
          - description: Value for a String annotation.
      description: 'Value of a segment annotation. Has one of three value types: Number, Boolean, or String.'
  parameters:
    X-Amz-SignedHeaders:
      name: X-Amz-SignedHeaders
      in: header
      schema:
        type: string
      required: false
    X-Amz-Signature:
      name: X-Amz-Signature
      in: header
      schema:
        type: string
      required: false
    X-Amz-Security-Token:
      name: X-Amz-Security-Token
      in: header
      schema:
        type: string
      required: false
    X-Amz-Content-Sha256:
      name: X-Amz-Content-Sha256
      in: header
      schema:
        type: string
      required: false
    X-Amz-Date:
      name: X-Amz-Date
      in: header
      schema:
        type: string
      required: false
    X-Amz-Credential:
      name: X-Amz-Credential
      in: header
      schema:
        type: string
      required: false
    X-Amz-Algorithm:
      name: X-Amz-Algorithm
      in: header
      schema:
        type: string
      required: false
  securitySchemes:
    hmac:
      type: apiKey
      name: Authorization
      in: header
      description: Amazon Signature authorization v4
      x-amazon-apigateway-authtype: awsSigv4
externalDocs:
  description: Amazon Web Services documentation
  url: https://docs.aws.amazon.com/xray/