# 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

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

Open the app you want to monitor and open the Alchemist panel. Paste a prompt along these lines:

```
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

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

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

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

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.*