# Workspace and usage (/guides/workspace-usage)

Two read-only endpoints tell your integration about the workspace it works in:

- [`GET /api/v1/workspace`](/api-reference/workspace/getWorkspace): which workspace and which key a request runs as.
- [`GET /api/v1/usage`](/api-reference/workspace/getUsage): 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](/authentication)).

## Check a key: GET /workspace [#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`](/errors/invalid_api_key), an expired one `401` [`api_key_expired`](/errors/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](/guides/agencies)).

<Callout title="Replaces GET /auth/me for keys">
`GET /auth/me` is a console endpoint. API keys get `403` [`api_key_route_forbidden`](/errors/api_key_route_forbidden) there and everywhere under `/auth`. Call `GET /api/v1/workspace` instead.
</Callout>

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
curl https://api.callmitra.ai/api/v1/workspace \
  -H "X-API-Key: $CALLMITRA_API_KEY"
```
</Tab>

<Tab value="Node.js">
```js
const res = await fetch('https://api.callmitra.ai/api/v1/workspace', {
  headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY },
});
if (res.status === 401) throw new Error('This API key is not valid');
const { workspace, apiKey } = await res.json();
console.log(`Connected to ${workspace.name} with ${apiKey.prefix}…`);
```
</Tab>

<Tab value="Python">
```python
import os
import requests

res = requests.get(
    "https://api.callmitra.ai/api/v1/workspace",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    timeout=30,
)
if res.status_code == 401:
    raise RuntimeError("This API key is not valid")
body = res.json()
print(f"Connected to {body['workspace']['name']} with {body['apiKey']['prefix']}…")
```
</Tab>
</Tabs>

```json title="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 }
}
```

| 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](/rate-limits). |

### Agency keys [#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`](/errors/permission_denied), never `404`.

```bash
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 [#read-usage-get-usage]

[`GET /api/v1/usage`](/api-reference/workspace/getUsage) reports one workspace: the one the request runs in (the client workspace when an agency key sends `X-Workspace-Id`).

### Choosing the period [#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`: 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`](/errors/parameter_invalid). A value that is not an ISO 8601 date or date-time answers the same code.

<Callout title="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.
</Callout>

<Tabs groupId="language" persist items={["cURL","Node.js","Python"]}>
<Tab value="cURL">
```bash
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"
```
</Tab>

<Tab value="Node.js">
```js
const url = new URL('https://api.callmitra.ai/api/v1/usage');
url.search = new URLSearchParams({
  from: '2026-11-01T00:00:00+05:30',
  to: '2026-12-01T00:00:00+05:30',
});
const res = await fetch(url, { headers: { 'X-API-Key': process.env.CALLMITRA_API_KEY } });
const usage = await res.json();
console.log(usage.calls.billedMinutes, 'minutes billed');
if (usage.balance) console.log('Balance: ₹', usage.balance.balanceInrPaise / 100);
```
</Tab>

<Tab value="Python">
```python
usage = requests.get(
    "https://api.callmitra.ai/api/v1/usage",
    headers={"X-API-Key": os.environ["CALLMITRA_API_KEY"]},
    params={"from": "2026-11-01T00:00:00+05:30", "to": "2026-12-01T00:00:00+05:30"},
    timeout=30,
).json()
print(usage["calls"]["billedMinutes"], "minutes billed")
if usage["balance"] is not None:
    print("Balance: ₹", usage["balance"]["balanceInrPaise"] / 100)
```
</Tab>
</Tabs>

```json title="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 [#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-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`.

```json
{
  "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
}
```

## Related [#related]

- [Authentication & API keys](/authentication)
- [Agencies & client workspaces](/guides/agencies)
- [Rate limits](/rate-limits)
- [Place and read calls](/guides/direct-calls)