SCscalekit
Triggers

Get metered trigger usage

Changed on

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.

get/api/v1/trigger-usage

Request

Query parameters

fromstring

First UTC calendar date to include, as YYYY-MM-DD. Inclusive. Required when period is not sent, and must be left empty when it is. Must be a real date, must not be after to, and must not be after today's UTC date. A date more than 30 days before today's UTC date is clamped to the first day of the readable window, 30 days before today.

tostring

Last UTC calendar date to include, as YYYY-MM-DD. Inclusive. Required when period is not sent, and must be left empty when it is. Must be a real date and must not be more than 30 days before today's UTC date. A date after today's UTC date is clamped to today.

period'24h' | '7d' | '30d'

A preset period ending now, sent instead of from and to: exactly 24h, 7d or 30d, lowercase. 24h reads hourly counts for the 24 UTC clock hours ending with the hour in progress. 7d and 30d read daily counts for the UTC calendar days ending with today's UTC date: the week ending today, or the 30 days ending today. Leave from and to empty when this is set; when it is not, both are required.

Response

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

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_hourstring

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.

fromstring

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.

periodstring

The period the request asked for: 24h, 7d or 30d. Empty when the request used from and to.

tostring

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.

todaystring

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.

Example response

{
  "current_hour": "2026-10-14T18:00:00Z",
  "days": [
    {
      "date": "2026-10-08"
    }
  ],
  "from": "2026-10-01",
  "hours": [
    {
      "start": "2026-10-14T17:00:00Z"
    }
  ],
  "period": "24h",
  "to": "2026-10-31",
  "today": "2026-10-31"
}

Changes