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

# Get Dashboard Stats

> Retrieve aggregated analytics and KPIs for conversations, messages, and user activity

Returns high-level statistics and metrics for dashboard reporting and automation.

## Authentication

This endpoint requires a valid JWT token from Clerk authentication. The token must include organization membership.

## Query Parameters

<ParamField query="from" type="string" required>
  Start date for the query range (ISO 8601 format, e.g., "2024-01-01T00:00:00.000Z")
</ParamField>

<ParamField query="to" type="string" required>
  End date for the query range (ISO 8601 format, e.g., "2024-12-31T23:59:59.999Z")
</ParamField>

<ParamField query="allInOrg" type="boolean" default="false">
  Whether to include stats for all users in the organization. Requires `org:admin` role.
</ParamField>

<ParamField query="agentId" type="string">
  Filter results to a specific agent ID
</ParamField>

<ParamField query="userId" type="string">
  Filter results to a specific user ID (admin only when `allInOrg` is true)
</ParamField>

<ParamField query="metadataKey" type="string">
  Filter by a specific metadata key in user's organization-scoped metadata
</ParamField>

<ParamField query="metadataValue" type="string">
  Filter by a specific metadata value. Can be used with or without metadataKey. Only searches within the current organization.
</ParamField>

## Response

<ResponseField name="conversationCount" type="number">
  Total number of unique conversations
</ResponseField>

<ResponseField name="messageCount" type="number">
  Total number of messages across all conversations
</ResponseField>

<ResponseField name="toolCalls" type="number">
  Total number of tool invocations across all messages
</ResponseField>

<ResponseField name="totalTokens" type="number">
  Total token usage across all conversations
</ResponseField>

<ResponseField name="inputTokens" type="number">
  Total input tokens (user messages and system prompts) across all conversations
</ResponseField>

<ResponseField name="outputTokens" type="number">
  Total output tokens (assistant responses) across all conversations
</ResponseField>

<ResponseField name="uniqueUsers" type="number">
  Number of unique users who participated in conversations
</ResponseField>

<ResponseField name="uniqueAgents" type="number">
  Number of unique agents used in conversations
</ResponseField>

<ResponseField name="totalFeedback" type="number">
  Total number of feedback responses (helpful + not helpful)
</ResponseField>

<ResponseField name="totalHelpful" type="number">
  Number of positive feedback responses
</ResponseField>

<ResponseField name="totalNotHelpful" type="number">
  Number of negative feedback responses
</ResponseField>

<ResponseField name="kbFileCount" type="number">
  Total number of knowledge base files processed in the date range (organization-wide, not filtered by user or agent)
</ResponseField>

<ResponseField name="kbCount" type="number">
  Number of distinct knowledge bases with files processed in the date range
</ResponseField>

<ResponseField name="kbExtractTotalTokens" type="number">
  Total tokens consumed by LLM-based document extraction across all knowledge base files in the date range
</ResponseField>

<ResponseField name="kbExtractInputTokens" type="number">
  Input tokens consumed by LLM-based document extraction (document content sent to the model)
</ResponseField>

<ResponseField name="kbExtractOutputTokens" type="number">
  Output tokens consumed by LLM-based document extraction (structured data generated by the model)
</ResponseField>

### Examples

<CodeGroup>
  ```curl Basic Request theme={null}
  curl -X GET "https://asteragents.com/api/dashboard/getStats?from=2024-01-01T00:00:00.000Z&to=2024-12-31T23:59:59.999Z&allInOrg=true" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN"
  ```

  ```curl With Filters theme={null}
  curl -X GET "https://asteragents.com/api/dashboard/getStats?from=2024-01-01T00:00:00.000Z&to=2024-12-31T23:59:59.999Z&agentId=123&metadataKey=department&metadataValue=engineering" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN"
  ```

  ```javascript theme={null}
  const response = await fetch('/api/dashboard/getStats?' + new URLSearchParams({
    from: '2024-01-01T00:00:00.000Z',
    to: '2024-12-31T23:59:59.999Z',
    allInOrg: 'true',
    agentId: '123'
  }), {
    headers: {
      'Authorization': 'Bearer ' + token
    }
  });

  const stats = await response.json();
  ```

  ```python theme={null}
  import requests

  response = requests.get(
      'https://asteragents.com/api/dashboard/getStats',
      params={
          'from': '2024-01-01T00:00:00.000Z',
          'to': '2024-12-31T23:59:59.999Z',
          'allInOrg': 'true'
      },
      headers={'Authorization': f'Bearer {token}'}
  )

  stats = response.json()
  ```

  ```json Response theme={null}
  {
    "conversationCount": 1247,
    "messageCount": 8934,
    "toolCalls": 2156,
    "totalTokens": 487293,
    "inputTokens": 324567,
    "outputTokens": 162726,
    "uniqueUsers": 89,
    "uniqueAgents": 12,
    "totalFeedback": 456,
    "totalHelpful": 389,
    "totalNotHelpful": 67,
    "kbFileCount": 342,
    "kbCount": 5,
    "kbExtractTotalTokens": 89234,
    "kbExtractInputTokens": 72891,
    "kbExtractOutputTokens": 16343
  }
  ```
</CodeGroup>

### Error Codes

<ResponseField name="403" type="object">
  Forbidden - User lacks required permissions (e.g., non-admin trying to use `allInOrg=true`)
</ResponseField>

<ResponseField name="500" type="object">
  Internal Server Error - Server encountered an unexpected condition
</ResponseField>

## Notes

* All dates should be provided in ISO 8601 format
* When `allInOrg=true`, only users with `org:admin` role can access organization-wide data
* **Metadata filtering is organization-scoped**: Only searches within the current organization's user metadata
* Metadata filtering supports flexible querying across user's publicMetadata JSON field
* Token counts include both input and output tokens from conversations
* Tool calls are counted across all message toolInvocations arrays
* Knowledge base stats (`kbFileCount`, `kbCount`, `kbExtractTotalTokens`, `kbExtractInputTokens`, `kbExtractOutputTokens`) are always organization-wide and are not filtered by `userId`, `agentId`, or metadata parameters