Skip to content

Get monthly usage

GET
/v1/usage
curl --request GET \
  --url https://api.inboxcnx.com/v1/usage \
  --header 'Authorization: Bearer <token>'

Returns the caller application’s billable usage for one month, per grant and profile, so you can bill your own users. One row per grant and profile, with the Application’s totals. A grant moved to another profile during the month has a row per profile. Summed over all rows, mails, backfillMails and gbMonths equal the totals. Once closed is true the month is invoiced and its numbers never change. For the running month projection extends the live mails’ daily rate over the month and adds backfillMails once, so a one-off backfill is not projected onto the month.

Requires the read:usage scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
period

The month, YYYY-MM. Default: the running month.

string
/^\d{4}-(0[1-9]|1[0-2])$/

The month, YYYY-MM. Default: the running month.

cursor

Opaque pagination cursor: a previous response’s nextCursor or prevCursor, passed back verbatim. A cursor issued under one sort order is rejected if reused with another.

string

Opaque pagination cursor: a previous response’s nextCursor or prevCursor, passed back verbatim. A cursor issued under one sort order is rejected if reused with another.

limit

Page size, between 1 and 200. Default 50.

integer
>= 1 <= 200

Page size, between 1 and 200. Default 50.

Responses

Section titled “Responses”

200

Section titled “200”

A page of usage rows

Media typeapplication/json
object
period
required
string
/^\d{4}-(0[1-9]|1[0-2])$/
from
required
string
to
required
string
closed
required
boolean
totals
required
object
activeGrantsPeak
required
integer
mails
required
integer
backfillMails
required
integer
gbMonths
required
number
projection
required
object
projectedGbMonths
required
number
allowanceGbMonths
required
number
overageGbMonths
required
number
mails
required
integer
allowanceMails
required
integer
projectedMails
required
integer
overageMails
required
integer
storageOverageAmount
required
string
mailOverageAmount
required
string
data
required
Array<object>
object
grantId
required
string format: uuid
externalUserId
required
string | null
profileKey
required
string | null
activeDays
required
integer
mails
required
integer
backfillMails
required
integer
gbMonths
required
number
nextCursor
required
string | null
prevCursor
required
string | null

Example 

{
  "period": "2026-10",
  "from": "2026-10-01T00:00:00.000Z",
  "to": "2026-11-01T00:00:00.000Z",
  "closed": false,
  "totals": {
    "activeGrantsPeak": 12,
    "mails": 4180,
    "backfillMails": 900,
    "gbMonths": 3.2
  },
  "projection": {
    "projectedGbMonths": 4.1,
    "allowanceGbMonths": 10,
    "overageGbMonths": 0,
    "mails": 4180,
    "allowanceMails": 50000,
    "projectedMails": 6200,
    "overageMails": 0,
    "storageOverageAmount": "0.00",
    "mailOverageAmount": "0.00"
  },
  "data": [
    {
      "grantId": "9b2f0c4e-6a1d-4f3b-8c55-0d7e2a91b3c4",
      "externalUserId": "crm-user-42",
      "profileKey": "default",
      "activeDays": 23,
      "mails": 410,
      "backfillMails": 90,
      "gbMonths": 0.3
    }
  ],
  "nextCursor": null,
  "prevCursor": null
}

400

Section titled “400”

Invalid query or malformed cursor

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

The credential lacks the read:usage scope

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

502

Section titled “502”

Usage could not be read

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}

503

Section titled “503”

Usage is not configured

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string

Example generated

{
  "error": {
    "code": "example",
    "message": "example"
  }
}