DocumentationAPI ReferenceChangelog

Envocal API

API Reference API Changelog

Endpoints

Get usage of a tenant GET
Usage

Get usage of a tenant

List conversations of a tenant GET

Newest first, paged. Combine the filters as needed. Get one conversation for its transcript and summary.

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

Authorization

Bearer
headerAuthorizationBearer <token>

Tenant API key (evk_…), created in Studio → Vault → API keys.

Path Parameters

tenantId*string

Tenant id, or current for the key's own tenant. Must be the key's tenant or one of its sub-tenants.

Query Parameters

from*string

Start of the period, inclusive, ISO 8601 UTC, e.g. 2026-09-01T00:00:00Z.

Formatdate-time
to*string

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.

Formatdate-time
includeSubtenants?boolean

Also report all sub-tenants. Default false: only this tenant.

Defaultfalse

Response Body

The usage report.

  1. response
  1. response
  2. …

Usage of a tenant (and optionally its sub-tenants) in a period, for billing. Voice conversations (phone, voice_chat) are measured in time; text chats (text_chat) in input and output tokens. Everything is split by whether the agent had a knowledge base during the conversation.

generatedAtUtc?string

When this report was generated (UTC).

Formatdate-time
period*

The requested period.

includeSubtenants?boolean

Whether sub-tenants are included.

tenant*

The requested tenant with its usage, and its sub-tenants when included.

Example Request
curl -X GET 'https://api.envocal.ai/v1/tenants/string/usage?from=2019-08-24T14%3A15%3A22Z&to=2019-08-24T14%3A15%3A22Z'
Example Response
{  "generatedAtUtc": "2019-08-24T14:15:22Z",  "period": {    "from": "2019-08-24T14:15:22Z",    "to": "2019-08-24T14:15:22Z"  },  "includeSubtenants": true,  "tenant": {    "id": "string",    "name": "string",    "extraId": "string",    "agents": [      {        "agentId": "string",        "agentName": "string",        "hasKnowledgeBase": true,        "voice": {          "conversations": 0,          "durationSeconds": 0,          "durationMinutes": 0.1,          "durationMmss": "string"        },        "text": {          "conversations": 0,          "inputTokens": 0,          "outputTokens": 0        }      }    ],    "totalDirect": {      "all": {        "voice": {          "conversations": 0,          "durationSeconds": 0,          "durationMinutes": 0.1,          "durationMmss": "string"        },        "text": {          "conversations": 0,          "inputTokens": 0,          "outputTokens": 0        }      },      "withKnowledgeBase": {        "voice": {          "conversations": 0,          "durationSeconds": 0,          "durationMinutes": 0.1,          "durationMmss": "string"        },        "text": {          "conversations": 0,          "inputTokens": 0,          "outputTokens": 0        }      },      "withoutKnowledgeBase": {        "voice": {          "conversations": 0,          "durationSeconds": 0,          "durationMinutes": 0.1,          "durationMmss": "string"        },        "text": {          "conversations": 0,          "inputTokens": 0,          "outputTokens": 0        }      }    },    "totalIncludingSubtenants": {      "all": {        "voice": {          "conversations": 0,          "durationSeconds": 0,          "durationMinutes": 0.1,          "durationMmss": "string"        },        "text": {          "conversations": 0,          "inputTokens": 0,          "outputTokens": 0        }      },      "withKnowledgeBase": {        "voice": {          "conversations": 0,          "durationSeconds": 0,          "durationMinutes": 0.1,          "durationMmss": "string"        },        "text": {          "conversations": 0,          "inputTokens": 0,          "outputTokens": 0        }      },      "withoutKnowledgeBase": {        "voice": {          "conversations": 0,          "durationSeconds": 0,          "durationMinutes": 0.1,          "durationMmss": "string"        },        "text": {          "conversations": 0,          "inputTokens": 0,          "outputTokens": 0        }      }    },    "subtenants": [      {}    ]  }}
Example Request
curl -X GET 'https://api.envocal.ai/v1/tenants/string/usage?from=2019-08-24T14%3A15%3A22Z&to=2019-08-24T14%3A15%3A22Z'
{
  "generatedAtUtc": "2019-08-24T14:15:22Z",
  "period": {
    "from": "2019-08-24T14:15:22Z",
    "to": "2019-08-24T14:15:22Z"
  },
  "includeSubtenants": true,
  "tenant": {
    "id": "string",
    "name": "string",
    "extraId": "string",
    "agents": [
      {
        "agentId": "string",
        "agentName": "string",
        "hasKnowledgeBase": true,
        "voice": {
          "conversations": 0,
          "durationSeconds": 0,
          "durationMinutes": 0.1,
          "durationMmss": "string"
        },
        "text": {
          "conversations": 0,
          "inputTokens": 0,
          "outputTokens": 0
        }
      }
    ],
    "totalDirect": {
      "all": {
        "voice": {
          "conversations": 0,
          "durationSeconds": 0,
          "durationMinutes": 0.1,
          "durationMmss": "string"
        },
        "text": {
          "conversations": 0,
          "inputTokens": 0,
          "outputTokens": 0
        }
      },
      "withKnowledgeBase": {
        "voice": {
          "conversations": 0,
          "durationSeconds": 0,
          "durationMinutes": 0.1,
          "durationMmss": "string"
        },
        "text": {
          "conversations": 0,
          "inputTokens": 0,
          "outputTokens": 0
        }
      },
      "withoutKnowledgeBase": {
        "voice": {
          "conversations": 0,
          "durationSeconds": 0,
          "durationMinutes": 0.1,
          "durationMmss": "string"
        },
        "text": {
          "conversations": 0,
          "inputTokens": 0,
          "outputTokens": 0
        }
      }
    },
    "totalIncludingSubtenants": {
      "all": {
        "voice": {
          "conversations": 0,
          "durationSeconds": 0,
          "durationMinutes": 0.1,
          "durationMmss": "string"
        },
        "text": {
          "conversations": 0,
          "inputTokens": 0,
          "outputTokens": 0
        }
      },
      "withKnowledgeBase": {
        "voice": {
          "conversations": 0,
          "durationSeconds": 0,
          "durationMinutes": 0.1,
          "durationMmss": "string"
        },
        "text": {
          "conversations": 0,
          "inputTokens": 0,
          "outputTokens": 0
        }
      },
      "withoutKnowledgeBase": {
        "voice": {
          "conversations": 0,
          "durationSeconds": 0,
          "durationMinutes": 0.1,
          "durationMmss": "string"
        },
        "text": {
          "conversations": 0,
          "inputTokens": 0,
          "outputTokens": 0
        }
      }
    },
    "subtenants": [
      {}
    ]
  }
}