Skip to Content
CallMitraDocs

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:

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 401 invalid_api_key, an expired one 401 api_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"
200 OK
{
  "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 }
}
FieldMeaning
workspace.id, workspace.nameThe workspace the request runs in.
workspace.parentIdThe agency workspace this client workspace belongs to; null for a workspace that is not a client.
apiKey.id, apiKey.nameThe 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.prefixThe first characters of the key, as shown in the console. The secret is never returned.
apiKey.scopes.accessfull, or read (read-only keys may only send GET).
apiKey.scopes.resourcesResource groups the key may reach. An empty list means all of them.
apiKey.expiresAtWhen the key stops working; null if never.
rateLimit.limitRequests 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

ParameterFormatMeaning
fromISO 8601 date or date-timeStart of the period, inclusive. A date-time without an offset is UTC. A bare date (2026-11-01) means 00:00 UTC that day.
toISO 8601 date or date-timeEnd 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: from from until now.
  • Only to: the 30 days before to.
  • With either sent, basis is custom.
  • from must be before to, and the range can cover at most 366 days. Otherwise 422 parameter_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"
200 OK
{
  "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.

FieldMeaning
period.start, period.endThe period used: start inclusive, end exclusive.
period.basisbilling_period, last_30_days or custom (see above).
calls.totalCalls created in the period, every status, test calls included.
calls.completedCalls that connected and ended normally.
calls.durationSecondsTalk time of completed calls, in seconds.
calls.billedMinutesMinutes charged for this workspace's calls in the period.
calls.walletChargedInrPaiseMoney taken from the wallet for calls in the period, in paise.
planThe 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.balanceInrPaiseWallet balance, in paise.
balance.ratePerMinuteInrPaisePrice of a minute paid from the wallet, in paise.
balance.minutesAtCurrentRateMinutes the balance pays for at that rate; null when there is no rate.
billingEnabledWhether 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
}

On this page