OCT-103 Gumlet outreach
POST/image/analytics

Get image usage analytics

Retrieves image usage analytics, including bandwidth consumption, request counts, and cache or origin metrics. Provide metrics and a date_range with start_at and end_at; the requested range can span no more than 30 days. Use group_by to choose the data interval and filters.source_id to scope results to an image source.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

4 body fields

Image analytics query. Provide metrics and date_range; you can optionally group results or filter them by source.

date_rangeobjectrequired

The timeframe to get the data for. Currently we only support a maximum of 30 days between start_at and end_at.

filtersobjectoptional

Optional filters for the analytics query.

group_bystringoptional

Data interval: daily, weekly, monthly, or hourly. Defaults to daily when omitted.

Allowed:dailyweeklymonthlyhourlyDefault:daily
metricsarray<string>required

Define the metric you need the data for. Supported values: bandwidth_consumption, requests_count, transformations_count, bandwidth_savings, origin_hit_rate, avg_transformation_response_time, status_4xx, status_5xx, cdn_hit_rate, content_type, status_2xx, avg_response_time, top_assets, bandwidth_consumption_by_source, and ai_credit_usage.

4 status codes
200Returns an analytics object with arrays for the requested metrics, including timestamped measurements and metric-specific values.
ai_credit_usagearray<object>optional
avg_response_timearray<object>optional
avg_transformation_response_timearray<object>optional
bandwidth_consumptionarray<object>optional
bandwidth_consumption_by_sourcearray<object>optional
bandwidth_savingsarray<object>optional
cdn_hit_ratearray<object>optional
content_typearray<object>optional
origin_hit_ratearray<object>optional
requests_countarray<object>optional
status_2xxarray<object>optional
status_4xxarray<object>optional
status_5xxarray<object>optional
transformations_countarray<object>optional
400Returned when required analytics fields are missing or a date range, grouping value, or metric fails validation.

One documented failure

  • image_source_not_found

    Could not find any image source with the specified source_id.

errorobjectrequired
401Returned when the API key or bearer token is missing or invalid.

One documented failure

  • invalid_api_key

    API key supplied with request is invalid

errorobjectrequired
403Returned when the account is unpaid or the authenticated user lacks the required role permissions.

One documented failure

  • unauthorized

    You don't have access to this feature. Please contact your organization owner.

errorobjectrequired

Error handling

A 400 is returned for a bad request, a 401 when the API key or bearer token is missing or invalid, and a 403 when the account is unpaid or lacks the required role permissions. metrics and date_range are required, and date_range must include start_at and end_at in yyyy-MM-dd format with no more than 30 days between them. group_by, when provided, must be daily, weekly, monthly, or hourly.