# Cloudflare Zone Analytics (`cloudflare.zone_analytics`)

Traffic of one of your Cloudflare zones by day or hour: requests, bandwidth, cached vs uncached, threats and page views.

Docs: https://primaryapi.com/docs/api-reference/cloudflare/zone_analytics

- Endpoint: `POST https://api.primaryapi.com/v1/run/cloudflare.zone_analytics`
- Category: Web Scraping · Platform: `cloudflare` · Kind: lookup · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=cloudflare.zone_analytics`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `zone` | string | yes |  | max 253 chars | The zone (domain) on Cloudflare: its domain name, for example "example.com", or its 32-character zone id from cloudflare.zones. |
| `granularity` | enum | no | "day" | one of: day, hour | One row per day (default) or per hour (UTC). |
| `since` | string | no |  |  | Start (UTC), as a date "2026-11-01" or a date-time. Default: 7 days ago (day) or 24 hours ago (hour). Moved later when the zone’s plan keeps less history. |
| `until` | string | no |  |  | End (UTC): the last day to include (day), or the end time, exclusive (hour). Default: today, or the current hour. |
| `connection` | string | no |  | max 200 chars | Which connected account to use when the workspace has several for this provider: the customId you gave it (exact), its connection id ("con_…"), its handle (login, email or @handle) or its name. Optional; prefer the customId or id, which never match two accounts. |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `zoneId` | string |  |
| `zone` | string |  |
| `granularity` | enum |  |
| `since` | string | First day (YYYY-MM-DD) or hour (ISO) covered |
| `until` | string | Last day covered (inclusive) or the end hour (exclusive) |
| `totals` | object |  |
| `totals.requests` | integer | All requests |
| `totals.cachedRequests` | integer | Requests served from Cloudflare’s cache |
| `totals.uncachedRequests` | integer | Requests that went to the origin |
| `totals.bytes` | integer | Bandwidth served, in bytes |
| `totals.cachedBytes` | integer |  |
| `totals.uncachedBytes` | integer |  |
| `totals.threats` | integer | Requests Cloudflare classified as threats |
| `totals.pageViews` | integer | Requests for HTML pages |
| `totals.encryptedRequests` | integer | Requests over HTTPS |
| `totals.cacheHitRatio` | number \| null | cachedRequests ÷ requests (0-1), null without traffic |
| `series` | object[] | One row per day or hour with traffic, oldest first |
| `series[].period` | string | The day (YYYY-MM-DD) or the start of the hour (ISO) |
| `series[].requests` | integer | All requests |
| `series[].cachedRequests` | integer | Requests served from Cloudflare’s cache |
| `series[].uncachedRequests` | integer | Requests that went to the origin |
| `series[].bytes` | integer | Bandwidth served, in bytes |
| `series[].cachedBytes` | integer |  |
| `series[].uncachedBytes` | integer |  |
| `series[].threats` | integer | Requests Cloudflare classified as threats |
| `series[].pageViews` | integer | Requests for HTML pages |
| `series[].encryptedRequests` | integer | Requests over HTTPS |
| `series[].uniqueVisitors` | integer \| null | Unique visitor IPs in this period (not additive across periods) |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/cloudflare.zone_analytics" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"zone":"023e105f4ecef8ad9ca31a8372d0c353","since":"2026-11-06","until":"2026-11-08"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "zoneId": "023e105f4ecef8ad9ca31a8372d0c353",
      "zone": "example.com",
      "granularity": "day",
      "since": "2026-11-06",
      "until": "2026-11-08",
      "totals": {
        "requests": 6000,
        "cachedRequests": 4800,
        "uncachedRequests": 1200,
        "bytes": 150000000,
        "cachedBytes": 120000000,
        "uncachedBytes": 30000000,
        "threats": 18,
        "pageViews": 2400,
        "encryptedRequests": 5940,
        "cacheHitRatio": 0.8
      },
      "series": [
        {
          "period": "2026-11-06",
          "requests": 1000,
          "cachedRequests": 800,
          "uncachedRequests": 200,
          "bytes": 25000000,
          "cachedBytes": 20000000,
          "uncachedBytes": 5000000,
          "threats": 3,
          "pageViews": 400,
          "encryptedRequests": 990,
          "uniqueVisitors": 120
        },
        {
          "period": "2026-11-07",
          "requests": 2000,
          "cachedRequests": 1600,
          "uncachedRequests": 400,
          "bytes": 50000000,
          "cachedBytes": 40000000,
          "uncachedBytes": 10000000,
          "threats": 6,
          "pageViews": 800,
          "encryptedRequests": 1980,
          "uniqueVisitors": 240
        },
        {
          "period": "2026-11-08",
          "requests": 3000,
          "cachedRequests": 2400,
          "uncachedRequests": 600,
          "bytes": 75000000,
          "cachedBytes": 60000000,
          "uncachedBytes": 15000000,
          "threats": 9,
          "pageViews": 1200,
          "encryptedRequests": 2970,
          "uniqueVisitors": 360
        }
      ]
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=cloudflare.zone_analytics`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Runs as your connected Cloudflare account (read-only) and needs the "Read analytics" permission. Counts are Cloudflare’s own roll-ups for the zone, in UTC. How far back and how wide a range you can read depends on the zone’s plan: when the range does not fit, it is narrowed to the most recent part that does and the response carries a hint starting with "date_adjusted:". Hours or days without traffic are left out of `series`. Results are never stored.

