--- title: "Get metered trigger usage" method: GET path: "/api/v1/trigger-usage" tags: ["Triggers"] --- # Get metered trigger usage `GET /api/v1/trigger-usage` ## Request - Base URL: `https://$SCALEKIT_ENVIRONMENT_URL` - URL: `https://$SCALEKIT_ENVIRONMENT_URL/api/v1/trigger-usage` - Auth: OAuth 2 - Client credentials - Token URL: `https://$SCALEKIT_ENVIRONMENT_URL/oauth/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns the trigger deliveries metered for this environment over a period, either a preset period ending now or a range of UTC calendar dates. Use this endpoint to chart trigger usage, for example the last 24 hours by the hour or the current month by the day. Ask for the period in one of two ways, never both: `period`, or `from` and `to`. With `period=24h` the counts are hourly, in `hours`, for the 24 UTC clock hours ending with the hour in progress, which the response names as `current_hour`; that hour's count grows until it ends. With `period=7d` or `period=30d` the counts are daily, in `days`, for the UTC calendar days ending with today's UTC date: the week ending today, or the 30 days ending today. With `from` and `to` the counts are daily, in `days`, for each UTC calendar day from `from` to `to`, both inclusive. Days follow UTC, not the caller's time zone. One unit is one trigger event sent to one receiving endpoint, so an event delivered to several endpoints counts once for each, and a filtered or duplicate event, a failed handoff, or an event no endpoint receives counts none. Only hours and days with metered units are returned: one with none is absent rather than listed as zero, so fill the gaps yourself over the bounds the response returns. Usage is recorded with a short delay, so the latest deliveries can be missing from the current hour's and today's count for a short while. The readable window is today's UTC date and the 30 days before it, and every `period` falls inside it. A `from` and `to` range that extends past the window is clamped to it: a `from` more than 30 days before today's UTC date reads from the first day of the window, and a `to` after today's UTC date reads through today. A range with no day inside the window is refused, as is a `from` after `to`. Returns the range actually read as `from` and `to`, which differ from the request when it was clamped, the `period` asked for, the size of each entry as `bucket`, and the server's UTC date as `today`, so you can tell the day still in progress apart from completed ones. ## Query parameters - `from` string - `to` string - `period` '24h' | '7d' | '30d' ## Response `200` The metered usage: one entry per hour (`period=24h`, in `hours`) or per UTC day (every other request, in `days`) with metered units, oldest first, plus the range read and today's UTC date - TriggersGetTriggerUsageResponse: Metered trigger deliveries in hourly buckets for period 24h, or in UTC daily buckets for every other request. Buckets with no deliveries are left out. - `bucket` 'TRIGGER_USAGE_BUCKET_DAY' | 'TRIGGER_USAGE_BUCKET_HOUR': The size of each entry in a trigger usage response. - TRIGGER_USAGE_BUCKET_DAY: One entry per UTC calendar day, in days. Returned for period 7d and 30d. - TRIGGER_USAGE_BUCKET_HOUR: One entry per UTC clock hour, in hours. Returned for period 24h. - `current_hour` string: Only for `period=24h`, and empty otherwise. The start of the UTC clock hour in progress on the server, as an RFC 3339 timestamp in UTC (`Z`). It is the last of the 24 hours `hours` covers, and its count grows until the hour ends. Returned so a client lays out the 24 hours and marks the one in progress without relying on its own clock. - `days` TriggersTriggerUsageDay[]: One entry per UTC day within the range read (`from`..`to`) that has metered deliveries, oldest first. A day in that range with none is absent rather than listed as zero, so a client that needs a continuous series fills the missing days itself, over the returned `from` and `to` rather than the range it requested. Days outside the range read were not read and must not be drawn as zero. Always empty for `period=24h`, whose counts are in `hours`. - `date` string: The UTC calendar date, as YYYY-MM-DD. - `units` string, int64: Trigger deliveries metered for this environment on this day: one for each trigger event sent to one receiving endpoint. Always greater than zero; a day with none is left out of the response. - `from` string: First UTC calendar date of the range read, as YYYY-MM-DD. For a `from` and `to` request, the requested `from`, or the first day of the readable window, 30 days before `today`, when the request started earlier. For a `period` request, the UTC date of the first hour (`24h`) or the first day (`7d`, `30d`) of the period. - `hours` TriggersTriggerUsageHour[]: Only for `period=24h`, and empty otherwise. One entry per UTC clock hour that has metered deliveries, oldest first, among the 24 hours from 23 hours before `current_hour` through `current_hour`. An hour in that range with none is absent rather than listed as zero, so a client that needs a continuous series fills the missing hours itself over those 24 hours. Hours outside them were not read and must not be drawn. - `start` string: The start of the UTC clock hour, as an RFC 3339 timestamp in UTC (`Z`) with zero minutes and seconds. The hour runs from `start` up to, not including, `start` plus one hour. - `units` string, int64: Trigger deliveries metered for this environment in this hour: one for each trigger event sent to one receiving endpoint. Always greater than zero; an hour with none is left out of the response. - `period` string: The `period` the request asked for: `24h`, `7d` or `30d`. Empty when the request used `from` and `to`. - `to` string: Last UTC calendar date of the range read, as YYYY-MM-DD. For a `from` and `to` request, the requested `to`, or `today` when the request ended later. For a `period` request, always `today`. - `today` string: The server's current UTC calendar date, as YYYY-MM-DD. Deliveries on this day are still being metered, so its count grows until the day ends. The readable window and any clamping of `from` and `to` are measured from this date. Returned so a client tells the day in progress apart from completed days without relying on its own clock. ## Other responses - `400`: Invalid request - `period` is not exactly `24h`, `7d` or `30d`; `period` is sent together with `from` or `to`; `period` is not sent and `from` or `to` is missing; a date is not a real calendar date in YYYY-MM-DD form; `from` is after `to`; `from` is after today's UTC date; or `to` is more than 30 days before today's UTC date. A range that only extends past the readable window is clamped, not refused - `404`: Not found - trigger usage is not metered for this environment (error_code TRIGGER_USAGE_NOT_METERED), or Triggers is not enabled for the environment (error_code RESOURCE_NOT_FOUND) - `500`: Internal error - the usage could not be read; retry the request - `503`: Service unavailable - usage data could not be read right now. No partial figures are returned; retry the request later ## Changes - **2026-10-30** `f47f1022d844`: 1 info - endpoint added [Operation history](https://skmtc.dev/scalekit/apis/scalekit-api-reference/changes/api/v1/trigger-usage/get.md) --- [API](https://skmtc.dev/scalekit/apis/scalekit-api-reference.md) - [All operations](https://skmtc.dev/scalekit/apis/scalekit-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/scalekit/apis/scalekit-api-reference/revisions/f47f1022d844?raw)