{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"Executes a SQL query against the analytics datasets available to the caller. Send either raw SQL or a JSON object containing the query and optional positional or named parameters, time range, and account or zone scope. Raw SQL placeholders can also be bound with query parameters named `param_<name>`. A trailing `FORMAT JSON`, `FORMAT JSONEachRow`, `FORMAT TabSeparated`, or `FORMAT TSV` is supported for all datasets. Without FORMAT, each backend retains its existing default JSON response.\n","properties":{"body":{"$ref":"#/definitions/analytics-sql_SqlQueryRequest"}},"required":["body"],"additionalProperties":false,"definitions":{"analytics-sql_SqlQueryRequest":{"type":"object","properties":{"params":{"description":"Positional array values for `$1`, `$2`, and similar placeholders, or named object values for placeholders such as `$status`.\n","oneOf":[{"items":{"oneOf":[{"type":["string","null"]},{"type":"number"},{"type":"boolean"}]},"type":"array"},{"additionalProperties":true,"type":"object"}]},"query":{"description":"SQL query to execute. A trailing FORMAT selects JSON, JSONEachRow, TabSeparated, or TSV output on any dataset.\n","type":"string"},"scope":{"$ref":"#/definitions/analytics-sql_SqlQueryScope"},"time_range":{"allOf":[{"$ref":"#/definitions/analytics-sql_SqlQueryTimeRange"}]}},"additionalProperties":false,"required":["query"],"examples":[{"params":{"status":404},"query":"SELECT edgeResponseStatus FROM events.httpRequests WHERE edgeResponseStatus = $status LIMIT 10","scope":{"accountTag":"0123456789abcdef0123456789abcdef"},"time_range":{"end":"2026-01-02T00:00:00Z","start":"2026-01-01T00:00:00Z"}}]},"analytics-sql_SqlQueryScope":{"description":"Account or zone scope applied to the query. Include exactly one scope tag. Do not include account or zone tenancy predicates in the SQL query when this field is present.\n","oneOf":[{"$ref":"#/definitions/analytics-sql_SqlQueryAccountScope"},{"$ref":"#/definitions/analytics-sql_SqlQueryZoneScope"}]},"analytics-sql_SqlQueryTimeRange":{"description":"Time bounds applied to the dataset's timestamp column. Do not include timestamp predicates in the SQL query when this field is present.\n","type":"object","properties":{"end":{"description":"Inclusive upper bound for the dataset's timestamp column.","type":"string","examples":["2026-01-02T00:00:00Z"]},"start":{"description":"Inclusive lower bound for the dataset's timestamp column.","type":"string","examples":["2026-01-01T00:00:00Z"]}},"additionalProperties":false,"required":["start"]},"analytics-sql_SqlQueryAccountScope":{"type":"object","properties":{"accountTag":{"description":"Account tag used to authorize and scope the query. Must be a 32-character lowercase hex string.\n","type":"string","pattern":"^[0-9a-f]{32}$","examples":["0123456789abcdef0123456789abcdef"]}},"additionalProperties":false,"required":["accountTag"]},"analytics-sql_SqlQueryZoneScope":{"type":"object","properties":{"zoneTag":{"description":"Zone tag used to authorize and scope the query. Must be a 32-character lowercase hex string.\n","type":"string","pattern":"^[0-9a-f]{32}$","examples":["023e105f2fd349899d7634a245f8ca0f"]}},"additionalProperties":false,"required":["zoneTag"]}}},"name":"Query analytics datasets","id":"cloudflare.sql-api-query-post","example":{"body":{"params":{"status":404},"query":"SELECT edgeResponseStatus FROM events.httpRequests WHERE edgeResponseStatus = $status LIMIT 10","scope":{"accountTag":"0123456789abcdef0123456789abcdef"},"time_range":{"end":"2026-01-02T00:00:00Z","start":"2026-01-01T00:00:00Z"}}},"maxRequests":1,"summary":false}}