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
granularity: Optional[float]
This is only used when the view is calculations. Leaving it empty lets Workers Observability detect the correct granularity.
limit: Optional[float]
Use this limit to cap the number of events returned when the view is events.
maximum2000
offset: Optional[str]
Cursor pagination for event/trace/invocation views. Pass the last item’s $metadata.id as the next offset.
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": "created",
"createdBy": "createdBy",
"description": "Query description",
"name": "x",
"parameters": {
"calculations": [
{
"operator": "uniq",
"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": "updated",
"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": [
{
"agentClass": "agentClass",
"eventTypeCounts": {
"foo": 0
},
"firstEventMs": 0,
"hasErrors": true,
"lastEventMs": 0,
"namespace": "namespace",
"service": "service",
"totalEvents": 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"
}
],
"events": {
"count": 0,
"events": [
{
"$metadata": {
"id": "id",
"account": "account",
"cloudService": "cloudService",
"coldStart": 1,
"cost": 1,
"duration": 1,
"endTime": 0,
"error": "error",
"errorTemplate": "errorTemplate",
"fingerprint": "fingerprint",
"level": "level",
"message": "message",
"messageTemplate": "messageTemplate",
"metricName": "metricName",
"origin": "origin",
"parentSpanId": "parentSpanId",
"provider": "provider",
"region": "region",
"requestId": "requestId",
"service": "service",
"spanId": "spanId",
"spanName": "spanName",
"stackId": "stackId",
"startTime": 0,
"statusCode": 1,
"traceDuration": 1,
"traceId": "traceId",
"transactionName": "transactionName",
"trigger": "trigger",
"type": "type",
"url": "url"
},
"dataset": "dataset",
"source": "string",
"timestamp": 0,
"$containers": {},
"$workers": {
"eventType": "fetch",
"requestId": "requestId",
"scriptName": "scriptName",
"durableObjectId": "durableObjectId",
"entrypoint": "entrypoint",
"event": {
"foo": "bar"
},
"executionModel": "durableObject",
"outcome": "outcome",
"scriptVersion": {
"id": "id",
"message": "message",
"tag": "tag"
},
"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,
"error": "error",
"errorTemplate": "errorTemplate",
"fingerprint": "fingerprint",
"level": "level",
"message": "message",
"messageTemplate": "messageTemplate",
"metricName": "metricName",
"origin": "origin",
"parentSpanId": "parentSpanId",
"provider": "provider",
"region": "region",
"requestId": "requestId",
"service": "service",
"spanId": "spanId",
"spanName": "spanName",
"stackId": "stackId",
"startTime": 0,
"statusCode": 1,
"traceDuration": 1,
"traceId": "traceId",
"transactionName": "transactionName",
"trigger": "trigger",
"type": "type",
"url": "url"
},
"dataset": "dataset",
"source": "string",
"timestamp": 0,
"$containers": {},
"$workers": {
"eventType": "fetch",
"requestId": "requestId",
"scriptName": "scriptName",
"durableObjectId": "durableObjectId",
"entrypoint": "entrypoint",
"event": {
"foo": "bar"
},
"executionModel": "durableObject",
"outcome": "outcome",
"scriptVersion": {
"id": "id",
"message": "message",
"tag": "tag"
},
"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": "created",
"createdBy": "createdBy",
"description": "Query description",
"name": "x",
"parameters": {
"calculations": [
{
"operator": "uniq",
"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": "updated",
"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": [
{
"agentClass": "agentClass",
"eventTypeCounts": {
"foo": 0
},
"firstEventMs": 0,
"hasErrors": true,
"lastEventMs": 0,
"namespace": "namespace",
"service": "service",
"totalEvents": 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"
}
],
"events": {
"count": 0,
"events": [
{
"$metadata": {
"id": "id",
"account": "account",
"cloudService": "cloudService",
"coldStart": 1,
"cost": 1,
"duration": 1,
"endTime": 0,
"error": "error",
"errorTemplate": "errorTemplate",
"fingerprint": "fingerprint",
"level": "level",
"message": "message",
"messageTemplate": "messageTemplate",
"metricName": "metricName",
"origin": "origin",
"parentSpanId": "parentSpanId",
"provider": "provider",
"region": "region",
"requestId": "requestId",
"service": "service",
"spanId": "spanId",
"spanName": "spanName",
"stackId": "stackId",
"startTime": 0,
"statusCode": 1,
"traceDuration": 1,
"traceId": "traceId",
"transactionName": "transactionName",
"trigger": "trigger",
"type": "type",
"url": "url"
},
"dataset": "dataset",
"source": "string",
"timestamp": 0,
"$containers": {},
"$workers": {
"eventType": "fetch",
"requestId": "requestId",
"scriptName": "scriptName",
"durableObjectId": "durableObjectId",
"entrypoint": "entrypoint",
"event": {
"foo": "bar"
},
"executionModel": "durableObject",
"outcome": "outcome",
"scriptVersion": {
"id": "id",
"message": "message",
"tag": "tag"
},
"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,
"error": "error",
"errorTemplate": "errorTemplate",
"fingerprint": "fingerprint",
"level": "level",
"message": "message",
"messageTemplate": "messageTemplate",
"metricName": "metricName",
"origin": "origin",
"parentSpanId": "parentSpanId",
"provider": "provider",
"region": "region",
"requestId": "requestId",
"service": "service",
"spanId": "spanId",
"spanName": "spanName",
"stackId": "stackId",
"startTime": 0,
"statusCode": 1,
"traceDuration": 1,
"traceId": "traceId",
"transactionName": "transactionName",
"trigger": "trigger",
"type": "type",
"url": "url"
},
"dataset": "dataset",
"source": "string",
"timestamp": 0,
"$containers": {},
"$workers": {
"eventType": "fetch",
"requestId": "requestId",
"scriptName": "scriptName",
"durableObjectId": "durableObjectId",
"entrypoint": "entrypoint",
"event": {
"foo": "bar"
},
"executionModel": "durableObject",
"outcome": "outcome",
"scriptVersion": {
"id": "id",
"message": "message",
"tag": "tag"
},
"truncated": true
}
}
]
},
"traces": [
{
"rootSpanName": "rootSpanName",
"rootTransactionName": "rootTransactionName",
"service": [
"string"
],
"spans": 0,
"traceDurationMs": 0,
"traceEndMs": 0,
"traceId": "traceId",
"traceStartMs": 0,
"errors": [
"string"
]
}
]
},
"success": true
}