Skip to main content
The analytics API gives plugins read access to aggregated session data.

​
Usage

import { createPlugin } from "openclaw/plugin-sdk"

export default createPlugin({
  name: "my-analytics-plugin",
  setup(sdk) {
    sdk.registerCommand({
      name: "stats",
      description: "Show your session statistics",
      async run({ userId }) {
        const stats = await sdk.runtime.analytics.getStats({ userId })
        return `Messages: ${stats.messageCount}, Tokens: ${stats.totalTokens}`
      },
    })
  },
})

​
Methods

runtime.analytics.getStats(opts: {
  userId: string
  since?: string   // ISO-8601
  until?: string
}): Promise<AnalyticsStats>

runtime.analytics.getGlobalStats(opts?: {
  since?: string
  until?: string
}): Promise<GlobalAnalyticsStats>

runtime.analytics.getSessions(opts: {
  userId: string
  limit?: number    // default: 10
  offset?: number
}): Promise<SessionSummary[]>

​
Types

interface AnalyticsStats {
  userId: string
  messageCount: number
  totalTokens: number
  avgResponseMs: number
  activeDays: number
  period: { since: string; until: string }
}

interface SessionSummary {
  sessionId: string
  userId: string
  startedAt: string
  lastActiveAt: string
  messageCount: number
  totalTokens: number
}

​
Access control

A plugin can only read stats for the user who triggered the current request, unless it has been granted admin capability in its manifest.