Run CloudWatch Logs Insights queries programmatically via the AWS API
domain: docs.aws.amazon.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Start a query by calling 'StartQuery' API (or 'aws logs start-query' CLI) with 'logGroupNames' array, 'startTime' and 'endTime' (Unix epoch milliseconds), 'queryString' in Logs Insights syntax, and optional 'limit'
Poll for results by calling 'GetQueryResults' with the 'queryId' returned by StartQuery; repeat until the 'status' field returns 'Complete' (also possible: 'Failed', 'Cancelled', 'Timeout')
Parse the results array where each element is an array of '{field, value}' objects; the special '@message', '@timestamp', '@logStream', and '@log' fields are always available
Use Logs Insights query syntax: 'fields', 'filter', 'stats', 'sort', 'limit', and 'parse' commands — for example 'fields @timestamp, @message | filter @message like /ERROR/ | stats count() by bin(5m)'
For recurring analysis consider exporting results to S3 via 'CreateExportTask' or schedule queries using EventBridge to trigger a Lambda that calls StartQuery/GetQueryResults
Known gotchas
Queries are asynchronous; the result is not available immediately after StartQuery returns — polling GetQueryResults is required and queries against large log groups can take minutes
The default result limit is 1000 log events; queries that would return more records are silently truncated — use 'stats' aggregations rather than raw 'fields' retrieval for large datasets
Logs Insights queries incur data scanned costs per GB; broad time ranges over high-volume log groups can generate significant unexpected charges — always scope queries with specific time ranges and filters
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?