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

# Get usage counts for a time window

> Conversation, question and answer counts for your organisation over a trailing or explicit window. Counts and rates only: no question or answer text is given.

Returns counts and rates for your organization only. The response never contains question or answer text. See [Analytics](/administration/analytics) for how to read the numbers.

Choose the window in one of two ways: `days` for a trailing window ending now, or an explicit `start` and `end` pair. Sending both forms returns `400`. With neither, you get the last 30 days. The window is half-open, `[start, end)`, and may span at most 366 days.

Filtering by `assistant_id` narrows every count to that assistant. An ID that belongs to another organization, or to no assistant, is not an error: it matches nothing and every count is `0`.

Requires the owner, admin or editor role. Members and dataset operators receive `403`.

<ParamField query="days" type="integer" default="30">
  Length of a trailing window ending now, from 1 to 366. ASCII digits only. Cannot be combined with
  `start` or `end`.
</ParamField>

<ParamField query="start" type="string">
  Start of an explicit window, as an ISO 8601 timestamp with a UTC offset (for example
  `2026-09-01T00:00:00Z`). A timestamp without an offset is refused. Requires `end`.
</ParamField>

<ParamField query="end" type="string">
  End of an explicit window, exclusive, as an ISO 8601 timestamp with a UTC offset. Must be after
  `start`, and no more than 366 days after it. Requires `start`.
</ParamField>

<ParamField query="assistant_id" type="string">
  Limit the counts to one assistant (UUID). A malformed ID returns `400`.
</ParamField>

## Response

<ResponseField name="window" type="object" required>
  The window the counts cover.

  <Expandable title="properties">
    <ResponseField name="start" type="string" required>
      Inclusive start, ISO 8601 in UTC.
    </ResponseField>

    <ResponseField name="end" type="string" required>
      Exclusive end, ISO 8601 in UTC.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conversations" type="integer" required>
  Conversations started in the window.
</ResponseField>

<ResponseField name="questions" type="integer" required>
  Questions asked in the window.
</ResponseField>

<ResponseField name="answers" type="integer" required>
  Answers started in the window that have finished, whether complete, interrupted or failed. Answers
  still in progress are not counted.
</ResponseField>

<ResponseField name="grounded_answers" type="integer" required>
  Finished answers that carried at least one citation.
</ResponseField>

<ResponseField name="abstained_answers" type="integer" required>
  Finished answers where the assistant declined to answer because its sources did not cover the
  question. See [How answers work](/concepts/how-answers-work).
</ResponseField>

<ResponseField name="failed_answers" type="integer" required>
  Answers that failed before producing a usable result.
</ResponseField>

<ResponseField name="grounded_rate" type="number | null" required>
  `grounded_answers / answers`, from 0 to 1. `null` when `answers` is `0`, meaning not applicable
  rather than zero.
</ResponseField>

<ResponseField name="abstention_rate" type="number | null" required>
  `abstained_answers / answers`, or `null` when `answers` is `0`.
</ResponseField>

<ResponseField name="failure_rate" type="number | null" required>
  `failed_answers / answers`, or `null` when `answers` is `0`.
</ResponseField>

<ResponseField name="models" type="object[]" required>
  Answers per model, highest count first, at most 50 entries.

  <Expandable title="properties">
    <ResponseField name="model" type="string" required>
      The model that produced the answers.
    </ResponseField>

    <ResponseField name="answers" type="integer" required>
      How many answers it produced.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="channels" type="object[]" required>
  Questions by the kind of caller that asked, highest count first.

  <Expandable title="properties">
    <ResponseField name="channel" type="string" required>
      `user` for a signed-in console user, `service` for an API key (including MCP clients),
      `widget` for a website widget visitor.
    </ResponseField>

    <ResponseField name="questions" type="integer" required>
      Questions from that channel.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl --request GET "$MITHUNAI_URL/arukz/api/v1/analytics/usage?days=7" \
    --header "Authorization: Bearer $MITHUNAI_API_KEY"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os, requests

  response = requests.get(
      f"{os.environ['MITHUNAI_URL']}/arukz/api/v1/analytics/usage",
      headers={"Authorization": f"Bearer {os.environ['MITHUNAI_API_KEY']}"},
      params={"days": 7},
      timeout=60,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const params = new URLSearchParams({ days: '7' })
  const response = await fetch(`${process.env.MITHUNAI_URL}/arukz/api/v1/analytics/usage?${params}`, {
    headers: { Authorization: `Bearer ${process.env.MITHUNAI_API_KEY}` },
  })
  console.log(await response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "window": {
      "start": "2026-09-17T10:00:03.214557+00:00",
      "end": "2026-09-24T10:00:03.214557+00:00"
    },
    "conversations": 412,
    "questions": 968,
    "answers": 961,
    "grounded_answers": 842,
    "abstained_answers": 104,
    "failed_answers": 15,
    "grounded_rate": 0.8761706555671176,
    "abstention_rate": 0.10822060353798127,
    "failure_rate": 0.015608740894901144,
    "models": [{ "model": "anthropic/claude-sonnet-5", "answers": 961 }],
    "channels": [
      { "channel": "widget", "questions": 713 },
      { "channel": "user", "questions": 171 },
      { "channel": "service", "questions": 84 }
    ]
  }
  ```

  ```json 400 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "code": "validation_error",
    "message": "Ask for either 'days' or a 'start' and 'end' pair, not both."
  }
  ```

  ```json 403 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "code": "authorization_error", "message": "You do not have permission to perform this action." }
  ```
</ResponseExample>