Get Dashboard Stats

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

GET https://asteragents.com/api/dashboard/getStats

Get Dashboard Stats

cURL

curl --request GET \
  --url https://asteragents.com/api/dashboard/getStats \
  --header 'Authorization: Bearer <token>'

200

{
  "403": {},
  "500": {},
  "conversationCount": 123,
  "messageCount": 123,
  "toolCalls": 123,
  "totalTokens": 123,
  "inputTokens": 123,
  "outputTokens": 123,
  "uniqueUsers": 123,
  "uniqueAgents": 123,
  "totalFeedback": 123,
  "totalHelpful": 123,
  "totalNotHelpful": 123,
  "kbFileCount": 123,
  "kbCount": 123,
  "kbExtractTotalTokens": 123,
  "kbExtractInputTokens": 123,
  "kbExtractOutputTokens": 123
}

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

from · string · required

Start date for the query range (ISO 8601 format, e.g., “2024-01-01T00:00:00.000Z”)

to · string · required

End date for the query range (ISO 8601 format, e.g., “2024-12-31T23:59:59.999Z”)

allInOrg · boolean · default: "false"

Whether to include stats for all users in the organization. Requires org:admin role.

agentId · string

Filter results to a specific agent ID

userId · string

Filter results to a specific user ID (admin only when allInOrg is true)

metadataKey · string

Filter by a specific metadata key in user’s organization-scoped metadata

metadataValue · string

Filter by a specific metadata value. Can be used with or without metadataKey. Only searches within the current organization.

Response

conversationCount · number

Total number of unique conversations

messageCount · number

Total number of messages across all conversations

toolCalls · number

Total number of tool invocations across all messages

totalTokens · number

Total token usage across all conversations

inputTokens · number

Total input tokens (user messages and system prompts) across all conversations

outputTokens · number

Total output tokens (assistant responses) across all conversations

uniqueUsers · number

Number of unique users who participated in conversations

uniqueAgents · number

Number of unique agents used in conversations

totalFeedback · number

Total number of feedback responses (helpful + not helpful)

totalHelpful · number

Number of positive feedback responses

totalNotHelpful · number

Number of negative feedback responses

kbFileCount · number

Total number of knowledge base files processed in the date range (organization-wide, not filtered by user or agent)

kbCount · number

Number of distinct knowledge bases with files processed in the date range

kbExtractTotalTokens · number

Total tokens consumed by LLM-based document extraction across all knowledge base files in the date range

kbExtractInputTokens · number

Input tokens consumed by LLM-based document extraction (document content sent to the model)

kbExtractOutputTokens · number

Output tokens consumed by LLM-based document extraction (structured data generated by the model)

Examples

Basic Request

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"

Error Codes

403 · object

Forbidden - User lacks required permissions (e.g., non-admin trying to use allInOrg=true)

500 · object

Internal Server Error - Server encountered an unexpected condition

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