Usage metrics

Aggregate the usage events you send through /track — the ones with an event_handle — into per-handle totals over a date range: a COUNT of events and a SUM of their attributes.value. The rows come back as a paginated object: "list"; the trend series, date range, available handles, and billed-usage line ride in metadata.

Not metered —

This endpoint only reads back your own /track data, so it is exempt from metering — it never counts against your monthly read quota.

This is the same aggregation that powers the in-app Usage Events panel, so the numbers match what you see in Ranksy.

Only usage events (those with an event_handle) are counted here. Activity pings — the bare /track calls with no event_handle, like app_opened or a page view — live in a separate stream and are never summed into these totals.

Requires the usage:read scope — see Authentication. There's no Partner-integration gate: an app that has tracked no events returns an empty list, not an error.

GET/api/v1/apps/:app/usage-metrics

Usage metrics

Path parameter

Name
app
Type
string
Description
The team app's ULID, e.g. 01JN4HKQX0000000000000000.

Query parameters

Name
event_handle
Type
string
Description
Restrict to one handle, or several as a comma-separated list (sms_sent,email_sent). Omit for every handle in the range.
Name
shop
Type
string
Description
A .myshopify.com domain. Narrows the totals to one customer. A domain Ranksy doesn't know returns an empty list. Omit for the app-wide total.
Name
start_date
Type
string
Description
YYYY-MM-DD. Defaults to 30 days before end_date.
Name
end_date
Type
string
Description
YYYY-MM-DD. Must be greater than or equal to start_date. Defaults to today.
Name
granularity
Type
string
Description
Trend bucket size: day (default), week, or month. Only affects metadata.trend, not the row totals.
Name
page
Type
integer
Description
Page of metric rows to return. Default 1.
Name
per_page
Type
integer
Description
Rows per page. Default 50, maximum 100.

Request

GET

/api/v1/apps/:app/usage-metrics

curl https://ranksyapp.com/api/v1/apps/01JN4HKQX0000000000000000/usage-metrics \
  -H "Authorization: Bearer rk_live_..."

Response

{
  "object": "list",
  "url": "/api/v1/apps/01JN4HKQX0000000000000000/usage-metrics",
  "page": 1,
  "per_page": 50,
  "total_count": 2,
  "has_more": false,
  "coverage": {
    "requested": { "start": "2026-07-01", "end": "2026-07-31" }
  },
  "metadata": {
    "range": {
      "start": "2026-07-01T00:00:00+00:00",
      "end": "2026-07-31T23:59:59+00:00",
      "granularity": "week"
    },
    "trend": [
      { "bucket": "2026-07-06", "event_handle": "messages_sent", "event_count": 40, "total_value": 40 },
      { "bucket": "2026-07-13", "event_handle": "messages_sent", "event_count": 88, "total_value": 88 }
    ],
    "available_handles": ["email_sent", "messages_sent"],
    "billed_usage": null,
    "filters": {
      "event_handle": "messages_sent",
      "shop": "store.myshopify.com",
      "start_date": "2026-07-01",
      "end_date": "2026-07-31"
    }
  },
  "data": [
    {
      "event_handle": "messages_sent",
      "event_category": "custom",
      "is_custom": true,
      "event_count": 128,
      "total_value": 128,
      "first_seen": "2026-07-01T09:32:11+00:00",
      "last_seen": "2026-07-31T22:05:44+00:00"
    }
  ]
}

The metric row

Each entry in data is one handle's totals over the range.

Name
event_handle
Type
string
Description
The event handle, e.g. messages_sent.
Name
event_category
Type
string | null
Description
The registry category for a standard event, or "custom" for everything else.
Name
is_custom
Type
boolean
Description
true for custom (non-registry) handles.
Name
event_count
Type
integer
Description
How many events of this handle landed in the range.
Name
total_value
Type
number | null
Description
The sum of attributes.value across those events. null when none carried a value — a pure count metric.
Name
first_seen
Type
string | null
Description
ISO 8601 timestamp of the earliest event in the range.
Name
last_seen
Type
string | null
Description
ISO 8601 timestamp of the latest event in the range.

Metadata

Name
range
Type
object
Description
The resolved start, end, and granularity the aggregation used.
Name
trend
Type
array
Description
One row per (bucket, event_handle): the event_count and total_value in each time bucket. Plot this for a per-handle chart over time.
Name
available_handles
Type
array
Description
Every handle present in the range, ignoring the event_handle filter. Use it to build a filter menu.
Name
billed_usage
Type
object | null
Description
App-wide billed usage and one-time charges for the period (amount, charges, currency). Only present at the app-wide scope — it's null when you pass a shop, and null for apps that don't bill on usage.
Name
filters
Type
object
Description
The filters echoed back, as applied.

The row totals count events over the whole range regardless of granularity — only metadata.trend is bucketed. To get messages_sent for one shop as a monthly chart, filter by event_handle and shop and read metadata.trend.