Skip to content

describe_query

Operation

describe_query

describe_query(request: DescribeQueryInput | DescribeQueryInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[DescribeQueryInputDict]) -> DescribeQueryOutput
Warning

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.

Parameters:

Name Type Description Default
request DescribeQueryInput | DescribeQueryInputDict | None

The input as a model or dictionary. Pass this or keyword arguments, not both.

None
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

None
**kwargs Unpack[DescribeQueryInputDict]

The input fields as keyword arguments.

{}

Returns:

Type Description
DescribeQueryOutput

An instance of DescribeQueryOutput.

describe_query async

describe_query(request: DescribeQueryInput | DescribeQueryInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[DescribeQueryInputDict]) -> DescribeQueryOutput
Warning

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.

Parameters:

Name Type Description Default
request DescribeQueryInput | DescribeQueryInputDict | None

The input as a model or dictionary. Pass this or keyword arguments, not both.

None
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

None
**kwargs Unpack[DescribeQueryInputDict]

The input fields as keyword arguments.

{}

Returns:

Type Description
DescribeQueryOutput

An instance of DescribeQueryOutput.

Input

Pass the input as keyword arguments, a positional dictionary, or a positional model object. Pass plugins separately as a keyword argument.

DescribeQueryInputDict

Bases: TypedDict

Dictionary form of DescribeQueryInput.

Attributes

event_data_store instance-attribute
event_data_store: str | None

The ARN (or the ID suffix of the ARN) of an event data store on which the specified query was run.

event_data_store_owner_account_id instance-attribute
event_data_store_owner_account_id: str | None

The account ID of the event data store owner.

query_alias instance-attribute
query_alias: str | None

The alias that identifies a query template.

query_id instance-attribute
query_id: str | None

The query ID.

refresh_id instance-attribute
refresh_id: str | None

The ID of the dashboard refresh.

DescribeQueryInput dataclass

Bases: _SerdeShape

Dataclass for DescribeQueryInput structure.

Attributes

event_data_store class-attribute instance-attribute
event_data_store: str | None = ...

The ARN (or the ID suffix of the ARN) of an event data store on which the specified query was run.

event_data_store_owner_account_id class-attribute instance-attribute
event_data_store_owner_account_id: str | None = ...

The account ID of the event data store owner.

query_alias class-attribute instance-attribute
query_alias: str | None = ...

The alias that identifies a query template.

query_id class-attribute instance-attribute
query_id: str | None = ...

The query ID.

refresh_id class-attribute instance-attribute
refresh_id: str | None = ...

The ID of the dashboard refresh.

Output

DescribeQueryOutput dataclass

Bases: _SerdeShape

Dataclass for DescribeQueryOutput structure.

Attributes

delivery_s3_uri class-attribute instance-attribute
delivery_s3_uri: str | None = ...

The URI for the S3 bucket where CloudTrail delivered query results, if applicable.

delivery_status class-attribute instance-attribute
delivery_status: str | None = ...

The delivery status.

error_message class-attribute instance-attribute
error_message: str | None = ...

The error message returned if a query failed.

event_data_store_owner_account_id class-attribute instance-attribute
event_data_store_owner_account_id: str | None = ...

The account ID of the event data store owner.

prompt class-attribute instance-attribute
prompt: str | None = ...

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.

query_id class-attribute instance-attribute
query_id: str | None = ...

The ID of the query.

query_statistics class-attribute instance-attribute
query_statistics: QueryStatisticsForDescribeQuery | None = ...

Metadata about a query, including the number of events that were matched, the total number of events scanned, the query run time in milliseconds, and the query's creation time.

query_status class-attribute instance-attribute
query_status: str | None = ...

The status of a query. Values for QueryStatus include QUEUED, RUNNING, FINISHED, FAILED, TIMED_OUT, or CANCELLED

query_string class-attribute instance-attribute
query_string: str | None = ...

The SQL code of a query.

response_metadata class-attribute instance-attribute
response_metadata: ResponseMetadata = ...

Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.