Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: Amazon CloudWatch Query API
version: '2010-08-01'
description: Generated from AWS's published Smithy model for Amazon CloudWatch. 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://logs.{region}.amazonaws.com
variables:
region:
default: us-east-1
security:
- sigv4: []
paths:
/#DescribeQueries:
post:
operationId: DescribeQueries
summary: Describe Queries
description: Returns a list of CloudWatch Logs Insights queries that are scheduled, running, or have been run recently
in this account. You can request all queries or limit it to queries of a specific log group or queries with a certain
status. This operation includes both interactive queries started directly by users and automated queries executed
by scheduled query configurations. Scheduled query executions appear in the results alongside manually initiated queries,
providing visibility into all query activity in your account.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/DescribeQueriesResponse'
'400':
description: InvalidParameterException; ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/InvalidParameterException'
'500':
description: ServiceUnavailableException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ServiceUnavailableException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.DescribeQueries
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/DescribeQueriesRequest'
tags:
- Query
/#StartQuery:
post:
operationId: StartQuery
summary: Start Query
description: 'Starts a query of one or more log groups or data sources using CloudWatch Logs Insights. You specify the
log groups or data sources and time range to query and the query string to use. You can query up to 10 data sources
in a single query. For more information, see CloudWatch Logs Insights Query Syntax. After you run a query using StartQuery,
the query results are stored by CloudWatch Logs. You can use GetQueryResults to retrieve the results of a query, using
the queryId that StartQuery returns. Interactive queries started with StartQuery share concurrency limits with automated
scheduled query executions. Both types of queries count toward the same regional concurrent query quota, so high scheduled
query activity may affect the availability of concurrent slots for interactive queries. To specify the log groups
to query, a StartQuery operation must include one of the following: Either exactly one of the following parameters:
logGroupName, logGroupNames, or logGroupIdentifiers Or the queryString must include a SOURCE command to select log
groups for the query. The SOURCE command can select log groups based on log group name prefix, account ID, and log
class, or select data sources us'
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/StartQueryResponse'
'400':
description: InvalidParameterException; LimitExceededException; MalformedQueryException; ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/InvalidParameterException'
'500':
description: ServiceUnavailableException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ServiceUnavailableException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.StartQuery
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/StartQueryRequest'
tags:
- Query
/#StopQuery:
post:
operationId: StopQuery
summary: Stop Query
description: Stops a CloudWatch Logs Insights query that is in progress. If the query has already ended, the operation
returns an error indicating that the specified query is not running. This operation can be used to cancel both interactive
queries and individual scheduled query executions. When used with scheduled queries, StopQuery cancels only the specific
execution identified by the query ID, not the scheduled query configuration itself.
responses:
'200':
description: Success
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/StopQueryResponse'
'400':
description: InvalidParameterException; ResourceNotFoundException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/InvalidParameterException'
'500':
description: ServiceUnavailableException
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/ServiceUnavailableException'
parameters:
- name: X-Amz-Target
in: header
required: true
schema:
type: string
enum:
- Logs_20140328.StopQuery
requestBody:
required: true
content:
application/x-amz-json-1.1:
schema:
$ref: '#/components/schemas/StopQueryRequest'
tags:
- Query
/v20210603/Monitors/{MonitorName}/Queries:
post:
operationId: StartQuery
summary: Start Query
description: Start a query to return data for a specific query type for the Amazon CloudWatch Internet Monitor query
interface. Specify a time period for the data that you want returned by using StartTime and EndTime. You filter the
query results to return by providing parameters that you specify with FilterParameters. For more information about
using the query interface, including examples, see Using the Amazon CloudWatch Internet Monitor query interface in
the Amazon CloudWatch Internet Monitor User Guide.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/StartQueryOutput'
'403':
description: AccessDeniedException; LimitExceededException
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedException'
'500':
description: InternalServerException
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerException'
'429':
description: ThrottlingException
content:
application/json:
schema:
$ref: '#/components/schemas/InternetmonitorThrottlingException'
'400':
description: ValidationException
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationException'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StartQueryInput'
tags:
- Query
servers:
- url: https://internetmonitor.{region}.amazonaws.com
variables:
region:
default: us-east-1
security:
- sigv4_internetmonitor: []
/v20210603/Monitors/{MonitorName}/Queries/{QueryId}:
delete:
operationId: StopQuery
summary: Stop Query
description: Stop a query that is progress for a specific monitor.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/StopQueryOutput'
'403':
description: AccessDeniedException; LimitExceededException
content:
application/json:
schema:
$ref: '#/components/schemas/AccessDeniedException'
'500':
description: InternalServerException
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerException'
'429':
description: ThrottlingException
content:
application/json:
schema:
$ref: '#/components/schemas/InternetmonitorThrottlingException'
'400':
description: ValidationException
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationException'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/StopQueryInput'
tags:
- Query
servers:
- url: https://internetmonitor.{region}.amazonaws.com
variables:
region:
default: us-east-1
security:
- sigv4_internetmonitor: []
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: logs
sigv4_internetmonitor:
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: internetmonitor
schemas:
AccessDeniedException:
type: object
properties:
message:
type: string
DescribeQueriesRequest:
type: object
properties:
logGroupName:
type: string
description: Limits the returned queries to only those for the specified log group.
status:
type: string
enum:
- Scheduled
- Running
- Complete
- Failed
- Cancelled
- Timeout
- Unknown
description: Limits the returned queries to only those that have the specified status. Valid values are Cancelled,
Complete, Failed, Running, and Scheduled.
maxResults:
type: integer
description: Limits the number of returned queries to the specified number.
nextToken:
type: string
queryLanguage:
type: string
enum:
- CWLI
- SQL
- PPL
description: Limits the returned queries to only the queries that use the specified query language.
DescribeQueriesResponse:
type: object
properties:
queries:
type: array
items:
$ref: '#/components/schemas/QueryInfo'
description: The list of queries that match the request.
nextToken:
type: string
FilterParameter:
type: object
properties:
Field:
type: string
description: A data field that you want to filter, to further scope your application's Internet Monitor data in
a repository that you created by running a query. A field might be city, for example. The field must be one of
the fields that was returned by the specific query that you used to create the repository.
Operator:
type: string
description: The operator to use with the filter field and a value, such as not_equals.
Values:
type: array
items:
type: string
description: One or more values to be used, together with the specified operator, to filter data for a query. For
example, you could specify an array of values such as ["Seattle", "Redmond"]. Values in the array are separated
by commas.
InternalServerException:
type: object
properties:
message:
type: string
InternetmonitorThrottlingException:
type: object
properties:
message:
type: string
InvalidParameterException:
type: object
properties:
message:
type: string
QueryInfo:
type: object
properties:
queryLanguage:
type: string
enum:
- CWLI
- SQL
- PPL
description: The query language used for this query. For more information about the query languages that CloudWatch
Logs supports, see Supported query languages.
queryId:
type: string
description: The unique ID number of this query.
queryString:
type: string
description: The query string used in this query.
status:
type: string
enum:
- Scheduled
- Running
- Complete
- Failed
- Cancelled
- Timeout
- Unknown
description: The status of this query. Possible values are Cancelled, Complete, Failed, Running, Scheduled, and
Unknown.
createTime:
type: integer
description: The date and time that this query was created.
logGroupName:
type: string
description: The name of the log group scanned by this query.
queryDuration:
type: integer
description: The duration in milliseconds that the query took to execute.
bytesScanned:
type: number
description: The total number of bytes scanned by the query. This indicates the cost associated with the query.
userIdentity:
type: string
description: The ARN of the user who ran the query.
ServiceUnavailableException:
type: object
properties:
message:
type: string
StartQueryInput:
type: object
properties:
MonitorName:
type: string
description: The name of the monitor to query.
StartTime:
type: string
description: The timestamp that is the beginning of the period that you want to retrieve data for with your query.
EndTime:
type: string
description: The timestamp that is the end of the period that you want to retrieve data for with your query.
QueryType:
type: string
description: 'The type of query to run. The following are the three types of queries that you can run using the
Internet Monitor query interface: MEASUREMENTS: Provides availability score, performance score, total traffic,
and round-trip times, at 5 minute intervals. TOP_LOCATIONS: Provides availability score, performance score, total
traffic, and time to first byte (TTFB) information, for the top location and ASN combinations that you''re monitoring,
by traffic volume. TOP_LOCATION_DETAILS: Provides TTFB for Amazon CloudFront, your current configuration, and
the best performing EC2 configuration, at 1 hour '
FilterParameters:
type: array
items:
$ref: '#/components/schemas/FilterParameter'
description: The FilterParameters field that you use with Amazon CloudWatch Internet Monitor queries is a string
the defines how you want a query to be filtered. The filter parameters that you can specify depend on the query
type, since each query type returns a different set of Internet Monitor data. For more information about specifying
filter parameters, see Using the Amazon CloudWatch Internet Monitor query interface in the Amazon CloudWatch Internet
Monitor User Guide.
LinkedAccountId:
type: string
description: The account ID for an account that you've set up cross-account sharing for in Amazon CloudWatch Internet
Monitor. You configure cross-account sharing by using Amazon CloudWatch Observability Access Manager. For more
information, see Internet Monitor cross-account observability in the Amazon CloudWatch Internet Monitor User Guide.
required:
- MonitorName
- StartTime
- EndTime
- QueryType
StartQueryOutput:
type: object
properties:
QueryId:
type: string
description: The internally-generated identifier of a specific query.
required:
- QueryId
StartQueryRequest:
type: object
properties:
queryLanguage:
type: string
enum:
- CWLI
- SQL
- PPL
description: Specify the query language to use for this query. The options are Logs Insights QL, OpenSearch PPL,
and OpenSearch SQL. For more information about the query languages that CloudWatch Logs supports, see Supported
query languages.
logGroupName:
type: string
description: 'The log group on which to perform the query. A StartQuery operation must include exactly one of the
following parameters: logGroupName, logGroupNames, or logGroupIdentifiers. The exception is queries using the
OpenSearch Service SQL query language, where you specify the log group names inside the querystring instead of
here.'
logGroupNames:
type: array
items:
type: string
description: 'The list of log groups to be queried. You can include up to 50 log groups. A StartQuery operation
must include exactly one of the following parameters: logGroupName, logGroupNames, or logGroupIdentifiers. The
exception is queries using the OpenSearch Service SQL query language, where you specify the log group names inside
the querystring instead of here.'
logGroupIdentifiers:
type: array
items:
type: string
description: 'The list of log groups to query. You can include up to 50 log groups. You can specify them by the
log group name or ARN. If a log group that you''re querying is in a source account and you''re using a monitoring
account, you must specify the ARN of the log group here. The query definition must also be defined in the monitoring
account. If you specify an ARN, use the format arn:aws:logs:region:account-id:log-group:log_group_name Don''t
include an * at the end. A StartQuery operation must include exactly one of the following parameters: logGroupName,
logGroupNames, or logGroupIdentifiers. The excep'
startTime:
type: integer
description: The beginning of the time range to query. The range is inclusive, so the specified start time is included
in the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
endTime:
type: integer
description: The end of the time range to query. The range is inclusive, so the specified end time is included in
the query. Specified as epoch time, the number of seconds since January 1, 1970, 00:00:00 UTC.
queryString:
type: string
description: The query string to use. For more information, see CloudWatch Logs Insights Query Syntax.
limit:
type: integer
description: The maximum number of log events to return from the query. The maximum limit is 100,000. The maximum
events returned in a single GetQueryResults API call is 10,000 log events per request. You can retrieve up to
100,000 log event results from a query by paginating with the nextToken. 100,000 limit is only supported for Logs
Insights QL and is currently not supported for PPL and SQL query languages.
required:
- startTime
- endTime
- queryString
StartQueryResponse:
type: object
properties:
queryId:
type: string
description: The unique ID of the query.
StopQueryInput:
type: object
properties:
MonitorName:
type: string
description: The name of the monitor.
QueryId:
type: string
description: The ID of the query that you want to stop. A QueryId is an internally-generated identifier for a specific
query.
required:
- MonitorName
- QueryId
StopQueryOutput:
type: object
properties: {}
StopQueryRequest:
type: object
properties:
queryId:
type: string
description: The ID number of the query to stop. To find this ID number, use DescribeQueries.
required:
- queryId
StopQueryResponse:
type: object
properties:
success:
type: boolean
description: This is true if the query was stopped by the StopQuery operation.
ValidationException:
type: object
properties:
message:
type: string
x-provenance:
method: harvested
publisher: Amazon Web Services
source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/cloudwatch-logs/service/2014-03-28/cloudwatch-logs-2014-03-28.json
note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)
sources:
- https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/cloudwatch-logs/service/2014-03-28/cloudwatch-logs-2014-03-28.json
- https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/internetmonitor/service/2021-06-03/internetmonitor-2021-06-03.json