Amazon CloudTrail Cloudtrail Query API

openapi: 3.2.0
info:
  title: AWS CloudTrail Query API
  version: '2013-11-01'
  description: Generated from AWS's published Smithy model for AWS CloudTrail. 5 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://cloudtrail.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Query
paths:
  /#CancelQuery:
    post:
      operationId: CancelQuery
      summary: Cancel Query
      description: CloudTrail Lake will no longer be open to new customers starting May 31, 2026. If you would like to use CloudTrail Lake, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see CloudTrail Lake availability change. Cancels a query if the query is not in a terminated state, such as CANCELLED, FAILED, TIMED_OUT, or FINISHED. You must specify an ARN value for EventDataStore. The ID of the query that you want to cancel is also required. When you run CancelQuery, the query status might show as CANCELLED even if the operation is not yet finished.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/CancelQueryResponse'
        '409':
          description: ConflictException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '400':
          description: EventDataStoreARNInvalidException; InactiveEventDataStoreException; InactiveQueryException; InvalidParameterException; OperationNotPermittedException; UnsupportedOperationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreARNInvalidException'
        '404':
          description: EventDataStoreNotFoundException; QueryIdNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreNotFoundException'
        '403':
          description: NoManagementAccountSLRExistsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/NoManagementAccountSLRExistsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - CloudTrail_20131101.CancelQuery
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/CancelQueryRequest'
      tags:
      - Query
  /#DescribeQuery:
    post:
      operationId: DescribeQuery
      summary: Describe Query
      description: CloudTrail Lake will no longer be open to new customers starting May 31, 2026. If you would like to use CloudTrail Lake, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see CloudTrail Lake availability change. Returns metadata about a query, including query run time in milliseconds, number of events scanned and matched, and query status. If the query results were delivered to an S3 bucket, the response also provides the S3 URI and the delivery status. You must specify either QueryId or QueryAlias. Specifying the QueryAlias parameter returns information about the last query run for the alias. You can provide RefreshId along with QueryAlias to view the query results of a dashboard query for the specified RefreshId.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/DescribeQueryResponse'
        '400':
          description: EventDataStoreARNInvalidException; InactiveEventDataStoreException; InvalidParameterException; OperationNotPermittedException; UnsupportedOperationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreARNInvalidException'
        '404':
          description: EventDataStoreNotFoundException; QueryIdNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreNotFoundException'
        '403':
          description: NoManagementAccountSLRExistsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/NoManagementAccountSLRExistsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - CloudTrail_20131101.DescribeQuery
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DescribeQueryRequest'
      tags:
      - Query
  /#GenerateQuery:
    post:
      operationId: GenerateQuery
      summary: Generate Query
      description: CloudTrail Lake will no longer be open to new customers starting May 31, 2026. If you would like to use CloudTrail Lake, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see CloudTrail Lake availability change. Generates a query from a natural language prompt. This operation uses generative artificial intelligence (generative AI) to produce a ready-to-use SQL query from the prompt. The prompt can be a question or a statement about the event data in your event data store. For example, you can enter prompts like "What are my top errors in the past month?" and “Give me a list of users that used SNS.” The prompt must be in English. For information about limitations, permissions, and supported Regions, see Create CloudTrail Lake queries from natural language prompts in the CloudTrail user guide. Do not include any personally identifying, confidential, or sensitive information in your prompts. This feature uses generative AI large language models (LLMs); we recommend double-checking the LLM response.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GenerateQueryResponse'
        '400':
          description: EventDataStoreARNInvalidException; GenerateResponseException; InactiveEventDataStoreException; InvalidParameterException; OperationNotPermittedException; UnsupportedOperationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreARNInvalidException'
        '404':
          description: EventDataStoreNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreNotFoundException'
        '403':
          description: NoManagementAccountSLRExistsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/NoManagementAccountSLRExistsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - CloudTrail_20131101.GenerateQuery
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GenerateQueryRequest'
      tags:
      - Query
  /#ListQueries:
    post:
      operationId: ListQueries
      summary: List Queries
      description: CloudTrail Lake will no longer be open to new customers starting May 31, 2026. If you would like to use CloudTrail Lake, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see CloudTrail Lake availability change. Returns a list of queries and query statuses for the past seven days. You must specify an ARN value for EventDataStore. Optionally, to shorten the list of results, you can specify a time range, formatted as timestamps, by adding StartTime and EndTime parameters, and a QueryStatus value. Valid values for QueryStatus include QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListQueriesResponse'
        '400':
          description: EventDataStoreARNInvalidException; InactiveEventDataStoreException; InvalidDateRangeException; InvalidMaxResultsException; InvalidNextTokenException; InvalidParameterException; InvalidQueryStatusException; OperationNotPermittedException; UnsupportedOperationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreARNInvalidException'
        '404':
          description: EventDataStoreNotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreNotFoundException'
        '403':
          description: NoManagementAccountSLRExistsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/NoManagementAccountSLRExistsException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - CloudTrail_20131101.ListQueries
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListQueriesRequest'
      tags:
      - Query
  /#StartQuery:
    post:
      operationId: StartQuery
      summary: Start Query
      description: CloudTrail Lake will no longer be open to new customers starting May 31, 2026. If you would like to use CloudTrail Lake, sign up prior to that date. Existing customers can continue to use the service as normal. For more information, see CloudTrail Lake availability change. Starts a CloudTrail Lake query. Use the QueryStatement parameter to provide your SQL query, enclosed in single quotation marks. Use the optional DeliveryS3Uri parameter to deliver the query results to an S3 bucket. StartQuery requires you specify either the QueryStatement parameter, or a QueryAlias and any QueryParameters. In the current release, the QueryAlias and QueryParameters parameters are used only for the queries that populate the CloudTrail Lake dashboards.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StartQueryResponse'
        '400':
          description: EventDataStoreARNInvalidException; InactiveEventDataStoreException; InsufficientEncryptionPolicyException; InvalidParameterException; InvalidQueryStatementException; InvalidS3BucketNameException; InvalidS3PrefixException; OperationNotPermittedException; UnsupportedOperationException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreARNInvalidException'
        '404':
          description: EventDataStoreNotFoundException; S3BucketDoesNotExistException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/EventDataStoreNotFoundException'
        '403':
          description: InsufficientS3BucketPolicyException; NoManagementAccountSLRExistsException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InsufficientS3BucketPolicyException'
        '429':
          description: MaxConcurrentQueriesException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/MaxConcurrentQueriesException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - CloudTrail_20131101.StartQuery
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StartQueryRequest'
      tags:
      - Query
components:
  schemas:
    ListQueriesRequest:
      type: object
      properties:
        EventDataStore:
          type: string
          description: The ARN (or the ID suffix of the ARN) of an event data store on which queries were run.
        NextToken:
          type: string
          description: A token you can use to get the next page of results.
        MaxResults:
          type: integer
          description: The maximum number of queries to show on a page.
        StartTime:
          type: string
          format: date-time
          description: Use with EndTime to bound a ListQueries request, and limit its results to only those queries run within a specified time period.
        EndTime:
          type: string
          format: date-time
          description: Use with StartTime to bound a ListQueries request, and limit its results to only those queries run within a specified time period.
        QueryStatus:
          type: string
          enum:
          - QUEUED
          - RUNNING
          - FINISHED
          - FAILED
          - CANCELLED
          - TIMED_OUT
          description: The status of queries that you want to return in results. Valid values for QueryStatus include QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED.
      required:
      - EventDataStore
    ListQueriesResponse:
      type: object
      properties:
        Queries:
          type: array
          items:
            $ref: '#/components/schemas/Query'
          description: Lists matching query results, and shows query ID, status, and creation time of each query.
        NextToken:
          type: string
          description: A token you can use to get the next page of results.
    EventDataStoreNotFoundException:
      type: object
      properties:
        Message:
          type: string
          description: Brief description of the exception returned by the request.
    CancelQueryRequest:
      type: object
      properties:
        EventDataStore:
          type: string
          description: The ARN (or the ID suffix of the ARN) of an event data store on which the specified query is running.
        QueryId:
          type: string
          description: The ID of the query that you want to cancel. The QueryId comes from the response of a StartQuery operation.
        EventDataStoreOwnerAccountId:
          type: string
          description: The account ID of the event data store owner.
      required:
      - QueryId
    StartQueryResponse:
      type: object
      properties:
        QueryId:
          type: string
          description: The ID of the started query.
        EventDataStoreOwnerAccountId:
          type: string
          description: The account ID of the event data store owner.
    StartQueryRequest:
      type: object
      properties:
        QueryStatement:
          type: string
          description: The SQL code of your query.
        DeliveryS3Uri:
          type: string
          description: The URI for the S3 bucket where CloudTrail delivers the query results.
        QueryAlias:
          type: string
          description: The alias that identifies a query template.
        QueryParameters:
          type: array
          items:
            type: string
          description: The query parameters for the specified QueryAlias.
        EventDataStoreOwnerAccountId:
          type: string
          description: The account ID of the event data store owner.
    CancelQueryResponse:
      type: object
      properties:
        QueryId:
          type: string
          description: The ID of the canceled query.
        QueryStatus:
          type: string
          enum:
          - QUEUED
          - RUNNING
          - FINISHED
          - FAILED
          - CANCELLED
          - TIMED_OUT
          description: Shows the status of a query after a CancelQuery request. Typically, the values shown are either RUNNING or CANCELLED.
        EventDataStoreOwnerAccountId:
          type: string
          description: The account ID of the event data store owner.
      required:
      - QueryId
      - QueryStatus
    InsufficientS3BucketPolicyException:
      type: object
      properties:
        Message:
          type: string
          description: Brief description of the exception returned by the request.
    NoManagementAccountSLRExistsException:
      type: object
      properties:
        Message:
          type: string
          description: Brief description of the exception returned by the request.
    QueryStatisticsForDescribeQuery:
      type: object
      properties:
        EventsMatched:
          type: integer
          description: The number of events that matched a query.
        EventsScanned:
          type: integer
          description: The number of events that the query scanned in the event data store.
        BytesScanned:
          type: integer
          description: The total bytes that the query scanned in the event data store. This value matches the number of bytes for which your account is billed for the query, unless the query is still running.
        ExecutionTimeInMillis:
          type: integer
          description: The query's run time, in milliseconds.
        CreationTime:
          type: string
          format: date-time
          description: The creation time of the query.
    MaxConcurrentQueriesException:
      type: object
      properties:
        Message:
          type: string
          description: Brief description of the exception returned by the request.
    GenerateQueryRequest:
      type: object
      properties:
        EventDataStores:
          type: array
          items:
            type: string
          description: The ARN (or ID suffix of the ARN) of the event data store that you want to query. You can only specify one event data store.
        Prompt:
          type: string
          description: The prompt that you want to use to generate the query. The prompt must be in English. For example prompts, see Example prompts in the CloudTrail user guide.
      required:
      - EventDataStores
      - Prompt
    EventDataStoreARNInvalidException:
      type: object
      properties:
        Message:
          type: string
          description: Brief description of the exception returned by the request.
    ConflictException:
      type: object
      properties:
        Message:
          type: string
          description: Brief description of the exception returned by the request.
    Query:
      type: object
      properties:
        QueryId:
          type: string
          description: The ID of a query.
        QueryStatus:
          type: string
          enum:
          - QUEUED
          - RUNNING
          - FINISHED
          - FAILED
          - CANCELLED
          - TIMED_OUT
          description: The status of the query. This can be QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED.
        CreationTime:
          type: string
          format: date-time
          description: The creation time of a query.
    GenerateQueryResponse:
      type: object
      properties:
        QueryStatement:
          type: string
          description: The SQL query statement generated from the prompt.
        QueryAlias:
          type: string
          description: An alias that identifies the prompt. When you run the StartQuery operation, you can pass in either the QueryAlias or QueryStatement parameter.
        EventDataStoreOwnerAccountId:
          type: string
          description: The account ID of the event data store owner.
    DescribeQueryRequest:
      type: object
      properties:
        EventDataStore:
          type: string
          description: The ARN (or the ID suffix of the ARN) of an event data store on which the specified query was run.
        QueryId:
          type: string
          description: The query ID.
        QueryAlias:
          type: string
          description: The alias that identifies a query template.
        RefreshId:
          type: string
          description: The ID of the dashboard refresh.
        EventDataStoreOwnerAccountId:
          type: string
          description: The account ID of the event data store owner.
    DescribeQueryResponse:
      type: object
      properties:
        QueryId:
          type: string
          description: The ID of the query.
        QueryString:
          type: string
          description: The SQL code of a query.
        QueryStatus:
          type: string
          enum:
          - QUEUED
          - RUNNING
          - FINISHED
          - FAILED
          - CANCELLED
          - TIMED_OUT
          description: The status of a query. Values for QueryStatus include QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED
        QueryStatistics:
          $ref: '#/components/schemas/QueryStatisticsForDescribeQuery'
        ErrorMessage:
          type: string
          description: The error message returned if a query failed.
        DeliveryS3Uri:
          type: string
          description: The URI for the S3 bucket where CloudTrail delivered query results, if applicable.
        DeliveryStatus:
          type: string
          enum:
          - SUCCESS
          - FAILED
          - FAILED_SIGNING_FILE
          - PENDING
          - RESOURCE_NOT_FOUND
          - ACCESS_DENIED
          - ACCESS_DENIED_SIGNING_FILE
          - CANCELLED
          - UNKNOWN
          description: The delivery status.
        Prompt:
          type: string
          description: The prompt used for a generated query. For information about generated queries, see Create CloudTrail Lake queries from natural language prompts in the CloudTrail user guide.
        EventDataStoreOwnerAccountId:
          type: string
          description: The account ID of the event data store owner.
  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: cloudtrail
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/cloudtrail/service/2013-11-01/cloudtrail-2013-11-01.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)