查询 API

向以下地址发送 GET 或 POST 请求：

https://api.cloudflare.com/client/v4/analytics/sql

每个请求都包含 Authorization: Bearer <API_TOKEN> 标头。

Cloudflare 建议使用带 JSON 正文的 POST。POST 也接受原始 SQL，GET 在 query 查询参数中接受 SQL。

JSON 请求

推荐的请求格式是 JSON 对象：

{
	"query": "SELECT timestamp, clientRequestHttpHost FROM events.httpRequests WHERE accountTag = $1 AND timestamp >= $2 LIMIT 100",
	"params": ["<ACCOUNT_TAG>", "2026-09-15T00:00:00Z"]
}

请求对象支持以下字段：

字段	类型	必填	描述
`query`	string	是	一条 SQL `SELECT` 语句。
`params`	array or object	否	`query` 中位置或命名占位符的值。
`scope`	object	否	在 SQL 之外提供的账户或 zone 范围。
`time_range`	object	否	在 SQL 语句之外提供的时间范围。

参数

使用参数，而不是将用户提供的值插入 SQL 文本。参数将值与 SQL 语法分开。

将 $1、$2 及后续占位符与数组一起使用：

{
	"query": "SELECT timestamp FROM events.httpRequests WHERE accountTag = $1 AND timestamp >= $2 LIMIT 10",
	"params": ["<ACCOUNT_TAG>", "2026-09-15T00:00:00Z"]
}

将 $name 占位符与对象一起使用：

{
	"query": "SELECT timestamp FROM events.httpRequests WHERE accountTag = $account AND timestamp >= $start LIMIT 10",
	"params": {
		"account": "<ACCOUNT_TAG>",
		"start": "2026-09-15T00:00:00Z"
	}
}

参数值可以是字符串、数字、布尔值或 null。API 会从表达式推断所需类型。每个占位符都必须有对应的值。

对于 GET 和原始 SQL POST 请求，使用名为 param_<NAME> 的 URL 查询参数绑定占位符。例如，param_status=404 绑定 $status，param_1=404 绑定 $1。重复的参数名会被拒绝。不要将 URL 参数与 JSON 正文中的 params 组合使用。

请求级范围

你可以在 SQL 语句之外提供账户或 zone 范围。这使应用程序能够复用 SQL，而无需嵌入租户谓词。

使用 accountTag 表示账户范围：

{
	"query": "SELECT edgeResponseStatus AS status, COUNT(*) AS requests FROM events.httpRequests WHERE timestamp >= $start GROUP BY edgeResponseStatus",
	"params": {
		"start": "<START_TIME>"
	},
	"scope": {
		"accountTag": "<ACCOUNT_TAG>"
	}
}

使用 zoneTag 表示 zone 范围：

{
	"query": "SELECT COUNT(*) AS requests FROM events.httpRequests WHERE timestamp >= $start",
	"params": {
		"start": "<START_TIME>"
	},
	"scope": {
		"zoneTag": "<ZONE_TAG>"
	}
}

包含 zoneTag 的查询（包括请求级 zone 范围）需要每个命名 zone 的 Zone Analytics Read 权限，或其所属账户的 Account Analytics Read 权限。

scope 对象必须恰好包含 accountTag 或 zoneTag 之一。不要将请求级范围与 SQL 中的 accountTag、zoneTag 或资源租户谓词组合使用。如果请求在两处都指定租户，API 会返回 HTTP 422。

账户和 zone tag 必须是 32 个字符的小写十六进制字符串。

请求级范围仅适用于 JSON 请求格式。

请求级时间范围

你可以在 SQL 语句之外提供时间范围。当应用程序与已保存 SQL 分开控制查询窗口时，这很有用。

{
	"query": "SELECT edgeResponseStatus AS status, COUNT(*) AS requests FROM events.httpRequests WHERE accountTag = $account GROUP BY edgeResponseStatus",
	"params": {
		"account": "<ACCOUNT_TAG>"
	},
	"time_range": {
		"start": "2026-09-15T00:00:00Z",
		"end": "2026-09-15T01:00:00Z"
	}
}

start 值是必填的。end 值是可选的。两个边界都是包含的。

不要将 time_range 与 SQL 中的时间谓词组合使用。API 会拒绝在两处都指定时间范围的请求。

原始 SQL 请求

API 也接受将 SQL 文本作为请求正文：

curl "https://api.cloudflare.com/client/v4/analytics/sql" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --data "SELECT COUNT(*) AS requests FROM events.httpRequests WHERE accountTag = '<ACCOUNT_TAG>' AND timestamp >= NOW() - INTERVAL '1' HOUR"

原始 SQL 请求可以使用 URL 参数绑定：

curl --get "https://api.cloudflare.com/client/v4/analytics/sql" \
  --header "Authorization: Bearer <API_TOKEN>" \
  --data-urlencode 'query=SELECT COUNT(*) AS requests FROM events.httpRequests WHERE accountTag = $account AND timestamp >= $start' \
  --data-urlencode "param_account=<ACCOUNT_TAG>" \
  --data-urlencode "param_start=<START_TIME>"

对于原始 SQL POST，将 SQL 放在请求正文中，并使用相同的 param_* URL 参数传递值。当应用程序提供请求级范围或时间范围时，请使用 JSON 请求格式。

响应格式

没有 FORMAT 子句时，ClickHouse 支持的数据集返回包含 data、rows 和 statistics 的 JSON：

{
	"data": [],
	"rows": 0,
	"statistics": {
		"elapsed_ms": 12,
		"rows_read": 10000,
		"bytes_read": 720000
	}
}

字段	类型	描述
`data`	array	表示为 JSON 对象的结果行。
`rows`	integer	`data` 中的对象数量。
`statistics.elapsed_ms`	integer	数据存储执行时间（毫秒）。
`statistics.rows_read`	integer	执行查询读取的行数。
`statistics.bytes_read`	integer	执行查询读取的字节数。

执行统计不包括排队时间、重试、网络传输或客户端处理。当数据存储未报告该统计时，值可以为 0。

Log Explorer 支持的数据集返回 data 和 rows，不包含 statistics。

在查询末尾添加以下子句之一以选择显式输出格式：

子句	内容类型	输出
`FORMAT JSON`	`application/json`	带类型化 `meta`、`data`、`rows`、`rows_before_limit_at_least` 和 ClickHouse `statistics` 的 JSON。
`FORMAT JSONEachRow`	`application/x-ndjson`	每行一个 JSON 对象，没有响应信封。
`FORMAT TabSeparated`	`text/tab-separated-values`	制表符分隔的行，没有标头或响应信封。
`FORMAT TSV`	`text/tab-separated-values`	`FORMAT TabSeparated` 的别名。

对于 Log Explorer 数据集，FORMAT JSON 返回与默认响应相同的 data 和 rows 形态。它不会添加 ClickHouse 元数据或统计。

SELECT timestamp, edgeResponseStatus
FROM events.httpRequests
WHERE accountTag = '<ACCOUNT_TAG>'
  AND timestamp >= NOW() - INTERVAL '1' HOUR
LIMIT 10
FORMAT JSONEachRow