Skip to content
Notavia Notavia Docs

Get current-period usage and plan limits

GET
/v1/usage
 
curl --request GET \
  --url https://your-notavia-host/v1/usage \
  --header 'Authorization: Bearer <token>'

Returns the calling organization’s live (non-test) send usage for the current calendar-month billing period, the resolved plan, its included send allowance, and a per-channel breakdown. Test-environment sends are not counted. Readable by any valid API key.

Authorizations

Section titled “Authorizations ”

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Current-period usage and plan limits.

Media type application/json

Current-period live usage and resolved plan limits.

object
plan
required

Resolved plan key (e.g. free, oem).

string
period_start
required

Inclusive UTC start of the current billing period (first of the month).

string format: date-time
period_end
required

Exclusive UTC end of the current billing period (first of the next month).

string format: date-time
included_sends

Monthly included send allowance, or null for unmetered plans.

integer format: int64
nullable
used_sends
required

Live (non-test) sends consumed in the current period.

integer format: int64
remaining_sends

Sends remaining before the cap, or null when there is no cap.

integer format: int64
nullable
hard_limit
required

When true, sends are rejected once the included allowance is exhausted.

boolean
by_channel
required

Live sends consumed in the current period, keyed by lowercase channel name.

object
key
additional properties
integer format: int64
Example generated
{
  "plan": "example",
  "period_start": "2026-04-15T12:00:00Z",
  "period_end": "2026-04-15T12:00:00Z",
  "included_sends": 1,
  "used_sends": 1,
  "remaining_sends": 1,
  "hard_limit": true,
  "by_channel": {
    "additionalProperty": 1
  }
}

401

Section titled “401 ”

Missing or invalid credentials.

Media type application/json
object
error
required
object
type
required
string
code
required
string
message
required
string
param
string
nullable
Example generated
{
  "error": {
    "type": "example",
    "code": "example",
    "message": "example",
    "param": "example"
  }
}