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

# Analytics API Endpoints for Conversation and Usage Data

> Retrieve account dashboard summaries, per-agent conversation analytics, and daily trend data programmatically using the BotSmith Analytics REST API.

The Analytics API gives you programmatic access to the same data shown on your BotSmith dashboard. Pull conversation counts, message totals, lead counts, and trend data into your own reporting tools or BI dashboards. All endpoints require authentication.

## Dashboard Summary

**`GET /api/analytics/dashboard`**

Returns an account-wide summary — totals across all your agents. This is the same snapshot shown at the top of the BotSmith dashboard.

```bash theme={null}
curl -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/analytics/dashboard
```

**Response (`200 OK`):**

```json theme={null}
{
  "total_conversations": 1250,
  "total_messages": 8430,
  "active_chatbots": 2,
  "total_chatbots": 3,
  "total_leads": 47
}
```

<ResponseField name="total_conversations" type="integer">
  Total number of conversations started across all your agents.
</ResponseField>

<ResponseField name="total_messages" type="integer">
  Total number of messages (user + assistant) exchanged across all your agents.
</ResponseField>

<ResponseField name="active_chatbots" type="integer">
  Number of agents currently set to `"active"` status.
</ResponseField>

<ResponseField name="total_chatbots" type="integer">
  Total number of agents in your account, regardless of status.
</ResponseField>

<ResponseField name="total_leads" type="integer">
  Total number of leads captured by your agents' widget lead forms.
</ResponseField>

***

## Per-Agent Analytics

**`GET /api/analytics/chatbot/{chatbot_id}`**

Returns conversation and message counts broken down by day for a specific agent. Use the `days` query parameter to control the time window.

```bash theme={null}
curl -H "Authorization: Bearer TOKEN" \
  "https://app.botsmith.ai/api/analytics/chatbot/CHATBOT_ID?days=30"
```

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent to retrieve analytics for.
</ParamField>

**Query parameters:**

<ParamField query="days" type="integer">
  Number of days to look back from today. Defaults to `30`. Accepted range: `1`–`365`.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "total_conversations": 87,
  "total_messages": 624,
  "date_range": ["2024-05-02", "2024-05-03", "2024-05-04"],
  "conversations_by_date": {
    "2024-05-02": 3,
    "2024-05-03": 5,
    "2024-05-04": 2
  },
  "messages_by_date": {
    "2024-05-02": 21,
    "2024-05-03": 38,
    "2024-05-04": 14
  }
}
```

<ResponseField name="total_conversations" type="integer">
  Total conversations in the requested date range.
</ResponseField>

<ResponseField name="total_messages" type="integer">
  Total messages (user + assistant) in the requested date range.
</ResponseField>

<ResponseField name="date_range" type="array">
  Ordered array of ISO 8601 date strings (`YYYY-MM-DD`) covering the requested window.
</ResponseField>

<ResponseField name="conversations_by_date" type="object">
  Map of `date → conversation count` for each day in the range. Days with no activity are included with a count of `0`.
</ResponseField>

<ResponseField name="messages_by_date" type="object">
  Map of `date → message count` for each day in the range. Days with no activity are included with a count of `0`.
</ResponseField>

***

## Account-Level Trends

**`GET /api/analytics/trends`**

Returns aggregated daily conversation and message counts across **all** your agents for the requested period. Also includes the average AI response time. Use this endpoint to power time-series charts in your own dashboards.

```bash theme={null}
curl -H "Authorization: Bearer TOKEN" \
  "https://app.botsmith.ai/api/analytics/trends?days=14"
```

**Query parameters:**

<ParamField query="days" type="integer">
  Number of days to look back from today. Defaults to `30`. Accepted range: `1`–`365`.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "conversations": [
    { "date": "May 19", "count": 12 },
    { "date": "May 20", "count": 18 },
    { "date": "May 21", "count": 9 }
  ],
  "messages": [
    { "date": "May 19", "count": 88 },
    { "date": "May 20", "count": 135 },
    { "date": "May 21", "count": 61 }
  ],
  "avg_response_time": "1s"
}
```

<ResponseField name="conversations" type="array">
  Array of objects, one per day, each with a `date` label (formatted `"Mon DD"`) and a `count` of new conversations.
</ResponseField>

<ResponseField name="messages" type="array">
  Array of objects, one per day, each with a `date` label and a `count` of total messages across all agents.
</ResponseField>

<ResponseField name="avg_response_time" type="string">
  Average time between a user message and the agent's reply for the period. Formatted as a human-readable string: `"450ms"`, `"1s"`, `"2m 15s"`, etc. Returns `"0s"` if there are no conversations in the period.
</ResponseField>

<Note>
  If you have no agents yet, the trends endpoint returns empty arrays for `conversations` and `messages` and an `avg_response_time` of `"0s"`.
</Note>