---
title: "Get Usage"
method: GET
path: "/api/v1/billing/usage"
tags: ["Billing"]
---

# Get Usage

`GET /api/v1/billing/usage`

## Response `200`

Successful Response

- UsageSummaryResponse
  - `cycle_start` integer, required — Unix seconds for the start of the current usage cycle.
  - `cycle_end` integer, nullable — Unix seconds for the end of the current usage cycle (Stripe period end, or the calendar-month boundary for orgs with no subscription).
  - `plan` string, required — Org's current plan (free/hobbyist/developer/startup/enterprise).
  - `channels` ChannelUsageResponse[] — Org-wide totals, one per channel with usage this cycle.
    - `event_type` string, required — Usage channel key (UsageEventType, e.g. 'sms_outbound').
    - `count` integer, required — Total usage this cycle (messages, or call seconds for voice).
    - `overage` integer, required — Units beyond the included allowance this cycle.
    - `est_overage_cents` integer, nullable — Estimated overage cost in cents (from published rates). None for unpriced channels (email, iMessage).
    - `own_campaign_count` integer, nullable — For SMS channels: portion of 'count' carried on the org's own 10DLC campaign (the rest rode the Inkbox-managed campaign). None on non-SMS channels.
  - `identities` IdentityUsageResponse[] — Per-identity usage breakdown.
    - `identity_id` string, nullable — Agent identity id, or None for the 'Unattributed' bucket (usage with no originating identity, e.g. outbound email).
    - `handle` string, nullable — Agent handle, if the identity is known.
    - `display_name` string, nullable — Identity display name, if set.
    - `channels` IdentityChannelCountResponse[] — Per-channel usage counts for this identity.
      - `event_type` string, required — Usage channel key (UsageEventType).
      - `count` integer, required — This identity's usage on the channel this cycle.
      - `own_campaign_count` integer, nullable — For SMS channels: portion of 'count' carried on the org's own 10DLC campaign. None on non-SMS channels.
    - `sms_used` integer, nullable — Combined in+out SMS drawn against this identity's allowance this cycle. None when the identity used no SMS.
    - `sms_limit` integer, nullable — Included SMS allowance for the identity.
    - `voice_sec_used` integer, nullable — Combined in+out call seconds drawn this cycle. None when unused.
    - `voice_sec_limit` integer, nullable — Included voice allowance for the identity, in seconds.
  - `sms_allowance_per_identity` integer, required — Included SMS allowance per phone-enabled identity per cycle (0 on Free).
  - `voice_sec_allowance_per_identity` integer, required — Included voice allowance per phone-enabled identity per cycle, in seconds.
  - `overage_cap_cents` integer, nullable — Org's monthly SMS+voice overage spend limit in cents; None when unset.
  - `overage_spend_cents` integer — Estimated SMS+voice overage spend so far this cycle, in cents (the figure the overage spend limit is enforced against).
  - `imessage_shared_messages` integer — Shared-pool iMessage messages this cycle (both directions) — the count the plan's shared iMessage cap is enforced against.
  - `imessage_dedicated_messages` integer — Dedicated-line iMessage messages this cycle (both directions) — the count the dedicated-line cap is enforced against.
  - `imessage_unique_recipients` integer — Unique shared-pool iMessage recipients this cycle — the count the plan's unique-recipient cap is enforced against.
  - `identities_used` integer — Non-deleted agent identities in the org — the count the plan's identity cap is enforced against on create.
  - `identities_included` integer — Agent identities included in the plan (resolved IDENTITIES_ACTIVE quota).

## Other responses

- `4XX` — Client error with Support Agent information.
- `5XX` — Server error with Support Agent information.

---

[API](https://skmtc.dev/inkbox/apis/inkbox-api.md) · [All operations](https://skmtc.dev/inkbox/apis/inkbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inkbox/inkbox-api/revisions/31f357e7e6f8/schema)