Metrics

Use the Metrics Resource API to retrieve Environment-level usage metrics for uploads, transformations, requests, transfer, cache behavior, and storage.

Overview

Metrics help you understand how an Environment is being used. Use them for internal dashboards, reporting, integration monitoring, or account usage views.

The Metrics API has two response shapes:

Endpoint	Use it for
/api/v1/metrics/datasets	Time-series chart data
/api/v1/metrics/stats	Current value, previous value, and percentage change summaries

For programmatic backend integrations, call both endpoints with a Server API Key.

Query parameters

Parameter	Type	Default	Notes
interval	HOURLY, DAILY, WEEKLY, MONTHLY	HOURLY	Aggregation interval
tz	string	UTC	Time zone used for grouping
date_start	date-time	optional	Start of the query range
date_end	date-time	optional	End of the query range

Get metrics datasets

curl "https://api.imgwire.dev/api/v1/metrics/datasets?interval=DAILY&tz=UTC" \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

The response contains arrays for:

Dataset	Point fields
uploads	timestamp, uploads
transformations	timestamp, transformations
requests	timestamp, requests
transfer_bytes	timestamp, transfer_bytes
cache_hit_ratio	label, value
storage_bytes	timestamp, storage_bytes_current, storage_bytes_added

Example response excerpt:

{
  "uploads": [
    {
      "timestamp": "2026-05-09T00:00:00Z",
      "uploads": 42
    }
  ],
  "requests": [
    {
      "timestamp": "2026-05-09T00:00:00Z",
      "requests": 18420
    }
  ],
  "cache_hit_ratio": [
    {
      "label": "hit",
      "value": 92
    }
  ]
}

Get metrics stats

curl "https://api.imgwire.dev/api/v1/metrics/stats?interval=DAILY&tz=UTC" \
  -H "Authorization: Bearer $IMGWIRE_API_KEY"

Each metric returns:

Field	Meaning
value	Current value for the selected period
prev	Previous comparable value
pct_change	Percentage change, or null when it cannot be calculated

Example response excerpt:

{
  "uploads": {
    "value": 42,
    "prev": 35,
    "pct_change": 20
  },
  "transfer_bytes": {
    "value": 128000000,
    "prev": 96000000,
    "pct_change": 33.3333333333
  }
}

When to use this

• Show usage charts in an internal dashboard.
• Track whether request volume or transfer is changing over time.
• Monitor image upload and transformation activity.
• Compare current and previous usage windows.
• Understand storage growth for an Environment.

Best practices

• Use datasets for charts and stats for summary cards.
• Choose an interval that matches the reporting view. Use HOURLY for short windows and DAILY, WEEKLY, or MONTHLY for longer reports.
• Pass an explicit tz when chart labels need to match a user or account timezone.
• Use date ranges when dashboards need stable, repeatable reporting periods.

Common mistakes

• Mixing bytes with request counts in one chart scale.
• Treating pct_change: null as 0.
• Forgetting to use a Server API Key from a trusted backend or reporting job.
• Expecting metrics to manage billing limits by themselves; use metrics as reporting data for your application.

Related pages

• Resource API Overview
• Images
• API Reference
• Backend Quickstart

Last updated at: May 9, 2026