Workspace and usage
Check which workspace and key a request runs as, and read calls, billed minutes and balance for a period.
Two read-only endpoints tell your integration about the workspace it works in:
GET /api/v1/workspace: which workspace and which key a request runs as.GET /api/v1/usage: calls, talk time, billed minutes, wallet charges, plan and balance for a period.
Every API key can call both with GET, including read-only keys and keys limited to other resources (Authentication).
Check a key: GET /workspace
Use it to:
- Verify a key before real work, for example when a customer pastes a key into your app. A bad key answers
401invalid_api_key, an expired one401api_key_expired. - Show the workspace name next to the connection in your UI.
- Read the key's limits: its access, the resources it can reach, its expiry and its rate limit.
- Confirm the agency context: with
X-Workspace-Id, an agency key sees the client workspace (Agencies).
Replaces GET /auth/me for keys
GET /auth/me is a console endpoint. API keys get 403 api_key_route_forbidden there and everywhere under /auth. Call GET /api/v1/workspace instead.
curl https://api.callmitra.ai/api/v1/workspace \
-H "X-API-Key: $CALLMITRA_API_KEY"{
"success": true,
"workspace": {
"id": "7b1c2f0e-1d2a-4c3b-9a8e-5f6d7c8b9a01",
"name": "Acme Realty",
"parentId": null
},
"apiKey": {
"id": "0d9e8f7a-6b5c-4d3e-2f1a-0b9c8d7e6f5a",
"prefix": "vk_live_Ab3dE6",
"name": "CRM sync",
"scopes": { "access": "read", "resources": ["calls", "leads"] },
"expiresAt": null
},
"rateLimit": { "limit": 300, "windowSeconds": 60 }
}| Field | Meaning |
|---|---|
workspace.id, workspace.name | The workspace the request runs in. |
workspace.parentId | The agency workspace this client workspace belongs to; null for a workspace that is not a client. |
apiKey.id, apiKey.name | The key that sent the request, and the name it was given. apiKey is null when the request was not made with an API key (a console session). |
apiKey.prefix | The first characters of the key, as shown in the console. The secret is never returned. |
apiKey.scopes.access | full, or read (read-only keys may only send GET). |
apiKey.scopes.resources | Resource groups the key may reach. An empty list means all of them. |
apiKey.expiresAt | When the key stops working; null if never. |
rateLimit.limit | Requests per minute allowed for this key; 0 means no limit. windowSeconds is the window length. See Rate limits. |
Agency keys
An agency key without X-Workspace-Id sees the agency workspace. With the header set to one of its client workspaces, workspace is the client and workspace.parentId is the agency. Use this to check that a client ID is valid before you start work in it: a workspace the key cannot act in answers 403 permission_denied, never 404.
curl https://api.callmitra.ai/api/v1/workspace \
-H "X-API-Key: $AGENCY_API_KEY" \
-H "X-Workspace-Id: 3f2b6c1e-8a4d-4f7e-9b2a-1c5d7e9f0a12"Read usage: GET /usage
GET /api/v1/usage reports one workspace: the one the request runs in (the client workspace when an agency key sends X-Workspace-Id).
Choosing the period
| Parameter | Format | Meaning |
|---|---|---|
from | ISO 8601 date or date-time | Start of the period, inclusive. A date-time without an offset is UTC. A bare date (2026-11-01) means 00:00 UTC that day. |
to | ISO 8601 date or date-time | End of the period, exclusive. A bare date includes that whole day (UTC). Default: now. |
- Neither sent: the current billing period of your plan, from its start until now (
basis: "billing_period"). Without a plan period, the last 30 days (basis: "last_30_days"). - Only
from: fromfromuntil now. - Only
to: the 30 days beforeto. - With either sent,
basisiscustom. frommust be beforeto, and the range can cover at most 366 days. Otherwise422parameter_invalid. A value that is not an ISO 8601 date or date-time answers the same code.
Dates are UTC days
Bare dates use UTC midnight, not India Standard Time. For an IST calendar month, send date-times with an offset, for example from=2026-11-01T00:00:00+05:30 and to=2026-12-01T00:00:00+05:30. In a raw URL, encode the + as %2B; the examples below do this for you.
curl -G https://api.callmitra.ai/api/v1/usage \
-H "X-API-Key: $CALLMITRA_API_KEY" \
--data-urlencode "from=2026-11-01T00:00:00+05:30" \
--data-urlencode "to=2026-12-01T00:00:00+05:30"{
"success": true,
"period": { "start": "2026-11-01T00:00:00Z", "end": "2026-11-15T12:00:00Z", "basis": "billing_period" },
"calls": {
"total": 412,
"completed": 288,
"durationSeconds": 21950.0,
"billedMinutes": 402,
"walletChargedInrPaise": 0
},
"plan": {
"name": "Growth",
"slug": "growth",
"periodStart": "2026-11-01T00:00:00+00:00",
"periodEnd": "2026-12-01T00:00:00+00:00",
"minutesIncluded": 2000,
"minutesUsed": 402,
"minutesRemaining": 1598,
"overageMinutes": 0,
"overageAmountInrPaise": 0
},
"balance": { "balanceInrPaise": 150000, "ratePerMinuteInrPaise": 600, "minutesAtCurrentRate": 250 },
"billingEnabled": true
}Fields
Money is in paise (1 INR = 100 paise), as integers. Talk time is in seconds; billed amounts of time are in whole minutes.
| Field | Meaning |
|---|---|
period.start, period.end | The period used: start inclusive, end exclusive. |
period.basis | billing_period, last_30_days or custom (see above). |
calls.total | Calls created in the period, every status, test calls included. |
calls.completed | Calls that connected and ended normally. |
calls.durationSeconds | Talk time of completed calls, in seconds. |
calls.billedMinutes | Minutes charged for this workspace's calls in the period. |
calls.walletChargedInrPaise | Money taken from the wallet for calls in the period, in paise. |
plan | The current billing period of the workspace's plan, whatever period you asked for: name, slug, periodStart, periodEnd, minutesIncluded, minutesUsed, minutesRemaining, overageMinutes, overageAmountInrPaise. For a client workspace its agency pays for, this is the agency's shared plan. null without a plan. |
balance.balanceInrPaise | Wallet balance, in paise. |
balance.ratePerMinuteInrPaise | Price of a minute paid from the wallet, in paise. |
balance.minutesAtCurrentRate | Minutes the balance pays for at that rate; null when there is no rate. |
billingEnabled | Whether plan limits and wallet charges apply on this deployment. |
When billing is off
When billing is not enabled on the deployment, billingEnabled is false and balance is null. The request still succeeds, and period, calls and plan are filled in as usual. Check for null before reading balance.
{
"success": true,
"period": { "start": "2026-10-16T12:00:00Z", "end": "2026-11-15T12:00:00Z", "basis": "last_30_days" },
"calls": { "total": 58, "completed": 41, "durationSeconds": 3120.0, "billedMinutes": 0, "walletChargedInrPaise": 0 },
"plan": null,
"balance": null,
"billingEnabled": false
}