# Usage: Get usage of a tenant (https://docs.envocal.ai/api-reference/usage/get-usage-of-a-tenant/)

> Usage in a period for billing: voice conversations (phone and web voice) in time, text chats in input and output tokens. Lines are per agent and knowledge-base state, and every total is split into with and without knowledge base, so different per-minute prices can be applied.

## GET `/v1/tenants/{tenantId}/usage`

Usage in a period for billing: voice conversations (phone and web voice) in time, text chats in input and output
tokens. Lines are per agent and knowledge-base state, and every total is split into with and without knowledge
base, so different per-minute prices can be applied.

With `includeSubtenants=true` the response nests all sub-tenants (to any depth) with their own lines and totals,
plus `totalIncludingSubtenants` at every level; sub-tenant branches without usage are left out.

Conversations are counted in the period they started in. Use `durationSeconds` for exact billing or
`durationMinutes` (decimal minutes) to multiply by a per-minute price.

**Required permission:** `usage:read`

### Parameters

| Name | In | | Type | Description |
| --- | --- | --- | --- | --- |
| `tenantId` | path | required | string | Tenant id, or `current` for the key's own tenant. Must be the key's tenant or one of its sub-tenants. |
| `from` | query | required | string (date-time) | Start of the period, inclusive, ISO 8601 UTC, e.g. `2026-09-01T00:00:00Z`. |
| `to` | query | required | string (date-time) | End of the period, exclusive, ISO 8601 UTC, e.g. `2026-10-01T00:00:00Z` for all of September. At most 366 days after `from`. |
| `includeSubtenants` | query |  | boolean | Also report all sub-tenants. Default false: only this tenant. |

### Responses

**200** — TenantUsageReportDto: The usage report.

| Field | Type | | Description |
| --- | --- | --- | --- |
| `generatedAtUtc` | string (date-time) |  | When this report was generated (UTC). |
| `period` | UsagePeriodDto | required | The requested period. |
| `includeSubtenants` | boolean |  | Whether sub-tenants are included. |
| `tenant` | TenantUsageDto | required | The requested tenant with its usage, and its sub-tenants when included. |

**400**: Missing or invalid `from`/`to`, `from` not before `to`, or a period longer than 366 days.

**401**: Missing, invalid, revoked or expired API key.

**403**: The key lacks the required permission, or the tenant/resource is outside its reach.

**404**: Tenant not found.

**429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header.

### Example

```bash
curl -X GET "https://api.envocal.ai/v1/tenants/current/usage" \
  -H "Authorization: Bearer evk_eu_..."
```