Skip to main content
GET
/
v2
/
aggregators
/
{aggregatorId}
/
analytics
Get Aggregator Analytics
curl --request GET \
  --url https://api.tusky.io/v2/aggregators/{aggregatorId}/analytics
{
  "aggregatorId": "<string>",
  "period": {
    "from": "<string>",
    "to": "<string>"
  },
  "requests": {
    "total": 123,
    "rpm": 123,
    "cached": 123,
    "uncached": 123,
    "cacheHitRate": 123
  },
  "bandwidth": {
    "totalBytes": 123,
    "bytesPerMinute": 123,
    "cached": 123,
    "uncached": 123
  },
  "topFiles": [
    {
      "path": "<string>",
      "requests": 123,
      "bytes": 123,
      "mimeType": "<string>"
    }
  ],
  "devices": {
    "desktop": 123,
    "mobile": 123,
    "bot": 123,
    "other": 123
  },
  "locations": [
    {
      "country": "<string>",
      "requests": 123,
      "bytes": 123
    }
  ],
  "statusCodes": {
    "2xx": 123,
    "3xx": 123,
    "4xx": 123,
    "5xx": 123
  },
  "timeSeries": [
    {
      "timestamp": "<string>",
      "requests": 123,
      "bytes": 123
    }
  ]
}
Retrieve detailed usage statistics for an aggregator. Analytics data is sourced from Cloudflare edge metrics and includes traffic, bandwidth, device breakdown, geographic distribution, and top files.

​
Path Parameters

​
aggregatorId
string
required
The aggregator ID.

​
Query Parameters

​
from
string
required
Start of the time range (ISO 8601). Example: 2026-03-01T00:00:00Z.
​
to
string
required
End of the time range (ISO 8601). Example: 2026-03-07T23:59:59Z.
​
granularity
string
default:"hour"
Time series granularity. One of: minute, hour, day.

​
Response

​
aggregatorId
string
The aggregator ID.
​
period
object
​
requests
object
​
bandwidth
object
​
topFiles
array
Top 20 most requested files.
​
devices
object
​
locations
array
Per-country breakdown.
​
statusCodes
object
​
timeSeries
array
Time-bucketed data at the requested granularity.

​
Example

curl "https://api.tusky.io/v2/aggregators/agg_default/analytics?from=2026-03-01T00:00:00Z&to=2026-03-07T23:59:59Z&granularity=day" \
  -H "Api-Key: YOUR_API_KEY"

​
Response

{
  "aggregatorId": "agg_default",
  "period": {
    "from": "2026-03-01T00:00:00Z",
    "to": "2026-03-07T23:59:59Z"
  },
  "requests": {
    "total": 145200,
    "rpm": 14.3,
    "cached": 130680,
    "uncached": 14520,
    "cacheHitRate": 90.0
  },
  "bandwidth": {
    "totalBytes": 8523694080,
    "bytesPerMinute": 839280,
    "cached": 7671324672,
    "uncached": 852369408
  },
  "topFiles": [
    {
      "path": "/v1/blobs/abc123",
      "requests": 12450,
      "bytes": 1245000000,
      "mimeType": "video/mp4"
    }
  ],
  "devices": {
    "desktop": 87120,
    "mobile": 50820,
    "bot": 5808,
    "other": 1452
  },
  "locations": [
    { "country": "US", "requests": 58080, "bytes": 3409477632 },
    { "country": "DE", "requests": 21780, "bytes": 1278554112 }
  ],
  "statusCodes": {
    "2xx": 140000,
    "3xx": 1200,
    "4xx": 3500,
    "5xx": 500
  },
  "timeSeries": [
    { "timestamp": "2026-03-01T00:00:00Z", "requests": 20743, "bytes": 1217670583 }
  ]
}
Content-Type behavior on aggregators without a custom domain: For security, aggregators without a custom domain return potentially insecure MIME types as application/octet-stream instead of their actual type. This includes: text/html, text/xml, application/xhtml+xml, text/x-handlebars-template (.hbs), application/javascript, text/css, image/svg+xml.Aggregators with a custom domain serve all MIME types as-is. Set up a custom domain if you need to serve HTML, SVG, or other renderable content directly.