List usage by workspace
GET/api/v1/organizations/{id}/usage
curl -X GET 'https://www.unitpost.com/api/v1/organizations/org_123/usage' \
-H 'Authorization: Bearer YOUR_ORG_KEY' \
-H 'User-Agent: my-app/1.0'{
"object": "list",
"has_more": false,
"data": [
{
"object": "workspace_usage",
"workspace_id": "workspace_123",
"external_id": "external_123",
"name": "Example",
"closed_at": "2026-01-01T00:00:00.000Z",
"plan": "string",
"period_start": "string",
"period_end": "string",
"emails": {
"sent": 0
},
"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
}
]
},
"on_shared_plan": false
}
]
}Usage and spend for each of the organization's workspaces, one row per workspace, newest first and cursor-paginated by workspace (limit 1 to 25, default 10; after and before take a ws_… id). A limit above 25 is a 422, not a shorter page; read more with after. Each workspace renews on its own date, so a row covers that workspace's own billing period: period=current (the default) is its open period, and an ISO 8601 instant is its period that contains that instant. A workspace with no recorded period at that instant (it did not exist yet, or nothing was used in that period) has period_start and period_end null and every number 0. spend, sms, emails.sent, plan and the period are built as GET /usage builds them, so for the open period a row equals that workspace's GET /usage; amounts are integer USD cents rounded per workspace, and the organization's total is the sum of the rows. Closed workspaces are listed, with closed_at, until they are deleted. external_id narrows to the workspace you gave that id. Takes an organization key (ok_live_…) with organizations:read.
Parameters6 fields
| Field | Type | Description |
|---|---|---|
idrequired | string · path | The organization's id (`org_…`), from `GET /whoami` or Organization → API. |
period | string · query | `current` (default), or an ISO 8601 instant with `Z` or an offset (`2026-10-15T00:00:00Z`); a date alone is UTC midnight. |
limit | integer · query | Workspaces a page (default 10, max 25). |
after | string · query | The next page: the last row's `workspace_id` (`ws_…`). |
before | string · query | The previous page: the first row's `workspace_id` (`ws_…`). Not with `after`. |
external_id | string · query | Only the workspace you gave this id. |
Response · 200 fields12 fields
| Field | Type | Description |
|---|---|---|
objectrequired | string | — |
workspace_idrequired | string | — |
external_idrequired | string | null | — |
namerequired | string | — |
closed_atrequired | string | null | — |
planrequired | string | — |
period_startrequired | string | null | — |
period_endrequired | string | null | — |
emailsrequired | object | — |
spendrequired | object | — |
smsrequired | object | — |
on_shared_plan | boolean | — |