Amazon X-Ray Traces API

The Traces API from Amazon X-Ray — 2 operation(s) for traces.

GitHub OpenAPI
Business capability
Observability Management BC-4220.20

Operations 2

POST /Traces Batch Get Traces #
POST /TraceSummaries Get Trace Summaries #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/amazon-xray:amazon-xray-traces-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

amazon-xray-traces-api-openapi.yml Raw ↑
openapi: 3.1.0
info:
  title: AWS X-Ray Traces API
  version: '2016-04-12'
  description: Generated from AWS's published Smithy model for AWS X-Ray. 2 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://xray.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /Traces:
    post:
      operationId: BatchGetTraces
      summary: Batch Get Traces
      description: You cannot find traces through this API if Transaction Search is enabled since trace is not indexed in
        X-Ray. Retrieves a list of traces specified by ID. Each trace is a collection of segment documents that originates
        from a single request. Use GetTraceSummaries to get a list of trace IDs.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGetTracesResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGetTracesRequest'
      tags:
      - Traces
  /TraceSummaries:
    post:
      operationId: GetTraceSummaries
      summary: Get Trace Summaries
      description: '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 Use filter expressions in the Amazon Web Services X-Ray Developer
        Guide.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTraceSummariesResult'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '429':
          description: ThrottledException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottledException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTraceSummariesRequest'
      tags:
      - Traces
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: xray
  schemas:
    AnnotationValue:
      type: object
      properties:
        NumberValue:
          type: number
          description: Value for a Number annotation.
        BooleanValue:
          type: boolean
          description: Value for a Boolean annotation.
        StringValue:
          type: string
          description: Value for a String annotation.
      description: Exactly one member is set.
    AvailabilityZoneDetail:
      type: object
      properties:
        Name:
          type: string
          description: The name of a corresponding Availability Zone.
    BatchGetTracesRequest:
      type: object
      properties:
        TraceIds:
          type: array
          items:
            type: string
          description: Specify the trace IDs of requests for which to retrieve segments.
        NextToken:
          type: string
          description: Pagination token.
      required:
      - TraceIds
    BatchGetTracesResult:
      type: object
      properties:
        Traces:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
          description: Full traces for the specified requests.
        UnprocessedTraceIds:
          type: array
          items:
            type: string
          description: Trace IDs of requests that haven't been processed.
        NextToken:
          type: string
          description: Pagination token.
    ErrorRootCause:
      type: object
      properties:
        Services:
          type: array
          items:
            $ref: '#/components/schemas/ErrorRootCauseService'
          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:
          type: boolean
          description: A flag that denotes that the root cause impacts the trace client.
    ErrorRootCauseEntity:
      type: object
      properties:
        Name:
          type: string
          description: The name of the entity.
        Exceptions:
          type: array
          items:
            $ref: '#/components/schemas/RootCauseException'
          description: The types and messages of the exceptions.
        Remote:
          type: boolean
          description: A flag that denotes a remote subsegment.
    ErrorRootCauseService:
      type: object
      properties:
        Name:
          type: string
          description: The service name.
        Names:
          type: array
          items:
            type: string
          description: A collection of associated service names.
        Type:
          type: string
          description: The type associated to the service.
        AccountId:
          type: string
          description: The account ID associated to the service.
        EntityPath:
          type: array
          items:
            $ref: '#/components/schemas/ErrorRootCauseEntity'
          description: The path of root cause entities found on the service.
        Inferred:
          type: boolean
          description: A Boolean value indicating if the service is inferred from the trace.
    FaultRootCause:
      type: object
      properties:
        Services:
          type: array
          items:
            $ref: '#/components/schemas/FaultRootCauseService'
          description: A list of corresponding services. A service identifies a segment and it contains a name, account ID,
            type, and inferred flag.
        ClientImpacting:
          type: boolean
          description: A flag that denotes that the root cause impacts the trace client.
    FaultRootCauseEntity:
      type: object
      properties:
        Name:
          type: string
          description: The name of the entity.
        Exceptions:
          type: array
          items:
            $ref: '#/components/schemas/RootCauseException'
          description: The types and messages of the exceptions.
        Remote:
          type: boolean
          description: A flag that denotes a remote subsegment.
    FaultRootCauseService:
      type: object
      properties:
        Name:
          type: string
          description: The service name.
        Names:
          type: array
          items:
            type: string
          description: A collection of associated service names.
        Type:
          type: string
          description: The type associated to the service.
        AccountId:
          type: string
          description: The account ID associated to the service.
        EntityPath:
          type: array
          items:
            $ref: '#/components/schemas/FaultRootCauseEntity'
          description: The path of root cause entities found on the service.
        Inferred:
          type: boolean
          description: A Boolean value indicating if the service is inferred from the trace.
    GetTraceSummariesRequest:
      type: object
      properties:
        StartTime:
          type: string
          format: date-time
          description: The start of the time frame for which to retrieve traces.
        EndTime:
          type: string
          format: date-time
          description: The end of the time frame for which to retrieve traces.
        TimeRangeType:
          type: string
          enum:
          - TraceId
          - Event
          - Service
          description: Query trace summaries by TraceId (trace start time), Event (trace update time), or Service (trace segment
            end time).
        Sampling:
          type: boolean
          description: Set to true to get summaries for only a subset of available traces.
        SamplingStrategy:
          $ref: '#/components/schemas/SamplingStrategy'
        FilterExpression:
          type: string
          description: Specify a filter expression to retrieve trace summaries for services or requests that meet certain
            requirements.
        NextToken:
          type: string
          description: Specify the pagination token returned by a previous request to retrieve the next page of results.
      required:
      - StartTime
      - EndTime
    GetTraceSummariesResult:
      type: object
      properties:
        TraceSummaries:
          type: array
          items:
            $ref: '#/components/schemas/TraceSummary'
          description: Trace IDs and annotations for traces that were found in the specified time frame.
        ApproximateTime:
          type: string
          format: date-time
          description: The start time of this page of results.
        TracesProcessedCount:
          type: integer
          description: The total number of traces processed, including traces that did not match the specified filter expression.
        NextToken:
          type: 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.
    Http:
      type: object
      properties:
        HttpURL:
          type: string
          description: The request URL.
        HttpStatus:
          type: integer
          description: The response status.
        HttpMethod:
          type: string
          description: The request method.
        UserAgent:
          type: string
          description: The request's user agent string.
        ClientIp:
          type: string
          description: The IP address of the requestor.
    InstanceIdDetail:
      type: object
      properties:
        Id:
          type: string
          description: The ID of a corresponding EC2 instance.
    InvalidRequestException:
      type: object
      properties:
        Message:
          type: string
    ResourceARNDetail:
      type: object
      properties:
        ARN:
          type: string
          description: The ARN of a corresponding resource.
    ResponseTimeRootCause:
      type: object
      properties:
        Services:
          type: array
          items:
            $ref: '#/components/schemas/ResponseTimeRootCauseService'
          description: A list of corresponding services. A service identifies a segment and contains a name, account ID, type,
            and inferred flag.
        ClientImpacting:
          type: boolean
          description: A flag that denotes that the root cause impacts the trace client.
    ResponseTimeRootCauseEntity:
      type: object
      properties:
        Name:
          type: string
          description: The name of the entity.
        Coverage:
          type: number
          description: The type and messages of the exceptions.
        Remote:
          type: boolean
          description: A flag that denotes a remote subsegment.
    ResponseTimeRootCauseService:
      type: object
      properties:
        Name:
          type: string
          description: The service name.
        Names:
          type: array
          items:
            type: string
          description: A collection of associated service names.
        Type:
          type: string
          description: The type associated to the service.
        AccountId:
          type: string
          description: The account ID associated to the service.
        EntityPath:
          type: array
          items:
            $ref: '#/components/schemas/ResponseTimeRootCauseEntity'
          description: The path of root cause entities found on the service.
        Inferred:
          type: boolean
          description: A Boolean value indicating if the service is inferred from the trace.
    RootCauseException:
      type: object
      properties:
        Name:
          type: string
          description: The name of the exception.
        Message:
          type: string
          description: The message of the exception.
    SamplingStrategy:
      type: object
      properties:
        Name:
          type: string
          enum:
          - PartialScan
          - FixedRate
          description: The name of a sampling rule.
        Value:
          type: number
          description: The value of a sampling rule.
    Segment:
      type: object
      properties:
        Id:
          type: string
          description: The segment's ID.
        Document:
          type: string
          description: The segment document.
    ServiceId:
      type: object
      properties:
        Name:
          type: string
        Names:
          type: array
          items:
            type: string
        AccountId:
          type: string
        Type:
          type: string
    ThrottledException:
      type: object
      properties:
        Message:
          type: string
    Trace:
      type: object
      properties:
        Id:
          type: string
          description: The unique identifier for the request that generated the trace's segments and subsegments.
        Duration:
          type: number
          description: The length of time in seconds between the start time of the earliest segment that started and the end
            time of the last segment that completed.
        LimitExceeded:
          type: boolean
          description: LimitExceeded is set to true when the trace has exceeded the Trace document size limit. For more information
            about this limit and other X-Ray limits and quotas, see Amazon Web Services X-Ray endpoints and quotas.
        Segments:
          type: array
          items:
            $ref: '#/components/schemas/Segment'
          description: Segment documents for the segments and subsegments that comprise the trace.
    TraceSummary:
      type: object
      properties:
        Id:
          type: string
          description: The unique identifier for the request that generated the trace's segments and subsegments.
        StartTime:
          type: string
          format: date-time
          description: The start time of a trace, based on the earliest trace segment start time.
        Duration:
          type: number
          description: The length of time in seconds between the start time of the earliest segment that started and the end
            time of the last segment that completed.
        ResponseTime:
          type: number
          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:
          type: boolean
          description: The root segment document has a 500 series error.
        HasError:
          type: boolean
          description: The root segment document has a 400 series error.
        HasThrottle:
          type: boolean
          description: One or more of the segment documents has a 429 throttling error.
        IsPartial:
          type: boolean
          description: One or more of the segment documents is in progress.
        Http:
          $ref: '#/components/schemas/Http'
        Annotations:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ValueWithServiceIds'
          description: Annotations from the trace's segment documents.
        Users:
          type: array
          items:
            $ref: '#/components/schemas/TraceUser'
          description: Users from the trace's segment documents.
        ServiceIds:
          type: array
          items:
            $ref: '#/components/schemas/ServiceId'
          description: Service IDs from the trace's segment documents.
        ResourceARNs:
          type: array
          items:
            $ref: '#/components/schemas/ResourceARNDetail'
          description: A list of resource ARNs for any resource corresponding to the trace segments.
        InstanceIds:
          type: array
          items:
            $ref: '#/components/schemas/InstanceIdDetail'
          description: A list of EC2 instance IDs for any instance corresponding to the trace segments.
        AvailabilityZones:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityZoneDetail'
          description: A list of Availability Zones for any zone corresponding to the trace segments.
        EntryPoint:
          $ref: '#/components/schemas/ServiceId'
        FaultRootCauses:
          type: array
          items:
            $ref: '#/components/schemas/FaultRootCause'
          description: A collection of FaultRootCause structures corresponding to the trace segments.
        ErrorRootCauses:
          type: array
          items:
            $ref: '#/components/schemas/ErrorRootCause'
          description: A collection of ErrorRootCause structures corresponding to the trace segments.
        ResponseTimeRootCauses:
          type: array
          items:
            $ref: '#/components/schemas/ResponseTimeRootCause'
          description: A collection of ResponseTimeRootCause structures corresponding to the trace segments.
        Revision:
          type: integer
          description: The revision number of a trace.
        MatchedEventTime:
          type: string
          format: date-time
          description: The matched time stamp of a defined event.
    TraceUser:
      type: object
      properties:
        UserName:
          type: string
          description: The user's name.
        ServiceIds:
          type: array
          items:
            $ref: '#/components/schemas/ServiceId'
          description: Services that the user's request hit.
    ValueWithServiceIds:
      type: object
      properties:
        AnnotationValue:
          $ref: '#/components/schemas/AnnotationValue'
        ServiceIds:
          type: array
          items:
            $ref: '#/components/schemas/ServiceId'
          description: Services to which the annotation applies.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/xray/service/2016-04-12/xray-2016-04-12.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)