# Get Your App's Own Usage Stats

Set up your AI chatbot to fetch and send its own activity reports -- daily, weekly, or on demand. No coding required.

---

Your chatbot can send you (or any team member) regular usage reports -- *"You had 47 conversations this week, 12 unique people, 318 messages"* -- without you ever logging into the dashboard. This guide walks through setting it up by chatting with the Alchemist. No code, no copy-paste of API keys into config files.

## What you'll build

By the end, your app will have a new tool called `fetch_my_app_usage` (you can name it anything). You can use it three ways:

- **In chat**: ask your bot *"how many conversations did we have this week?"* and it'll answer with live numbers.
- **In the Heartbeat**: schedule the bot to email you a weekly summary automatically.
- **From any channel**: WhatsApp, Slack, email -- anywhere your bot runs.

> **Note:** This setup uses **Custom Actions** and (for the optional weekly summary) **Heartbeat**, both of which require a **Builder plan or higher**. The Builder API itself has no tier gate, but the custom HTTP action that calls it does.
> <a
> href="https://build.chipp.ai/plans"
> target="_blank"
> rel="noopener noreferrer"
>
> >
> Upgrade to Builder →
> </a>

## Before you start

You'll need:
- A Chipp app you've already created on a **Builder** plan or higher
- Access to the Alchemist panel (the AI assistant on the right side of the builder)
- About 5 minutes

## Step 1 -- Ask the Alchemist to set everything up


  **1.** 
    <strong>Open your app and open the Alchemist</strong>

    Go to [build.chipp.ai](https://build.chipp.ai), open the app you want to monitor, and click the Alchemist panel on the right (the AI assistant).
  


  **2.** 
    <strong>Paste this prompt into the Alchemist</strong>

    ```
    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
    called BUILDER_API_KEY, and wire it into a custom HTTP action
    called fetch_my_app_usage.
    ```

    The Alchemist will respond in three stages:

    1. **Create the API key.** The Alchemist mints a Builder API key for this app and shows you the raw value once -- it starts with `chipp_`. Save it somewhere safe (your password manager, a sticky note, anywhere offline). You won't see the raw key again. *If you lose it, ask the Alchemist to revoke the old key and create a new one -- your data isn't lost, only the key.*

    2. **Open a secure form.** The Alchemist will pop up a form titled "Builder API Key" (or similar) with a single field. **Paste the raw key into the form and click Save.** The value is encrypted on our servers; nobody, including Chipp staff, can read it back.

    3. **Build the custom action.** The Alchemist creates a new HTTP action called `fetch_my_app_usage`. You'll see it appear under **Build → Actions** in your app (scroll past the integrations to the Custom Actions card). The action's `Authorization` header is wired to `Bearer {{var.BUILDER_API_KEY}}`, so the encrypted key is substituted in only when the action runs -- it never appears in chat history or logs.
  


  **3.** 
    <strong>Verify it worked</strong>

    Still in the Alchemist chat, type:

    ```
    Test the fetch_my_app_usage action and show me the result.
    ```

    You should see a JSON response with a `summary` object containing `total_sessions`, `unique_consumers`, and `total_messages`, plus a `timeseries` array. If you instead see a 401 Unauthorized error, the key was pasted wrong -- ask the Alchemist *"Re-collect the BUILDER_API_KEY value"* and repeat stage 2.
  


## Step 2 -- Test it in the deployed chat

Open your app's public chat (Publish → Share → open your chat URL) and try:

- *"How many conversations have we had this week?"*
- *"Give me a usage summary for the last 30 days."*
- *"Compare this week to last week."*

Your bot will call `fetch_my_app_usage` behind the scenes and answer with live numbers from the database. The numbers are the same ones you'd see on the **Insights → Overview** page in the builder.

> **Warning:** Live conversation counts include sessions still in progress. If you want strict "completed conversations only", phrase your question like *"how many ended conversations did we have this week"* -- the bot will pick the right filter from the response.

## Step 3 -- Wire it into the Heartbeat (optional)

The [Heartbeat](/docs/guides/heartbeat) is a separate feature that lets your bot proactively message you (or your customers) on a schedule. Because the Heartbeat agent loop shares the same tools as regular chat, your new `fetch_my_app_usage` action is automatically available to it -- no extra wiring.


  **1.** 
    <strong>Open Heartbeat settings</strong>

    From your app, navigate to **Publish → Heartbeat**.
  


  **2.** 
    <strong>Enable Heartbeat and pick a schedule</strong>

    Toggle on **Enable heartbeat**. Choose:
    - **Schedule**: *Weekly, Monday at 9:00 AM* (or daily, or every-N-hours)
    - **Channel**: *Email* (so the report lands in your inbox)
    - **Recipients**: add your own email under **Additional recipients** or **Curated list**
  


  **3.** 
    <strong>Write the heartbeat instructions</strong>

    In the **Instructions** field, paste something like:

    ```
    Every Monday morning, call fetch_my_app_usage to get the past
    week's stats and email me a short summary. Format it like:

    "Here's your weekly report for {date range}:
    - {N} conversations
    - {N} unique people
    - {N} total messages"

    If conversations are up 20%+ from the previous week, mention the
    growth. If they're down 20%+, flag it as a heads-up. Always send
    the report on Mondays, even if nothing changed.
    ```

    The last sentence matters: by default Heartbeat suppresses messages when the AI decides there's nothing worth saying. Telling it to *always* send the report overrides that for reporting use cases.
  


  **4.** 
    <strong>Send a test</strong>

    Scroll to the **Test Heartbeat** card at the bottom, pick your own account in the consumer picker, and click **Send Test**. You should get an email within ~30 seconds. From then on, the heartbeat runs on the schedule you picked.
  


## What stats are available?

Two endpoints today, both read-only:

| Endpoint | Returns |
|----------|---------|
| `/api/v1/apps/{appId}/analytics/usage` | Total sessions, unique consumers, total messages, plus a day/week/month timeseries |
| `/api/v1/apps/{appId}/analytics/token-usage` | Total tokens consumed (input/output), per-model breakdown -- useful for cost monitoring |

See the full [Analytics endpoint reference](/docs/builder-api/analytics) for query parameters and response fields.

If you want **per-model token costs** in your weekly email, repeat Step 1 with a second prompt:

```
Create a second custom action called fetch_my_token_usage that calls
/api/v1/apps/{appId}/analytics/token-usage with the same
BUILDER_API_KEY variable I already saved.
```

The Alchemist will reuse the secret variable you already saved -- no new key needed.

## How the security works (short version)

- The Builder API key starts with `chipp_` and is **scoped to a single app**. It can't read another app's data.
- The raw key is shown to you exactly once at creation. We store only a SHA-256 hash. You can't recover the raw key from us -- only revoke and replace it.
- When you saved the key into the secure form, it was encrypted with the platform's per-app encryption key. The custom action references it via `{{var.BUILDER_API_KEY}}`, which the platform substitutes server-side at runtime. The raw value never appears in chat history, the Alchemist's tool arguments, or any log file.
- To revoke a key (for rotation or after a leak), ask the Alchemist *"Revoke the Builder API key called 'Weekly stats reader'"* (or whatever you named it). Old custom actions will start returning `401 Unauthorized`. Mint a new key and update the secret variable to replace it.

See the [Variables and Secrets](/docs/custom-actions/variables) reference for more on how secret variables are stored.

## Troubleshooting

| Symptom | Cause | Fix |
|---------|-------|-----|
| Alchemist says "I created the variable but the value is empty" | You closed the secure form without pasting the key | Ask the Alchemist *"Re-collect the BUILDER_API_KEY value"* and paste the raw key |
| Bot says "I couldn't fetch usage" or shows a 401 | Key was pasted wrong, or the key was revoked | Mint a new key with *"Create a new Builder API key and update BUILDER_API_KEY"* |
| Bot says "I don't know how to do that" | The custom action wasn't actually created | Check **Build → Actions** -- if `fetch_my_app_usage` isn't listed in the Custom Actions card, repeat Step 1 |
| Heartbeat email never arrives | The AI decided nothing needed reporting | Add *"Always send the report, even when there's no change"* to your heartbeat instructions |
| You want to share this report with a team member | They don't need the API key -- the bot itself does the fetching | Just add their email to the heartbeat's recipient list |

## What's next

- **Schedule per-customer digests**, not just self-reports: in your heartbeat instructions, ask the bot to compose personalized summaries for each consumer. The bot still has access to `fetch_my_app_usage` for org-wide context.
- **Pull stats into Google Sheets**: build a second app on Chipp that calls the Builder API on a schedule and writes results to a sheet via the Google Sheets hosted integration.
- **Cross-app dashboards**: Builder API keys are scoped per-app. To monitor several apps from one place, mint a key per app, save each as a separate secret variable in your dashboard app (e.g. `STATS_KEY_APP_A`, `STATS_KEY_APP_B`), and create one custom action per app.

## See also

- [Builder API Overview](/docs/builder-api/overview) -- full endpoint reference
- [Analytics endpoints](/docs/builder-api/analytics) -- usage and token-usage fields
- [Heartbeat](/docs/guides/heartbeat) -- proactive outreach setup
- [Variables and Secrets](/docs/custom-actions/variables) -- how encrypted application variables work
- [The Alchemist](/docs/guides/alchemist) -- your AI builder assistant