Python Cloudflare Analytics Client

A Python client for interacting with the Cloudflare GraphQL Analytics API. Simple, AI generated, hand polished.

Note: The official Cloudflare Python library does not support the GraphQL Analytics API endpoints. This library provides dedicated support for querying Cloudflare analytics data.

Installation

uv add cloudflare-analytics

Features

• Simple, clean API for Cloudflare GraphQL Analytics
• Built-in retry logic with exponential backoff
• Type-safe responses using Pydantic models
• Comprehensive error handling

Usage

There are two ways to initialize the client:

Option 1: Global Client (Recommended)

get_analytics_client returns a globally cached singleton instance. It also automatically checks for the CLOUDFLARE_API_TOKEN environment variable if no token is passed.

from cloudflare_analytics import get_analytics_client

# Uses CLOUDFLARE_API_TOKEN environment variable by default
client = get_analytics_client()

# Or pass it explicitly
client = get_analytics_client(api_token="your_cloudflare_api_token")

Option 2: Manual Instantiation

Use CloudflareAnalyticsClient directly if you need to manage multiple instances with different tokens or prefer to avoid global state.

from cloudflare_analytics import CloudflareAnalyticsClient

client = CloudflareAnalyticsClient(api_token="your_cloudflare_api_token")

Executing a Query

Once you have a client instance, you can execute GraphQL queries:

# Execute a GraphQL query
query = '''
query GetStreamMinutes($accountTag: string!, $start: Date, $end: Date) {
  viewer {
    accounts(filter: { accountTag: $accountTag }) {
      streamMinutesViewedAdaptiveGroups(
        filter: { date_geq: $start, date_lt: $end }
        orderBy: [date_ASC]
      ) {
        dimensions { date }
        sum { minutesViewed }
      }
    }
  }
}
'''

response = client.query(
    query,
    variables={
        "accountTag": "your_account_id",
        "start": "2025-10-01",
        "end": "2025-10-28"
    }
)

if response.errors:
    print(f"Errors: {response.errors}")
elif response.data:
    groups = response.data["viewer"]["accounts"][0]["streamMinutesViewedAdaptiveGroups"]
    for group in groups:
        minutes = group["sum"]["minutesViewed"]
        date = group["dimensions"]["date"]
        print(f"Date: {date}, Minutes: {minutes}")

Cloudflare API Key Setup

• Manage Account > Account API tokens
• The easiest way to get the account ID is to log into your dashboard and look at the first UID after the domain in the URL.

MIT License

This project was created from iloveitaly/python-package-template