Retrieve current usage and limits
Email usage against the limits that are actually enforced: the current month's counts per source category, the monthly cap applied to their total, and today's sends against the trust-tier daily ceiling.
Every figure is read from an enforcement path, so what this reports and what refuses a send cannot disagree. Correspondingly, nothing else is published — there is no billing period, invoice total or non-email meter here, because the platform meters none of those.
Two caveats worth reading before you alert on these numbers:
- The windows differ. The monthly counters roll over on the SERVER's calendar month; the daily counter buckets on the UTC date. The two therefore reset at different instants.
monthly.limitis null once a subscription makes sending metered rather than capped, and also when an operator has set per-category limits — in that case the caps live inmonthly.categories[*].limit.
Requires the usage:read scope — View your usage totals and billing limits.
API key authentication. Use a sk_* (FULL) or pk_* (SENDING_ONLY) key as the bearer token. Public keys (pk_*) are restricted to the email-send endpoints and the self-serve list subscribe/unsubscribe pair; every other endpoint — event tracking included — answers 403 for them. In scope terms (used by /api/v1/* operations): FULL keys hold every scope; SENDING_ONLY keys hold only emails:send.
In: header
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X GET "https://example.com/api/v1/usage"{
"plan": "free",
"monthly": {
"emails_sent": 0,
"limit": 0,
"categories": {
"transactional": {
"emails_sent": 0,
"limit": 0
},
"campaign": {
"emails_sent": 0,
"limit": 0
},
"workflow": {
"emails_sent": 0,
"limit": 0
},
"inbound": {
"emails_sent": 0,
"limit": 0
}
}
},
"daily": {
"emails_sent": 0,
"limit": 0,
"trust_tier": "NEW"
}
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}{
"type": "http://example.com",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"code": "string",
"request_id": "string",
"errors": [
{
"pointer": "string",
"code": "string",
"message": "string"
}
]
}