Run a query
workers.observability.telemetry.query(TelemetryQueryParams**kwargs) -> TelemetryQueryResponse
POST/accounts/{account_id}/workers/observability/telemetry/query
Run a temporary or saved query.
Security
API Email + API Key
The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.
Example:
The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.
Example:
API Token
The preferred authorization scheme for interacting with the Cloudflare API. Create a token.
Example:
User Service Key
Used when interacting with the Origin CA certificates API. View/change your key.
Example:
Accepted Permissions (at least one required)
Parameters
query_id: str
Identifier for the query. When parameters are omitted, this ID is used to load a previously saved query’s parameters. When providing parameters inline, pass any identifier (e.g. an ad-hoc ID).
granularity: Optional[float]
Number of time-series buckets. Only used when view is ‘calculations’. Omit to let the system auto-detect an appropriate granularity.
When true, omits time-series data from the response and returns only aggregated values. Reduces response size when series are not needed.
limit: Optional[float]
Maximum number of events to return when view is ‘events’. Also controls the number of group-by rows when view is ‘calculations’.
maximum2000
offset: Optional[str]
Cursor for pagination in event, trace, invocation, and agent views. Pass the $metadata.id of the last event, the trace cursor, or AgentRun.id to fetch the next page.
Run a query
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_email=os.environ.get("CLOUDFLARE_EMAIL"), # This is the default and can be omitted
api_key=os.environ.get("CLOUDFLARE_API_KEY"), # This is the default and can be omitted
)
response = client.workers.observability.telemetry.query(
account_id="account_id",
query_id="queryId",
timeframe={
"from": 0,
"to": 0,
},
)
print(response.run){
"errors": [
{
"message": "message"
}
],
"messages": [
{
"message": "Successful request"
}
],
"result": {
"run": {
"id": "id",
"accountId": "accountId",
"dry": true,
"granularity": 0,
"query": {
"id": "id",
"adhoc": true,
"created": "string",
"createdBy": "createdBy",
"description": "Query description",
"name": "x",
"parameters": {
"calculations": [
{
"operator": "count",
"alias": "alias",
"key": "key",
"keyType": "string"
}
],
"datasets": [
"string"
],
"filterCombination": "and",
"filters": [
{
"filterCombination": "and",
"filters": [
{}
],
"kind": "group"
}
],
"groupBys": [
{
"type": "string",
"value": "value"
}
],
"havings": [
{
"key": "key",
"operation": "eq",
"value": 0
}
],
"limit": 0,
"needle": {
"value": {
"0": "s",
"1": "t",
"2": "r",
"3": "i",
"4": "n",
"5": "g"
},
"isRegex": true,
"matchCase": true
},
"orderBy": {
"value": "value",
"order": "asc"
}
},
"updated": "string",
"updatedBy": "updatedBy"
},
"status": "STARTED",
"timeframe": {
"from": 0,
"to": 0
},
"userId": "userId",
"created": "created",
"statistics": {
"bytes_read": 0,
"elapsed": 0,
"rows_read": 0,
"abr_level": 0
},
"updated": "updated"
},
"statistics": {
"bytes_read": 0,
"elapsed": 0,
"rows_read": 0,
"abr_level": 0
},
"agents": [
{
"id": "id",
"errors": [
"string"
],
"models": [
"string"
],
"providers": [
"string"
],
"services": [
"string"
],
"spans": 0,
"status": "completed",
"traceDurationMs": 0,
"traceEndMs": 0,
"traceId": "traceId",
"traceStartMs": 0,
"agentId": "agentId",
"agentName": "agentName",
"conversationId": "conversationId",
"inputTokens": 0,
"outputTokens": 0
}
],
"calculations": [
{
"aggregates": [
{
"count": 0,
"interval": 0,
"sampleInterval": 0,
"value": 0,
"groups": [
{
"key": "key",
"value": "string"
}
]
}
],
"calculation": "calculation",
"series": [
{
"data": [
{
"count": 0,
"interval": 0,
"sampleInterval": 0,
"value": 0,
"firstSeen": "firstSeen",
"groups": [
{
"key": "key",
"value": "string"
}
],
"lastSeen": "lastSeen"
}
],
"time": "time"
}
],
"alias": "alias"
}
],
"compare": [
{
"aggregates": [
{
"count": 0,
"interval": 0,
"sampleInterval": 0,
"value": 0,
"groups": [
{
"key": "key",
"value": "string"
}
]
}
],
"calculation": "calculation",
"series": [
{
"data": [
{
"count": 0,
"interval": 0,
"sampleInterval": 0,
"value": 0,
"firstSeen": "firstSeen",
"groups": [
{
"key": "key",
"value": "string"
}
],
"lastSeen": "lastSeen"
}
],
"time": "time"
}
],
"alias": "alias"
}
],
"distribution": {
"bins": [
"string"
],
"bucketBoundaries": [
0
],
"bucketMode": "log",
"buckets": [
"string"
],
"matrix": [
[
0
]
]
},
"events": {
"count": 0,
"events": [
{
"$metadata": {
"id": "id",
"account": "account",
"cloudService": "cloudService",
"coldStart": 1,
"cost": 1,
"duration": 1,
"endTime": 0,
"endTimeNs": "endTimeNs",
"error": "error",
"errorTemplate": "errorTemplate",
"fingerprint": "fingerprint",
"level": "level",
"message": "message",
"messageTemplate": "messageTemplate",
"metricName": "metricName",
"origin": "origin",
"parentSpanId": "parentSpanId",
"provider": "provider",
"rayId": "rayId",
"region": "region",
"requestId": "requestId",
"service": "service",
"spanId": "spanId",
"spanName": "spanName",
"stackId": "stackId",
"startTime": 0,
"startTimeNs": "startTimeNs",
"statusCode": 1,
"timestampNs": "timestampNs",
"traceDuration": 1,
"traceId": "traceId",
"transactionName": "transactionName",
"trigger": "trigger",
"type": "type",
"url": "url"
},
"dataset": "dataset",
"source": "string",
"timestamp": 0,
"$containers": {
"foo": "bar"
},
"$workers": {
"eventType": "fetch",
"scriptName": "scriptName",
"durableObjectId": "durableObjectId",
"entrypoint": "entrypoint",
"event": {
"foo": "bar"
},
"executionModel": "durableObject",
"outcome": "outcome",
"preview": {
"id": "id",
"name": "name",
"slug": "slug"
},
"requestId": "requestId",
"scriptVersion": {
"id": "id",
"message": "message",
"tag": "tag"
},
"spanId": "spanId",
"traceId": "traceId",
"truncated": true
}
}
],
"fields": [
{
"key": "key",
"type": "type"
}
],
"series": [
{
"data": [
{
"aggregates": {
"_count": 1,
"_interval": 1,
"_firstSeen": "_firstSeen",
"_lastSeen": "_lastSeen",
"bin": {}
},
"count": 0,
"interval": 0,
"sampleInterval": 0,
"errors": 0,
"groups": {
"foo": "string"
}
}
],
"time": "time"
}
]
},
"invocations": {
"foo": [
{
"$metadata": {
"id": "id",
"account": "account",
"cloudService": "cloudService",
"coldStart": 1,
"cost": 1,
"duration": 1,
"endTime": 0,
"endTimeNs": "endTimeNs",
"error": "error",
"errorTemplate": "errorTemplate",
"fingerprint": "fingerprint",
"level": "level",
"message": "message",
"messageTemplate": "messageTemplate",
"metricName": "metricName",
"origin": "origin",
"parentSpanId": "parentSpanId",
"provider": "provider",
"rayId": "rayId",
"region": "region",
"requestId": "requestId",
"service": "service",
"spanId": "spanId",
"spanName": "spanName",
"stackId": "stackId",
"startTime": 0,
"startTimeNs": "startTimeNs",
"statusCode": 1,
"timestampNs": "timestampNs",
"traceDuration": 1,
"traceId": "traceId",
"transactionName": "transactionName",
"trigger": "trigger",
"type": "type",
"url": "url"
},
"dataset": "dataset",
"source": "string",
"timestamp": 0,
"$containers": {
"foo": "bar"
},
"$workers": {
"eventType": "fetch",
"scriptName": "scriptName",
"durableObjectId": "durableObjectId",
"entrypoint": "entrypoint",
"event": {
"foo": "bar"
},
"executionModel": "durableObject",
"outcome": "outcome",
"preview": {
"id": "id",
"name": "name",
"slug": "slug"
},
"requestId": "requestId",
"scriptVersion": {
"id": "id",
"message": "message",
"tag": "tag"
},
"spanId": "spanId",
"traceId": "traceId",
"truncated": true
}
}
]
},
"traces": [
{
"rootSpanName": "rootSpanName",
"rootTransactionName": "rootTransactionName",
"service": [
"string"
],
"spans": 0,
"traceDurationMs": 0,
"traceEndMs": 0,
"traceId": "traceId",
"traceStartMs": 0,
"errors": [
"string"
]
}
]
},
"success": true
}Returns Examples
{
"errors": [
{
"message": "message"
}
],
"messages": [
{
"message": "Successful request"
}
],
"result": {
"run": {
"id": "id",
"accountId": "accountId",
"dry": true,
"granularity": 0,
"query": {
"id": "id",
"adhoc": true,
"created": "string",
"createdBy": "createdBy",
"description": "Query description",
"name": "x",
"parameters": {
"calculations": [
{
"operator": "count",
"alias": "alias",
"key": "key",
"keyType": "string"
}
],
"datasets": [
"string"
],
"filterCombination": "and",
"filters": [
{
"filterCombination": "and",
"filters": [
{}
],
"kind": "group"
}
],
"groupBys": [
{
"type": "string",
"value": "value"
}
],
"havings": [
{
"key": "key",
"operation": "eq",
"value": 0
}
],
"limit": 0,
"needle": {
"value": {
"0": "s",
"1": "t",
"2": "r",
"3": "i",
"4": "n",
"5": "g"
},
"isRegex": true,
"matchCase": true
},
"orderBy": {
"value": "value",
"order": "asc"
}
},
"updated": "string",
"updatedBy": "updatedBy"
},
"status": "STARTED",
"timeframe": {
"from": 0,
"to": 0
},
"userId": "userId",
"created": "created",
"statistics": {
"bytes_read": 0,
"elapsed": 0,
"rows_read": 0,
"abr_level": 0
},
"updated": "updated"
},
"statistics": {
"bytes_read": 0,
"elapsed": 0,
"rows_read": 0,
"abr_level": 0
},
"agents": [
{
"id": "id",
"errors": [
"string"
],
"models": [
"string"
],
"providers": [
"string"
],
"services": [
"string"
],
"spans": 0,
"status": "completed",
"traceDurationMs": 0,
"traceEndMs": 0,
"traceId": "traceId",
"traceStartMs": 0,
"agentId": "agentId",
"agentName": "agentName",
"conversationId": "conversationId",
"inputTokens": 0,
"outputTokens": 0
}
],
"calculations": [
{
"aggregates": [
{
"count": 0,
"interval": 0,
"sampleInterval": 0,
"value": 0,
"groups": [
{
"key": "key",
"value": "string"
}
]
}
],
"calculation": "calculation",
"series": [
{
"data": [
{
"count": 0,
"interval": 0,
"sampleInterval": 0,
"value": 0,
"firstSeen": "firstSeen",
"groups": [
{
"key": "key",
"value": "string"
}
],
"lastSeen": "lastSeen"
}
],
"time": "time"
}
],
"alias": "alias"
}
],
"compare": [
{
"aggregates": [
{
"count": 0,
"interval": 0,
"sampleInterval": 0,
"value": 0,
"groups": [
{
"key": "key",
"value": "string"
}
]
}
],
"calculation": "calculation",
"series": [
{
"data": [
{
"count": 0,
"interval": 0,
"sampleInterval": 0,
"value": 0,
"firstSeen": "firstSeen",
"groups": [
{
"key": "key",
"value": "string"
}
],
"lastSeen": "lastSeen"
}
],
"time": "time"
}
],
"alias": "alias"
}
],
"distribution": {
"bins": [
"string"
],
"bucketBoundaries": [
0
],
"bucketMode": "log",
"buckets": [
"string"
],
"matrix": [
[
0
]
]
},
"events": {
"count": 0,
"events": [
{
"$metadata": {
"id": "id",
"account": "account",
"cloudService": "cloudService",
"coldStart": 1,
"cost": 1,
"duration": 1,
"endTime": 0,
"endTimeNs": "endTimeNs",
"error": "error",
"errorTemplate": "errorTemplate",
"fingerprint": "fingerprint",
"level": "level",
"message": "message",
"messageTemplate": "messageTemplate",
"metricName": "metricName",
"origin": "origin",
"parentSpanId": "parentSpanId",
"provider": "provider",
"rayId": "rayId",
"region": "region",
"requestId": "requestId",
"service": "service",
"spanId": "spanId",
"spanName": "spanName",
"stackId": "stackId",
"startTime": 0,
"startTimeNs": "startTimeNs",
"statusCode": 1,
"timestampNs": "timestampNs",
"traceDuration": 1,
"traceId": "traceId",
"transactionName": "transactionName",
"trigger": "trigger",
"type": "type",
"url": "url"
},
"dataset": "dataset",
"source": "string",
"timestamp": 0,
"$containers": {
"foo": "bar"
},
"$workers": {
"eventType": "fetch",
"scriptName": "scriptName",
"durableObjectId": "durableObjectId",
"entrypoint": "entrypoint",
"event": {
"foo": "bar"
},
"executionModel": "durableObject",
"outcome": "outcome",
"preview": {
"id": "id",
"name": "name",
"slug": "slug"
},
"requestId": "requestId",
"scriptVersion": {
"id": "id",
"message": "message",
"tag": "tag"
},
"spanId": "spanId",
"traceId": "traceId",
"truncated": true
}
}
],
"fields": [
{
"key": "key",
"type": "type"
}
],
"series": [
{
"data": [
{
"aggregates": {
"_count": 1,
"_interval": 1,
"_firstSeen": "_firstSeen",
"_lastSeen": "_lastSeen",
"bin": {}
},
"count": 0,
"interval": 0,
"sampleInterval": 0,
"errors": 0,
"groups": {
"foo": "string"
}
}
],
"time": "time"
}
]
},
"invocations": {
"foo": [
{
"$metadata": {
"id": "id",
"account": "account",
"cloudService": "cloudService",
"coldStart": 1,
"cost": 1,
"duration": 1,
"endTime": 0,
"endTimeNs": "endTimeNs",
"error": "error",
"errorTemplate": "errorTemplate",
"fingerprint": "fingerprint",
"level": "level",
"message": "message",
"messageTemplate": "messageTemplate",
"metricName": "metricName",
"origin": "origin",
"parentSpanId": "parentSpanId",
"provider": "provider",
"rayId": "rayId",
"region": "region",
"requestId": "requestId",
"service": "service",
"spanId": "spanId",
"spanName": "spanName",
"stackId": "stackId",
"startTime": 0,
"startTimeNs": "startTimeNs",
"statusCode": 1,
"timestampNs": "timestampNs",
"traceDuration": 1,
"traceId": "traceId",
"transactionName": "transactionName",
"trigger": "trigger",
"type": "type",
"url": "url"
},
"dataset": "dataset",
"source": "string",
"timestamp": 0,
"$containers": {
"foo": "bar"
},
"$workers": {
"eventType": "fetch",
"scriptName": "scriptName",
"durableObjectId": "durableObjectId",
"entrypoint": "entrypoint",
"event": {
"foo": "bar"
},
"executionModel": "durableObject",
"outcome": "outcome",
"preview": {
"id": "id",
"name": "name",
"slug": "slug"
},
"requestId": "requestId",
"scriptVersion": {
"id": "id",
"message": "message",
"tag": "tag"
},
"spanId": "spanId",
"traceId": "traceId",
"truncated": true
}
}
]
},
"traces": [
{
"rootSpanName": "rootSpanName",
"rootTransactionName": "rootTransactionName",
"service": [
"string"
],
"spans": 0,
"traceDurationMs": 0,
"traceEndMs": 0,
"traceId": "traceId",
"traceStartMs": 0,
"errors": [
"string"
]
}
]
},
"success": true
}
