API: Open Chat Studio v2
Description: Build, deploy and monitor chatbots.

TAG: Usage
Description: Inspect team usage and activity data (message counts, and more).

ENDPOINTS:

GET /api/v2/usage/
  Summary: Usage
  Description: Return team-scoped usage data for a time window.

Each `metric` you request gets its own block in the response:

- **`messages`** — human / AI / total message counts
- **`sessions`** — session count
- **`participants`** — distinct active-participant count
- **`cost`** — total spend and currency
- **`tokens`** — prompt / completion / total token counts

**Time window.** Either a calendar `period` (current / previous month) or an explicit `start` / `end` range — `start` is included and `end` is excluded.

**Shape of `results`.**

- With `granularity` finer than `total`, `results` is one row per time bucket.
- With `group_by` set, `results` is cursor-paginated breakdown rows — one per group, or one per (group, bucket) when combined with a finer granularity.

Optionally narrowed by `participant`, `chatbot`, or `platform`.

> **Tip:** The **Response samples** panel has worked examples for the common cases — pick one from the **Example** dropdown (single participant, cost + tokens, grouped breakdowns, and daily timeseries).
  Parameters:
    - chatbot (query, string (optional)): Restrict to a single chatbot by its ``public_id``.
    - end (query, string (optional)): Exclusive end of an explicit window (ISO date or datetime). Requires 'start'.
    - granularity (query, string (optional)): Time-bucketing of results. 'total' (default) returns a single object; the others return one row per bucket, each carrying 'bucket_start'.

* `total` - total
* `daily` - daily
* `weekly` - weekly
* `monthly` - monthly
    - group_by (query, string (optional)): Break the results down by this dimension: one row per group, cursor-paginated. Combines with 'granularity' to give one row per (group, time bucket).

* `participant` - participant
* `chatbot` - chatbot
* `platform` - platform
    - metric (query, array (required)): Metrics to return; repeat the parameter for several.
    - participant (query, string (optional)): Restrict to a single participant by their ``public_id``.
    - participant_identifier (query, string (optional)): Restrict to a single participant by their raw identifier (email/phone).
    - period (query, string (optional)): Calendar month to report on, evaluated in the given timezone. Mutually exclusive with 'start'/'end'; defaults to the current month when no explicit window is given.

* `current_month` - current_month
* `previous_month` - previous_month
    - platform (query, string (optional)): Restrict to a single channel platform by its slug (e.g. 'web', 'whatsapp').

* `telegram` - telegram
* `web` - web
* `whatsapp` - whatsapp
* `facebook` - facebook
* `sureadhere` - sureadhere
* `api` - api
* `slack` - slack
* `commcare_connect` - commcare_connect
* `embedded_widget` - embedded_widget
* `email` - email
    - start (query, string (optional)): Inclusive start of an explicit window (ISO date or datetime). Requires 'end'.
    - tz (query, string (optional)): IANA timezone name defining calendar and bucket boundaries. Defaults to UTC.
  Responses:
    200:
      Content: application/json
      Schema: UsageResponseOrGrouped
  Security:
    OAuth2
      - Required scopes: usage:read
    apiKeyAuth
    tokenAuth

SCHEMAS:

UsageResponseOrGrouped:
  - type: unknown

SECURITY:
- OAuth2
  - Authorization Code Flow (authorization url: /o/authorize/, token url: /o/token/)
- API Key authentication (header: X-api-key)
- HTTP bearer authentication