Health, limits & billing
Health check, rate-limit status and billing in /v2.
This page covers the utility endpoints: the health check, your rate-limit budget, and read-only billing data.
Health check
Tells you whether the API is up. Call it from a monitor, or to check if a failure is the API or your key.
| Old API | New API | |
|---|---|---|
| Method + route | GET /v1/health | GET /v1/health (path unchanged) |
| Key permission (scope) | X-Api-Key header sent in the old example | no key needed |
| Rate bucket | 20/min shared | not rate limited |
| Plan needed | - | - |
What changed
- The path is still
/v1/health. It is the only route that did not move to/v2. - Only the host changes: call
/v1/healthon the new base URL. - No key is needed. Do not send one. A monitor can poll it without using your budget.
- The body is now wrapped in
dataandmeta. The old docs did not document a body at all.
Path and query parameters
None.
Request body
No body.
Example request (new)
curl -X GET "$TI_BASE_URL/v1/health"Example request (old)
curl -X GET "https://lupus-edge.trulyinbox.com/v1/health" \
-H "X-Api-Key: YOUR_API_KEY"Response (new)
200 OK
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
status | string | Always "ok" when the API answers. | not documented in the old docs |
timestamp | string | Server time, ISO 8601 in UTC. | not documented in the old docs |
{
"data": {
"status": "ok",
"timestamp": "2026-09-29T10:00:00.000Z"
},
"meta": {
"request_id": "req_8c41f0d2-6b1e-4a57-9d3a-2f7e5b0c9a11",
"timestamp": "2026-09-29T10:00:00.000Z"
}
}Response (old)
Not documented in the old docs (the page shows an empty 200 response).
Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 500 | internal_error | The API is up but something failed. | Treat as unhealthy. Retry after a short wait. |
| - | - | No answer, timeout, or a connection error. | Treat as down. Alert or retry later. |
Rate-limit status
Shows how much of your per-minute budget is used and left, for each of the three buckets. Call it when you want to plan a batch of calls.
| Old API | New API | |
|---|---|---|
| Method + route | GET /v1/rate-limit | GET /v2/workspaces/{workspaceId}/rate-limit |
| Key permission (scope) | any key | any key (no scope needed) |
| Rate bucket | did not use quota (per old docs) | read - this call counts |
| Plan needed | - | - |
What changed
- The route now sits under a workspace: put your
workspaceIdin the path. - One number became three buckets:
read,write, andbulk. Each has its ownlimit,used, andremaining. - This call now uses one request from your
readbucket. The old one did not.read.usedalready includes this call. - Limits depend on your organization's plan (see the table below), not a flat 20/min.
resetsAtis a Unix time in seconds. All three buckets reset at that moment.- Counters are kept per API key. Two keys in the same organization each get their own budget. A separate 100/min limit per IP address applies to all keys together.
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 | The TrulyInbox workspace the key is used for. | - |
Request body
No body.
Example request (new)
curl -X GET "$TI_BASE_URL/v2/workspaces/42/rate-limit" \
-H "Authorization: Bearer ti_ws_your_key"Example request (old)
curl -X GET "https://lupus-edge.trulyinbox.com/v1/rate-limit" \
-H "X-Api-Key: YOUR_API_KEY"Response (new)
200 OK
| New field (inside data) | Type | What it means | Old field |
|---|---|---|---|
read.limit | number | GET requests allowed per minute. | not documented in the old docs |
read.used | number | GET requests already used this minute (includes this call). | not documented in the old docs |
read.remaining | number | GET requests left this minute. | not documented in the old docs |
write.limit / write.used / write.remaining | number | The same three numbers for POST, PATCH, PUT and DELETE. | - |
bulk.limit / bulk.used / bulk.remaining | number | The same three numbers for bulk routes (bulk status, bulk warmup enable/pause, bulk tags). | - |
resetsAt | number | Unix time in seconds when all buckets reset. | not documented in the old docs |
{
"data": {
"read": { "limit": 20, "used": 7, "remaining": 13 },
"write": { "limit": 10, "used": 2, "remaining": 8 },
"bulk": { "limit": 4, "used": 0, "remaining": 4 },
"resetsAt": 1790676060
},
"meta": {
"request_id": "req_3b9e2a70-11c4-4f0e-8a2d-6c5f1e9d7b20",
"timestamp": "2026-09-29T10:00:21.000Z"
}
}Response (old)
Not documented in the old docs. The old docs only said it returns "requests made, remaining quota, and reset window".
Limits per plan (requests per minute)
| Plan | read (GET) | write (POST/PATCH/PUT/DELETE) | bulk |
|---|---|---|---|
| Free | 5 | 2 | 1 |
| Starter | 10 | 5 | 2 |
| Trial | 20 | 10 | 4 |
| Growth | 20 | 10 | 4 |
| Scale | 30 | 15 | 6 |
| Scale +5k | 40 | 20 | 8 |
| Scale +10k | 45 | 22 | 9 |
| Scale +20k | 50 | 25 | 10 |
The billing cycle (monthly or yearly) does not change the limit. On top of these, every IP address gets 100 requests per minute across all keys. Tools like Zapier, Make, or n8n may share one IP with other customers, so they can hit the IP limit first.
Headers on every response
| Header | What it means |
|---|---|
X-RateLimit-Limit | Limit of the bucket this call used (read, write, or bulk). |
X-RateLimit-Remaining | Calls left in that bucket this minute. |
X-RateLimit-Reset | Unix time in seconds when the window resets. |
X-RateLimit-IP-Limit | Per-IP limit (100/min). |
X-RateLimit-IP-Remaining | Calls left for your IP this minute. |
Retry-After | Only on a 429. Seconds to wait before the next call (at least 1). |
How to pace your calls
- Read
X-RateLimit-RemainingandX-RateLimit-Resetfrom every response. You do not need to call this endpoint before each request. - If
X-RateLimit-Remainingis 0, wait untilX-RateLimit-Resetbefore the next call in that bucket. - Also watch
X-RateLimit-IP-Remaining. The IP limit is shared and your plan does not raise it. - On a 429, wait
Retry-Afterseconds (the same value is inerror.retry_after). Then retry once. - Do not retry at once in a loop. A rejected call still uses budget, so tight retries keep you blocked.
- Keep bulk routes for large jobs. The bulk bucket is small (1 to 10 per minute), but one bulk call can cover many mailboxes.
- Five failed key attempts from one IP lock that IP out for 15 minutes (429
too_many_requests). Stop and fix the key instead of retrying.
Errors you should handle
| HTTP | error.code | When it happens | What to do |
|---|---|---|---|
| 401 | unauthorized | No Authorization: Bearer header. | Send the header. |
| 401 | invalid_api_key | The key is wrong or was revoked. | Use a valid key. |
| 403 | workspace_forbidden | The key cannot access this workspaceId. | Use the workspace the key belongs to. |
| 403 | api_access_not_in_plan | Your plan does not include API access. | Upgrade the plan. |
| 403 | subscription_paused | The subscription is paused. | Resume the subscription. |
| 429 | rate_limit_exceeded | The read bucket or the IP limit is used up. | Wait Retry-After seconds, then retry. |
| 429 | too_many_requests | Too many failed key attempts from your IP. | Wait 15 minutes. Fix the key. |
Invite a member to Move daily warmup budget between workspaces
Sends an invitation email and returns the pending invite. The person becomes a member only after they accept, so they do not appear in the member list yet.
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.