> ## Documentation Index
> Fetch the complete documentation index at: https://botsify.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Measure Botsify Bot Performance with Dashboard Analytics

> Retrieve dashboard statistics for your Botsify bots — including message counts and user engagement metrics — over any custom date range.

Understanding how your bot is performing is essential for improving conversation quality and demonstrating ROI. Botsify exposes a dashboard statistics endpoint that lets you pull message counts and user engagement metrics for any custom date range — making it easy to build reports, set up monitoring dashboards, or feed data into your analytics stack.

## The analytics endpoint

`POST /api/v1/bot-dashboard-stats` returns aggregated performance data for the bots associated with your API key. You control the reporting window by passing a `date_from` and `date_to` value in `YYYY-MM-DD` format.

```bash theme={null}
curl --request POST \
  --url https://app.botsify.com/api/v1/bot-dashboard-stats \
  --header 'Content-Type: application/json' \
  --data '{
    "apikey": "<YOUR_API_KEY>",
    "date_from": "2025-01-01",
    "date_to": "2025-01-31"
  }'
```

**Request body fields**

| Field | Type | Required | Description |
| - | - | - | - |
| `apikey` | string | ✅ | Your Botsify API key |
| `date_from` | string | ✅ | Start of the reporting window in `YYYY-MM-DD` format (inclusive) |
| `date_to` | string | ✅ | End of the reporting window in `YYYY-MM-DD` format (inclusive) |

***

## Understanding the parameters

**`date_from`** — The first day of your reporting period. All statistics are aggregated from the beginning of this calendar day (midnight UTC).

**`date_to`** — The last day of your reporting period. Statistics are aggregated through the end of this calendar day (23:59:59 UTC). Set `date_to` to today's date to include the most recent activity.

Both dates are **inclusive**, so a request with `date_from: "2025-01-01"` and `date_to: "2025-01-01"` returns data for exactly one day.

***

## Sample response shape

The endpoint returns a JSON object containing aggregated statistics for the specified date range. The response includes metrics such as:

```json theme={null}
{
  "date_from": "2025-01-01",
  "date_to": "2025-01-31",
  "stats": {
    "total_messages": 18420,
    "messages_sent": 9310,
    "messages_received": 9110,
    "total_users": 3250,
    "new_users": 870,
    "returning_users": 2380,
    "engaged_sessions": 4120,
    "avg_messages_per_session": 4.5
  }
}
```

The `stats` object describes activity across all bots tied to your API key for the given window:

* **`total_messages`** — combined inbound and outbound message volume
* **`messages_sent`** — messages delivered from the bot to users
* **`messages_received`** — messages sent by users to the bot
* **`total_users`** — unique users who interacted during the period
* **`new_users`** — users engaging for the first time
* **`returning_users`** — users with prior interaction history
* **`engaged_sessions`** — conversation sessions that progressed beyond the opening message
* **`avg_messages_per_session`** — average depth of a conversation

> [!NOTE]
>
> The exact fields returned may vary based on your Botsify plan and the channels connected to your bots. Always inspect the live response to confirm which metrics are available for your account.

***

## Building a rolling 30-day report

> [!TIP]
>
> To track performance on a continuous basis, compute `date_from` dynamically as today's date minus 30 days and `date_to` as today's date. Schedule this call daily (e.g. via a cron job) and store each response in your data warehouse to build a time-series view of your bot's growth. Here is a quick shell snippet to generate the correct date strings:
>
> ```bash theme={null}
> DATE_TO=$(date +%Y-%m-%d)
> DATE_FROM=$(date -d "30 days ago" +%Y-%m-%d)   # Linux
> # DATE_FROM=$(date -v-30d +%Y-%m-%d)            # macOS
>
> curl --request POST \
>   --url https://app.botsify.com/api/v1/bot-dashboard-stats \
>   --header 'Content-Type: application/json' \
>   --data "{
>     \"apikey\": \"<YOUR_API_KEY>\",
>     \"date_from\": \"$DATE_FROM\",
>     \"date_to\": \"$DATE_TO\"
>   }"
> ```

***

## Next steps

* **Correlate with deployments** — cross-reference stat drops or spikes with the version history from [Deploy an Agent](/guides/deploy-an-agent) to identify the impact of configuration changes.
* **Combine with WhatsApp data** — supplement bot-level stats with broadcast-specific metrics from the [WhatsApp Integration guide](/guides/whatsapp-integration).
* **Set up alerts** — if `new_users` drops sharply day-over-day, that may signal a channel connectivity issue worth investigating in your Botsify dashboard.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.