Migrating from v1Health, limits & billing
Billing summary to Plan capabilities
Returns the organization's plan, subscription status, trial dates, and usage against plan limits. Use it to warn a customer before they hit a limit.
Billing summary
Returns the organization's plan, subscription status, trial dates, and usage against plan limits. Use it to warn a customer before they hit a limit.
| Old API | New API | |
|---|---|---|
| Method + route | none - new | GET /v2/workspaces/{workspaceId}/billing/summary |
| Key permission (scope) | none - new | billing:read (key role must be Admin or higher) |
| Rate bucket | none - new | read |
| Plan needed | none - new | - |
What changed
- This endpoint is new.
- Billing is for the whole organization. The
workspaceIdin the path is only used to check the key. - Admin role or higher is required. An Editor or Viewer key gets 403
insufficient_scope, even withbilling:read. - A
nulllimit means unlimited. Never treat it as 0. usageis cached for about 45 seconds. Read today's warmup sends from theDAILY_EMAILSentry inusage;warmupDailyonly tells you when the daily count resets.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | must be a workspace your key can access | Any workspace of the organization the key can access. | - |
Request body
No body.
Example request (new)
curl -X GET "$TI_BASE_URL/v2/workspaces/42/billing/summary" \
-H "Authorization: Bearer ti_ws_your_key"Response (new)
200 OK
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
plan | object or null | Current plan: id, name. null if the organization has no plan. | - |
status | string | TRIALING, ACTIVE, PAUSED, CANCELED, or PAST_DUE. | - |
trial | object or null | startedAt, endsAt, and daysLeft (whole days, never below 0). null when not in a trial. | - |
emailAccounts.used | number | Connected mailboxes in the organization. | - |
warmupDaily.resetsAt | string | Next reset: midnight in the organization's timezone. | - |
scheduledChange | object or null | A cancel or pause booked for the end of the billing period: action (cancel, pause, resume) and effectiveAt. | - |
scheduledResumeAt | string or null | When a fixed-length pause ends by itself. null for an open-ended pause or no pause. | - |
usage | array | One entry per limit: code (EMAIL_ACCOUNTS or DAILY_EMAILS), used, limit, pct. | - |
{
"data": {
"plan": { "id": 2, "name": "growth" },
"status": "ACTIVE",
"trial": null,
"emailAccounts": { "used": 17 },
"warmupDaily": {
"resetsAt": "2026-09-30T00:00:00.000Z"
},
"scheduledChange": null,
"scheduledResumeAt": null,
"usage": [
{ "code": "EMAIL_ACCOUNTS", "used": 17, "limit": 20, "pct": 85 },
{ "code": "DAILY_EMAILS", "used": 137, "limit": 500, "pct": 27 }
]
},
"meta": {
"request_id": "req_9a7b3c21-4d5e-4f60-8b19-0c2d3e4f5a6b",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | Header missing, or key wrong or revoked. | Send a valid key. |
| 403 | insufficient_scope | The key lacks billing:read, or its role is below Admin. | Use an Admin-level key with billing:read. |
| 403 | forbidden | The person behind a personal key is no longer an Admin in this workspace. | Use a key from a current Admin or Owner. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the workspace the key belongs to. |
| 429 | rate_limit_exceeded | Read bucket or IP limit used up. | Wait Retry-After seconds. |
Plan capabilities
Returns the list of features the organization's plan allows, as resource/action names. Use it to hide actions the customer cannot use.
| Old API | New API | |
|---|---|---|
| Method + route | none - new | GET /v2/workspaces/{workspaceId}/billing/capabilities |
| Key permission (scope) | none - new | billing:read (key role must be Admin or higher) |
| Rate bucket | none - new | read |
| Plan needed | none - new | - |
What changed
- This endpoint is new.
- It returns a flat list of strings such as
email-account/list. If a name is in the list, the plan allows that action. - The list comes from an account-level override when one exists, otherwise from the base plan.
- Admin role or higher is required, the same as the billing summary.
Path and query parameters
| Name | In | Type | Required | Default / limits | What it means | Old name |
|---|---|---|---|---|---|---|
workspaceId | path | number | yes | must be a workspace your key can access | Any workspace of the organization the key can access. | - |
Request body
No body.
Example request (new)
curl -X GET "$TI_BASE_URL/v2/workspaces/42/billing/capabilities" \
-H "Authorization: Bearer ti_ws_your_key"Response (new)
200 OK
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
identifiers | array of strings | Every resource/action the plan allows. | - |
{
"data": {
"identifiers": [
"email-account/list",
"reports/overview"
]
},
"meta": {
"request_id": "req_1e2f3a4b-5c6d-4e7f-8091-a2b3c4d5e6f7",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized / invalid_api_key | Header missing, or key wrong or revoked. | Send a valid key. |
| 403 | insufficient_scope | The key lacks billing:read, or its role is below Admin. | Use an Admin-level key with billing:read. |
| 403 | forbidden | The person behind a personal key is no longer an Admin in this workspace. | Use a key from a current Admin or Owner. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the workspace the key belongs to. |
| 429 | rate_limit_exceeded | Read bucket or IP limit used up. | Wait Retry-After seconds. |