> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Get trigger usage (beta)

`GET /api/v1/trigger-usage`

This endpoint is in beta. Its request and response may change.

Gets the trigger deliveries metered for your environment. One unit is one event sent to one of your endpoints. Ask for `period` (`24h` by the hour, `7d` or `30d` by the UTC day), or for a range of UTC dates with `from` and `to`, up to 30 days back. Hours and days with no usage are left out, so fill the gaps with zero.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | No | 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. |
| `period` | string (enum) | No | 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. One of: `24h`, `7d`, `30d`. |
| `to` | string | No | 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. |

**Response (200)**

| Name | Type | Description |
| --- | --- | --- |
| `bucket` | string (enum) | What each entry counts. `TRIGGER_USAGE_BUCKET_HOUR` for `period=24h`, whose counts are in `hours`. `TRIGGER_USAGE_BUCKET_DAY` for `period=7d` and `period=30d`, whose counts are in `days`. `TRIGGER_USAGE_BUCKET_UNSPECIFIED` when the request used `from` and `to`; those counts are always by UTC day, in `days`. One of: `TRIGGER_USAGE_BUCKET_DAY`, `TRIGGER_USAGE_BUCKET_HOUR`. |
| `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` | array of object | 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`. |
| `days.date` | string | The UTC calendar date, as YYYY-MM-DD. |
| `days.units` | string | 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` | array of object | 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. |
| `hours.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. |
| `hours.units` | string | 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. |

**Errors**

- `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 isn't turned on for your 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

**Request**

```bash
curl -sS -G -X GET \
  "$SCALEKIT_ENVIRONMENT_URL/api/v1/trigger-usage" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "period=7d"
```

**Response**

```json
{
  "period": "7d",
  "bucket": "TRIGGER_USAGE_BUCKET_DAY",
  "from": "2026-10-22",
  "to": "2026-10-28",
  "today": "2026-10-28",
  "days": [
    {
      "date": "2026-10-27",
      "units": "112"
    },
    {
      "date": "2026-10-28",
      "units": "39"
    }
  ],
  "hours": [],
  "current_hour": ""
}
```

**Python SDK:** `scalekit_client.actions.triggers.get_usage`

Read metered trigger deliveries for a preset period or a UTC date range. Pass either `period` or both `from_date` and `to_date`. The server checks the combination and clamps the range to the last 30 days.

```python
scalekit_client.actions.triggers.get_usage(
    period: TriggerUsagePeriod | str | None = None,
    from_date: date | str | None = None,
    to_date: date | str | None = None,
) -> GetTriggerUsageResponse
```

Example:

```python
result = scalekit_client.actions.triggers.get_usage(
    period="7d",
)
```

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `period` | `TriggerUsagePeriod \| str \| None` | No | `"24h"` (hourly counts) or `"7d"`/`"30d"` (daily counts). |
| `from_date` | `date \| str \| None` | No | First UTC date, inclusive: a `date`, an aware `datetime` (its UTC date is used) or a `"YYYY-MM-DD"` string. |
| `to_date` | `date \| str \| None` | No | Last UTC date, inclusive, in the same forms. |

Returns `GetTriggerUsageResponse`: Daily or hourly counts and the range actually read.


Part of [Triggers](https://docs.scalekit.com/agentkit/reference/triggers/) in the [AgentKit API reference](https://docs.scalekit.com/agentkit/reference/). Authentication: https://docs.scalekit.com/agentkit/reference/authentication.md. Errors and rate limits: https://docs.scalekit.com/agentkit/reference/errors.md. Pagination: https://docs.scalekit.com/agentkit/reference/pagination.md


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |