--- title: "Programmatic Usage Stats — AVCodex Docs" description: "Programmatic Usage Stats — AVCodex documentation for AV integrators, programmers, and ops teams." lang: en json-ld: --- [](/) Solutions [Pricing](/pricing)[The Signal](/blog)[Resources](/resources) Learn [Free AI Assessment](/scorecard)[Get Started →](/pricing) [Documentation Home](/docs) Guides Getting Started - [The Alchemist Copilot](/docs/guides/the-alchemist-copilot) - [Choosing a Model](/docs/guides/choosing-a-model) - [Skills & Templates](/docs/guides/skills-and-templates) - [Pricing & Usage](/docs/guides/pricing-and-usage) - [Understanding Tokens](/docs/guides/understanding-tokens) - [Maximize AVCodex Capabilities](/docs/guides/maximize-avcodex-capabilities) Knowledge & Memory - [How Knowledge Sources Work](/docs/guides/how-knowledge-sources-work) - [Knowledge Retrieval Settings](/docs/guides/knowledge-retrieval-settings) - [User Memory](/docs/guides/user-memory) - [Consumer Brain](/docs/guides/consumer-brain) Agent Capabilities - [Image Recognition](/docs/guides/image-recognition) - [Image Generation](/docs/guides/image-generation) - [Video Generation](/docs/guides/video-generation) - [Deep Research and Deep Thinking](/docs/guides/deep-research-and-deep-thinking) - [Heartbeat (Proactive AI Outreach)](/docs/guides/heartbeat-proactive-ai-outreach) - [Database Connections](/docs/guides/database-connections) - [Agent-to-Agent Links](/docs/guides/agent-to-agent-links) - [Message Tagging](/docs/guides/message-tagging) - [Lead Generation Forms](/docs/guides/lead-generation-forms) - [Multilingual Apps](/docs/guides/multilingual-apps) - [Understanding Evaluations](/docs/guides/understanding-evaluations) Design & Experience - [Style Studio](/docs/guides/style-studio) - [Component Studio](/docs/guides/component-studio) - [HQ Profile](/docs/guides/hq-profile) - [Multiplayer Chat](/docs/guides/multiplayer-chat) - [Circles](/docs/guides/circles) - [Desktop Agent](/docs/guides/desktop-agent) Voice & Phone - [Phone Numbers](/docs/guides/phone-numbers) - [Outbound Calling](/docs/guides/outbound-calling) - [Voice Cloning](/docs/guides/voice-cloning) Publish & Share - [Embed Chat Widget](/docs/guides/embed-chat-widget) - [Custom Domains](/docs/guides/custom-domains) - [PWA Installation](/docs/guides/pwa-installation) - [AVCodex Sites](/docs/guides/avcodex-sites) - [Embed on Kajabi](/docs/guides/embed-on-kajabi) - [How to Use AVCodex with Claude Code](/docs/guides/how-to-use-avcodex-with-claude-code) Monetization & Access - [Selling Access](/docs/guides/selling-access) - [Consumer Monetization](/docs/guides/consumer-monetization) - [Access Control](/docs/guides/access-control) - [Bring Your Own Auth](/docs/guides/bring-your-own-auth) - [Clever SSO for Schools](/docs/guides/clever-sso-for-schools) Analytics & Operations - [Analytics & Chat History](/docs/guides/analytics-and-chat-history) - [Performance Dashboard](/docs/guides/performance-dashboard) - [Programmatic Usage Stats](/docs/guides/programmatic-usage-stats) - [Session Lifecycle Webhooks](/docs/guides/session-lifecycle-webhooks) - [Audit Logs](/docs/guides/audit-logs) Teams & White-Label - [Team Management](/docs/guides/team-management) - [Enterprise Whitelabel](/docs/guides/enterprise-whitelabel) Alchemist Platform - [Alchemist Tickets](/docs/guides/alchemist-tickets) - [Alchemist Getting Started](/docs/guides/alchemist-getting-started) - [Alchemist Working with Tickets](/docs/guides/alchemist-working-with-tickets) - [Alchemist Local Development](/docs/guides/alchemist-local-development) Alchemist Operations - [Alchemist Environment Variables](/docs/guides/alchemist-environment-variables) - [Alchemist Deploys and Domains](/docs/guides/alchemist-deploys-and-domains) - [Alchemist Self-Healing](/docs/guides/alchemist-self-healing) Alchemist API & Automation - [Alchemist API Keys](/docs/guides/alchemist-api-keys) - [Alchemist MCP Server](/docs/guides/alchemist-mcp-server) - [Alchemist Pipeline Configuration](/docs/guides/alchemist-pipeline-configuration) - [Alchemist Pipeline Permutations](/docs/guides/alchemist-pipeline-permutations) Developer Platform - [Building Custom MCP Servers](/docs/guides/building-custom-mcp-servers) - [Consumer OAuth for Custom MCP Servers](/docs/guides/consumer-oauth-for-custom-mcp-servers) AVCodex MCP Server - [Overview](/docs/guides/overview) - [MCP Reference](/docs/guides/mcp-reference) - [Setup & Installation](/docs/guides/setup-and-installation) - [Authentication](/docs/guides/authentication) - [Tools Reference](/docs/guides/tools-reference) - [Common Workflows](/docs/guides/common-workflows) - [Rate Limits](/docs/guides/rate-limits) Custom Actions Pro Actions API Builder API Agentic Commerce (ACP) Integrations [Docs](/docs)/ Guides / Analytics & Operations # Programmatic Usage Stats Last updated · MAR 2026 · [Read as Markdown](/docs/guides/programmatic-usage-stats.md) # Get Your App's Own Usage Stats Set up your AI agent to fetch and send its own activity reports: daily, weekly, or on demand. * * * Your agent can report its own usage ("47 conversations this week, 12 unique people, 318 messages") without anyone logging into the dashboard. You set this up by chatting with the Alchemist copilot. No code, and no copy-pasting API keys into config files. ## [What you'll build# ](#what-you-ll-build) A new tool on your app called `fetch_my_app_usage` (name it whatever you like). You can use it three ways: - **In chat.** Ask your agent "how many conversations did we have this week?" and it answers with live numbers. - **In the Heartbeat.** Schedule the agent to email you a weekly summary automatically. - **From any channel.** WhatsApp, Slack, email, anywhere your agent runs. > **Note:** This setup uses [Custom Actions](/docs/custom-actions/overview) and, for the optional scheduled summary, [Heartbeat](/docs/guides/heartbeat-proactive-ai-outreach). Both require a Builder plan or higher. The Builder API itself has no tier gate, but the custom HTTP action that calls it does. ## [Step 1: Ask the Alchemist to set it up# ](#step-1-ask-the-alchemist-to-set-it-up) Open the app you want to monitor and open the Alchemist panel. Paste a prompt along these lines: code ``` Set up a tool so this app can fetch its own usage stats. Use the Builder API at /api/v1/apps/{appId}/analytics/usage. Create the Builder API key, save it as a secret variable, and wire up the custom action. Name the tool fetch_my_app_usage. ``` The Alchemist creates the Builder API key, stores it as a secret variable so it never appears in your prompt or in chat, and wires the custom action to the analytics endpoint. ## [Step 2: Test it in chat# ](#step-2-test-it-in-chat) Ask your agent directly: > "How many conversations did we have in the last 7 days?" You should get live numbers back. If the agent says it doesn't have that tool, check that the action saved and that the secret variable resolved. ## [Step 3 (optional): Schedule a recurring report# ](#step-3-optional-schedule-a-recurring-report) Add a Heartbeat that runs weekly and instructs the agent to call `fetch_my_app_usage` and email the summary to you. See [Heartbeat](/docs/guides/heartbeat-proactive-ai-outreach) for scheduling and delivery channels. ## [Why integrators use this# ](#why-integrators-use-this) The reporting problem in managed AV services is not gathering the data. It is remembering to send it. A weekly automated summary to the account owner turns your support agent into visible, recurring proof of value, which is what renewal conversations run on. A useful pattern: have the Heartbeat send the client-facing summary to the client's facilities lead, and a separate internal summary to your service manager with the deflection numbers. ## [Security note# ](#security-note) The Builder API key is stored as a secret variable, which means it is never rendered into the system prompt or exposed in conversation. Do not paste the raw key into your prompt text as a workaround. If you need to rotate it, ask the Alchemist to regenerate rather than editing the variable by hand. \*AVCodex · Your AV expertise. Amplified by AI.\* Was this helpful? [Edit this page →](#) [ Previous Performance Dashboard ](/docs/guides/performance-dashboard)[ Next Session Lifecycle Webhooks ](/docs/guides/session-lifecycle-webhooks) On this page - [What you'll build](#what-you-ll-build) - [Step 1: Ask the Alchemist to set it up](#step-1-ask-the-alchemist-to-set-it-up) - [Step 2: Test it in chat](#step-2-test-it-in-chat) - [Step 3 (optional): Schedule a recurring report](#step-3-optional-schedule-a-recurring-report) - [Why integrators use this](#why-integrators-use-this) - [Security note](#security-note) [](/) The AI platform built exclusively for professional AV. Build, deploy, and sell AI tools that understand your industry. ### Platform - What You Can Build - Templates - [Pricing](/pricing) ### Services - [Done-For-You](/pricing) - [Academy](/academy) - [Contact](/contact) ### Company - About - [The Signal](/blog) - [Docs](/docs) - [LinkedIn](#) © 2026 AVCodex. A Future Ready Holdings Inc. product. SOC 2 Type II Certified · HIPAA Compliant