Skip to content

Usage statistics API

See exactly how much your ZenDRIVE S3 Access is being used — request counts, bandwidth, and a day-by-day breakdown — over a simple authenticated API. It's the same usage data shown in your dashboard, available programmatically so you can pull it into your own scripts, billing reconciliation, or graphs.

The endpoint

POST https://dashboard.clearstreamer.com/zendrive-api/cdn-stats/

You authenticate with the same S3 access key and secret key you use to connect to your storage (from your welcome email). The request must be over HTTPS — plain HTTP is rejected.

Mind the trailing slash

Always POST to the URL with the trailing slash (/zendrive-api/cdn-stats/). Without it the server issues a redirect that drops your request body, and the call appears to do nothing.

Quick examples

Send just your keys and you get the last 30 days:

curl -X POST https://dashboard.clearstreamer.com/zendrive-api/cdn-stats/ \
  -H "Content-Type: application/json" \
  -d '{
    "access_key": "YOUR_ACCESS_KEY",
    "secret_key": "YOUR_SECRET_KEY"
  }'

Pass from / to as YYYY-MM-DD (UTC). The window can be up to 366 days:

curl -X POST https://dashboard.clearstreamer.com/zendrive-api/cdn-stats/ \
  -H "Content-Type: application/json" \
  -d '{
    "access_key": "YOUR_ACCESS_KEY",
    "secret_key": "YOUR_SECRET_KEY",
    "from": "2026-05-01",
    "to": "2026-05-31"
  }'

Pipe the response through jq to format it or pull out just what you need:

# whole response, pretty-printed
curl -s -X POST https://dashboard.clearstreamer.com/zendrive-api/cdn-stats/ \
  -H "Content-Type: application/json" \
  -d '{"access_key":"YOUR_ACCESS_KEY","secret_key":"YOUR_SECRET_KEY"}' | jq

# just the 30-day summary
curl -s -X POST https://dashboard.clearstreamer.com/zendrive-api/cdn-stats/ \
  -H "Content-Type: application/json" \
  -d '{"access_key":"YOUR_ACCESS_KEY","secret_key":"YOUR_SECRET_KEY"}' | jq '.summary'

# GB downloaded per day
curl -s -X POST https://dashboard.clearstreamer.com/zendrive-api/cdn-stats/ \
  -H "Content-Type: application/json" \
  -d '{"access_key":"YOUR_ACCESS_KEY","secret_key":"YOUR_SECRET_KEY"}' \
  | jq -r '.daily[] | "\(.date)  \(.bytes_sent / 1e9 | floor) GB"'

Parameters

Field Required Description
access_key Yes Your S3 access key.
secret_key Yes Your S3 secret key.
from No Start date YYYY-MM-DD (UTC). Defaults to 30 days ago.
to No End date YYYY-MM-DD (UTC). Defaults to today.

from must be on or before to, and the window can't exceed 366 days.

A successful response

{
  "status": "ok",
  "service_id": 1234,
  "from": "2026-05-25",
  "to": "2026-06-24",
  "summary": {
    "total_requests": 1875432,
    "successful_requests": 1861090,
    "client_errors": 14342,
    "auth_failures": 0,
    "bytes_sent": 18402954112000,
    "bytes_received": 0,
    "unique_ips": 3,
    "success_rate": 99.2
  },
  "daily": [
    {
      "date": "2026-05-25",
      "total_requests": 41201,
      "successful_requests": 41000,
      "client_errors": 201,
      "auth_failures": 0,
      "bytes_sent": 402954112000,
      "bytes_received": 0,
      "unique_ips": 2
    }
  ]
}

What the fields mean

Field Meaning
total_requests All S3 requests in the window.
successful_requests Requests that returned a 2xx.
client_errors Requests that returned a 4xx (e.g. missing object, bad request).
auth_failures Requests rejected for authentication / whitelist reasons.
bytes_sent Bytes downloaded from your node (egress) — this is your bandwidth usage.
bytes_received Bytes uploaded to your node.
unique_ips Distinct client IP addresses seen.
success_rate successful_requests ÷ total_requests, as a percentage.

daily holds one entry per day that had activity, oldest first. Days with no traffic are omitted, and a brand-new service simply returns an empty daily list with zeroed totals.

Bandwidth is in bytes

bytes_sent / bytes_received are raw bytes. Divide by 1_000_000_000 for GB (or 1_073_741_824 for GiB).

Errors

HTTP message Meaning
400 access_key and secret_key are required A credential field was missing.
400 'from' / 'to' must be a valid YYYY-MM-DD date A date couldn't be parsed.
400 'from' must be on or before 'to' The date range was inverted.
400 date range too large (max 366 days) Shorten the window.
400 HTTPS is required The request wasn't over HTTPS.
401 Invalid credentials Access key or secret key didn't match.
403 Service is not active The service is suspended or cancelled.
405 POST is required Use POST, not GET.
429 Too many requests, slow down Wait a moment — there's a short per-key rate limit.
503 Service temporarily unavailable A transient backend issue — retry shortly.

Generate a usage report with an AI assistant

Want a ready-made script that pulls your stats on a schedule and summarises them? Paste the prompt below into an AI assistant and fill in the bracketed details.

I want to track my ZenDRIVE S3 Access usage from a script using the usage statistics API.
Reference: https://wiki.clearstreamer.com/connecting/usage-stats-api/

My details:
- API endpoint: https://dashboard.clearstreamer.com/zendrive-api/cdn-stats/
- My S3 access key + secret key: [paste — treat the secret like a password]
- What I want: [e.g. a daily email/Slack summary of requests + GB downloaded, or a CSV of the daily breakdown]
- OS / scheduler I want: [cron / systemd timer / other]

Produce the script plus the scheduler unit/entry to run it, and a one-line way to test it.

Rules you must follow:
- POST over HTTPS only, to the URL WITH its trailing slash. Send access_key + secret_key
  in a JSON body; optionally from/to as YYYY-MM-DD (default is the last 30 days, max 366-day window).
- Store my keys in a root-owned file with chmod 600 — never inline them in a
  world-readable script, a committed file, or logs.
- Parse the JSON response (status, summary{...}, daily[...]); bytes_sent/bytes_received are raw bytes.
- Respect the per-key rate limit and back off on HTTP 429; only act on success and
  log failures (400/401/403/429/503) without printing the keys.
- Don't invent credentials — leave placeholders for anything I didn't provide.

Keeping it secure

  • The request carries your secret key, so the endpoint enforces HTTPS — never send it over plain HTTP, and don't log it. Treat any script holding these keys the same way you'd treat the keys themselves.
  • If your keys may have been exposed, rotate them — see Credentials & rotation.