> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knock2.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/tenants/{product_slug}/usage — Get a Tenant's Usage for a Window

> GET /v1/tenants/{product_slug}/usage returns a tenant's own usage (never its parent's or siblings') for a requested window. Requires tenants:read.

`GET /v1/tenants/{product_slug}/usage` returns a tenant's own usage — never its parent's or siblings' — for a requested window. Defaults to the tenant's current billing period.

## Endpoint

```text theme={null}
GET https://api.knock2.ai/v1/tenants/{product_slug}/usage
```

## Path Parameter

<ParamField path="product_slug" type="string" required>
  Your own tenant, or a direct child's slug.
</ParamField>

## Query Parameters

<ParamField query="period" default="billing_period" type="string">
  One of `billing_period`, `month`, `week`, `day`, or `lifetime`.
</ParamField>

## Example Request

```bash theme={null}
curl "https://api.knock2.ai/v1/tenants/acme_com_yourco_com/usage?period=month" \
  -H "Authorization: Bearer YOUR_PARENT_API_KEY"
```

## Response

```json theme={null}
{
  "data": {
    "product_slug": "acme_com_yourco_com",
    "period": "month",
    "window_start": "2026-08-01T00:00:00Z",
    "window_end": "2026-08-31T23:59:59Z",
    "unique_accounts": 12,
    "unique_contacts": 34,
    "total_credits": 46
  }
}
```

## Required Scope

Requires `tenants:read`.

## Error Responses

| Status | Meaning                                                      |
| ------ | ------------------------------------------------------------ |
| `400`  | `period` is not one of the supported values.                 |
| `401`  | Missing or invalid API key.                                  |
| `403`  | Your API key does not have the `tenants:read` scope.         |
| `404`  | No tenant found with this `product_slug` under your account. |
| `429`  | Rate limit exceeded.                                         |