Usage

Retrieve usage

GET/api/v1/usage

GET /usage
curl -X GET 'https://www.unitpost.com/api/v1/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "usage",
  "plan": "string",
  "period_start": "string",
  "period_end": "string",
  "emails": {
    "sent": 0,
    "included": 0,
    "daily_cap": 0,
    "sent_today": 0
  },
  "wallet": {
    "allowance_cents": 0,
    "used_cents": 0,
    "reserved_cents": 0,
    "fee_deficit_cents": 0,
    "fee_deficit_settled_cents": 0,
    "carryover_cents": 0,
    "purchased_credit_cents": 0,
    "overage_cents": 0,
    "overage_cap_cents": 0,
    "email_rate_per_1k_cents": 0,
    "shared_plan": {
      "allowance_cents": 0,
      "cap_cents": 0,
      "paused": false
    }
  },
  "spend": {
    "total_cents": 1,
    "email_cents": 0,
    "sms_cents": 0,
    "sms_carrier_fees_cents": 0,
    "other_cents": 0,
    "refunds_cents": 0,
    "included_cents": 0,
    "purchased_credit_cents": 0,
    "overage_cents": 0,
    "credits_added_cents": 0
  },
  "sms": {
    "messages": 0,
    "segments": 0,
    "send_cents": 0,
    "received": 0,
    "received_cents": 0,
    "monthly_fees_cents": 0,
    "one_time_fees_cents": 0,
    "refunds_cents": 0,
    "countries": [
      {
        "country": "string",
        "messages": 0,
        "segments": 0,
        "price_per_segment_cents": 0,
        "price_per_segment_cents_decimal": "string",
        "cost_cents": 0
      }
    ],
    "received_countries": [
      {
        "country": "string",
        "received": 0,
        "segments": 0,
        "cost_cents": 0
      }
    ]
  },
  "limits": {
    "log_retention_days": 0,
    "domains": 0,
    "team_members": 0,
    "api_keys": 0,
    "webhook_endpoints": 0,
    "image_storage_mb": 0,
    "contacts": 0,
    "advance_scheduling_days": 0,
    "automation_runs_included": 0,
    "ai_credits": 0,
    "sms_toll_free_numbers": 0,
    "sms_local_numbers_per_country": 1
  },
  "features": {
    "sms": false,
    "sms_carrier_resources": false,
    "inbound_email": false,
    "topics": false,
    "granular_permissions": false,
    "remove_branding": false
  }
}

Retrieve your workspace's current billing-period usage snapshot: the plan, the period window, and the email counter. On paid plans the response also carries the dollar sending wallet: the monthly allowance included with the plan, spend so far, any upgrade carryover, the non-expiring purchased-credit balance, and billable overage, all as integer USD cents. On the free plan wallet is null and the emails object carries the monthly quota and daily cap instead. spend itemizes the period from the wallet ledger (email, SMS, SMS carrier fees, refunds, and how it was paid), and sms breaks SMS down by destination country with segments, the price per segment, texts received by the receiving number's country, monthly number and campaign fees, one-time registration fees, and refunds. Amounts are read from the same ledger and meters that gate sending, so this matches the dashboard statement exactly. Requires the emails:read or sms:read capability.

Response · 200 fields10 fields
FieldTypeDescription
objectrequiredstring—
planrequiredstring—
period_startrequiredstring—
period_endrequiredstring—
emailsrequiredobject—
walletrequiredobject | null—
spendrequiredobject—
smsrequiredobject—
limitsobject—
featuresobject—
200401403

Retrieve spend caps

GET/api/v1/spend-caps

GET /spend-caps
curl -X GET 'https://www.unitpost.com/api/v1/spend-caps' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "spend_caps",
  "sms_purchases": {
    "cap_cents": 0,
    "max_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  },
  "shared_plan": {
    "cap_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  }
}

The workspace's monthly spend caps and what each has counted this period. sms_purchases caps the SMS carrier purchases API keys and apps confirm (POST /sms/quotes/{id}/confirm): the fee due now plus the first month of a monthly fee, per UTC calendar month; dashboard purchases never count. cap_cents is the cap as set (null: none, so every API purchase is refused with 403 api_spend_cap_not_set); the cap that applies is the lower of it and max_cents ($1,000 a month by default). A workspace that starts a paid plan on its own card starts with a $75 cap when it has none, unless a key or app of it already holds sms:purchase (a workspace its organization pays for follows the organization Owner's rules instead; a key still needs sms:purchase to buy). shared_plan is the workspace's cap on its organization's shared plan and what it drew from it this period (null when it isn't on one); its organization sets it. Requires the sms:read or sms:purchase or spend_caps:write capability.

Response · 200 fields3 fields
FieldTypeDescription
objectrequiredstring—
sms_purchasesrequiredobjectSMS purchases by API (`POST /sms/quotes/{id}/confirm`). Purchases made in the dashboard never count.
shared_planobject | nullThe workspace's cap on its organization's shared plan, read-only: its organization sets it (`PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`). Null when the workspace isn't on a shared plan.
200401403404422

Update spend caps

PATCH/api/v1/spend-caps

PATCH /spend-caps
curl -X PATCH 'https://www.unitpost.com/api/v1/spend-caps' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'
Response · 200
{
  "object": "spend_caps",
  "sms_purchases": {
    "cap_cents": 0,
    "max_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  },
  "shared_plan": {
    "cap_cents": 0,
    "spent_cents": 0,
    "period_start": "string",
    "period_end": "string"
  }
}

Set, raise, lower or clear a monthly spend cap; only the caps you send change. sms_purchases.cap_cents is whole cents from 0 (API purchases off) to the platform maximum ($1,000 a month by default), or null to clear it, after which every API purchase is refused (403 api_spend_cap_not_set) until a cap is set again. A purchase over the cap is refused with 403 api_spend_cap_exceeded and nothing is charged; the dashboard buys past it. The capability is in no key preset, and only the workspace owner holds it and can give it to a key or an app; no other capability changes a cap. A workspace its organization pays for refuses it (403 billed_by_organization): its organization sets that cap with sms_purchases_cap_cents on PATCH /organizations/{id}/workspaces/{workspace_id}. shared_plan is read-only: a body naming it is 403 billed_by_organization and changes nothing (the organization sets that cap with PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}). Requires the spend_caps:write capability.

Request body1 field
FieldTypeDescription
sms_purchasesobject—
Response · 200 fields3 fields
FieldTypeDescription
objectrequiredstring—
sms_purchasesrequiredobjectSMS purchases by API (`POST /sms/quotes/{id}/confirm`). Purchases made in the dashboard never count.
shared_planobject | nullThe workspace's cap on its organization's shared plan, read-only: its organization sets it (`PATCH /organizations/{id}/shared-plan/workspaces/{workspace_id}`). Null when the workspace isn't on a shared plan.
200400401403404422

Search docs and guides

Search the docs and product guides.