AWS X-Ray

AWS X-Ray Sampling API

Manage sampling rules

GitHub OpenAPI
Business capability
Observability Management BC-4220.20

Operations 6

POST /SamplingRules AWS X-Ray Get All Sampling Rules #
POST /CreateSamplingRule AWS X-Ray Create a Sampling Rule #
POST /UpdateSamplingRule AWS X-Ray Update a Sampling Rule #
POST /DeleteSamplingRule AWS X-Ray Delete a Sampling Rule #
POST /SamplingTargets AWS X-Ray Get Sampling Targets #
POST /GetSamplingRules Get Sampling Rules #

Documentation

📖
Documentation
https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html
📖
APIReference
https://docs.aws.amazon.com/xray/latest/api/Welcome.html

Specifications

⚙
OpenAPI
https://artifacts.apis.io/aws-x-ray/openapi/aws-x-ray-sampling-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/aws-x-ray/json-schema/aws-x-ray-trace-segment.yml

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/aws-x-ray:aws-x-ray-sampling-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.

GitHub Google LinkedIn

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

OpenAPI Specification

aws-x-ray-sampling-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Aws X Ray Sampling API
  version: '2016-04-12'
  description: 'Operations tagged Sampling across 2 of this provider''s published API definitions: aws-x-ray-openapi.yml, aws-x-ray-sampling-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://xray.{region}.amazonaws.com
  description: AWS X-Ray regional endpoint
  variables:
    region:
      default: us-east-1
      description: AWS region
tags:
- name: Sampling
  description: Manage sampling rules
paths:
  /SamplingRules:
    post:
      operationId: GetSamplingRules
      summary: AWS X-Ray Get All Sampling Rules
      description: Retrieves all sampling rules.
      tags:
      - Sampling
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                NextToken:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  SamplingRuleRecords:
                    type: array
                    items:
                      $ref: '#/components/schemas/SamplingRuleRecord'
                  NextToken:
                    type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - aws_sig_v4: []
    servers:
    - url: https://xray.{region}.amazonaws.com
      description: AWS X-Ray regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
  /CreateSamplingRule:
    post:
      operationId: CreateSamplingRule
      summary: AWS X-Ray Create a Sampling Rule
      description: Creates a rule to control sampling behavior for instrumented applications.
      tags:
      - Sampling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - SamplingRule
              properties:
                SamplingRule:
                  $ref: '#/components/schemas/SamplingRule'
                Tags:
                  type: array
                  items:
                    $ref: '#/components/schemas/Tag'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  SamplingRuleRecord:
                    $ref: '#/components/schemas/SamplingRuleRecord'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - aws_sig_v4: []
    servers:
    - url: https://xray.{region}.amazonaws.com
      description: AWS X-Ray regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
  /UpdateSamplingRule:
    post:
      operationId: UpdateSamplingRule
      summary: AWS X-Ray Update a Sampling Rule
      description: Modifies a sampling rule's configuration.
      tags:
      - Sampling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - SamplingRuleUpdate
              properties:
                SamplingRuleUpdate:
                  type: object
                  properties:
                    RuleName:
                      type: string
                    RuleARN:
                      type: string
                    ResourceARN:
                      type: string
                    Priority:
                      type: integer
                    FixedRate:
                      type: number
                    ReservoirSize:
                      type: integer
                    Host:
                      type: string
                    ServiceName:
                      type: string
                    ServiceType:
                      type: string
                    HTTPMethod:
                      type: string
                    URLPath:
                      type: string
                    Attributes:
                      type: object
                      additionalProperties:
                        type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  SamplingRuleRecord:
                    $ref: '#/components/schemas/SamplingRuleRecord'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - aws_sig_v4: []
    servers:
    - url: https://xray.{region}.amazonaws.com
      description: AWS X-Ray regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
  /DeleteSamplingRule:
    post:
      operationId: DeleteSamplingRule
      summary: AWS X-Ray Delete a Sampling Rule
      description: Deletes a sampling rule.
      tags:
      - Sampling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                RuleName:
                  type: string
                RuleARN:
                  type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  SamplingRuleRecord:
                    $ref: '#/components/schemas/SamplingRuleRecord'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - aws_sig_v4: []
    servers:
    - url: https://xray.{region}.amazonaws.com
      description: AWS X-Ray regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
  /SamplingTargets:
    post:
      operationId: GetSamplingTargets
      summary: AWS X-Ray Get Sampling Targets
      description: Requests a sampling quota for rules that the service is using to sample requests.
      tags:
      - Sampling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - SamplingStatisticsDocuments
              properties:
                SamplingStatisticsDocuments:
                  type: array
                  items:
                    type: object
                    properties:
                      RuleName:
                        type: string
                      ClientID:
                        type: string
                      Timestamp:
                        type: string
                        format: date-time
                      RequestCount:
                        type: integer
                      SampledCount:
                        type: integer
                      BorrowCount:
                        type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  SamplingTargetDocuments:
                    type: array
                    items:
                      type: object
                      properties:
                        RuleName:
                          type: string
                        FixedRate:
                          type: number
                        ReservoirQuota:
                          type: integer
                        ReservoirQuotaTTL:
                          type: string
                          format: date-time
                        Interval:
                          type: integer
                  LastRuleModification:
                    type: string
                    format: date-time
                  UnprocessedStatistics:
                    type: array
                    items:
                      type: object
                      properties:
                        RuleName:
                          type: string
                        ErrorCode:
                          type: string
                        Message:
                          type: string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      security:
      - aws_sig_v4: []
    servers:
    - url: https://xray.{region}.amazonaws.com
      description: AWS X-Ray regional endpoint
      variables:
        region:
          default: us-east-1
          description: AWS region
  /GetSamplingRules:
    post:
      operationId: postGetSamplingRules
      summary: Get Sampling Rules
      description: Retrieves all sampling rules.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSamplingRulesResult'
        '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/GetSamplingRulesRequest'
      tags:
      - Sampling
      security:
      - sigv4: []
      x-operation-id-source: normalized
      x-operation-id-original: GetSamplingRules
    servers:
    - url: https://xray.{region}.amazonaws.com
      variables:
        region:
          default: us-east-1
components:
  schemas:
    Tag:
      type: object
      required:
      - Key
      - Value
      properties:
        Key:
          type: string
        Value:
          type: string
    SamplingRule:
      type: object
      required:
      - ResourceARN
      - Priority
      - FixedRate
      - ReservoirSize
      - ServiceName
      - ServiceType
      - Host
      - HTTPMethod
      - URLPath
      - Version
      properties:
        RuleName:
          type: string
        RuleARN:
          type: string
        ResourceARN:
          type: string
        Priority:
          type: integer
        FixedRate:
          type: number
        ReservoirSize:
          type: integer
        ServiceName:
          type: string
        ServiceType:
          type: string
        Host:
          type: string
        HTTPMethod:
          type: string
        URLPath:
          type: string
        Version:
          type: integer
        Attributes:
          type: object
          additionalProperties:
            type: string
    SamplingRuleRecord:
      type: object
      properties:
        SamplingRule:
          $ref: '#/components/schemas/SamplingRule'
        CreatedAt:
          type: string
          format: date-time
        ModifiedAt:
          type: string
          format: date-time
    GetSamplingRulesRequest:
      type: object
      properties:
        NextToken:
          type: string
          description: Pagination token.
    SamplingRateBoost:
      type: object
      properties:
        MaxRate:
          type: number
          description: Defines max temporary sampling rate to apply when a boost is triggered. Calculated boost rate by X-Ray will be less than or equal to this max rate.
        CooldownWindowMinutes:
          type: integer
          description: Sets the time window (in minutes) in which only one sampling rate boost can be triggered. After a boost occurs, no further boosts are allowed until the next window.
      required:
      - MaxRate
      - CooldownWindowMinutes
    GetSamplingRulesResult:
      type: object
      properties:
        SamplingRuleRecords:
          type: array
          items:
            $ref: '#/components/schemas/SamplingRuleRecord_2'
          description: Rule definitions and metadata.
        NextToken:
          type: string
          description: Pagination token.
    ThrottledException:
      type: object
      properties:
        Message:
          type: string
    InvalidRequestException:
      type: object
      properties:
        Message:
          type: string
    SamplingRule_2:
      type: object
      properties:
        RuleName:
          type: string
          description: The name of the sampling rule. Specify a rule by either name or ARN, but not both.
        RuleARN:
          type: string
          description: The ARN of the sampling rule. Specify a rule by either name or ARN, but not both.
        ResourceARN:
          type: string
          description: Matches the ARN of the Amazon Web Services resource on which the service runs.
        Priority:
          type: integer
          description: The priority of the sampling rule.
        FixedRate:
          type: number
          description: The percentage of matching requests to instrument, after the reservoir is exhausted.
        ReservoirSize:
          type: integer
          description: A fixed number of matching requests to instrument per second, prior to applying the fixed rate. The reservoir is not used directly by services, but applies to all services using the rule collectively.
        ServiceName:
          type: string
          description: Matches the name that the service uses to identify itself in segments.
        ServiceType:
          type: string
          description: Matches the origin that the service uses to identify its type in segments.
        Host:
          type: string
          description: Matches the hostname from a request URL.
        HTTPMethod:
          type: string
          description: Matches the HTTP method of a request.
        URLPath:
          type: string
          description: Matches the path from a request URL.
        Version:
          type: integer
          description: The version of the sampling rule format (1).
        Attributes:
          type: object
          additionalProperties:
            type: string
          description: Matches attributes derived from the request.
        SamplingRateBoost:
          $ref: '#/components/schemas/SamplingRateBoost'
      required:
      - ResourceARN
      - Priority
      - FixedRate
      - ReservoirSize
      - ServiceName
      - ServiceType
      - Host
      - HTTPMethod
      - URLPath
      - Version
    SamplingRuleRecord_2:
      type: object
      properties:
        SamplingRule:
          $ref: '#/components/schemas/SamplingRule_2'
        CreatedAt:
          type: string
          format: date-time
          description: When the rule was created.
        ModifiedAt:
          type: string
          format: date-time
          description: When the rule was last modified.
  securitySchemes:
    aws_sig_v4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4
    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
x-refined-from:
- aws-x-ray-openapi.yml
- aws-x-ray-sampling-api-openapi.yml