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

# Analytics

> Account analytics, trends, genie performance, and period comparisons

Use the `analytics` resource to fetch overview metrics, conversation trends, genie performance breakdowns, and period-over-period comparisons.

Supported actions: `all`, `overview`, `trends`, `genie-performance`, `compare`.

***

## Overview

Returns account-level aggregate counts for genies, conversations, leads, and knowledge base documents. `all` and `overview` are equivalent.

<ParamField body="resource" type="string" required>
  Must be `"analytics"`.
</ParamField>

<ParamField body="action" type="string" required>
  `"all"` or `"overview"`.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean">
      Admin only. View analytics across all users.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Scope analytics to a specific user.
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="stats" type="object">
      <Expandable title="properties">
        <ResponseField name="genies" type="number">
          Total number of genies.
        </ResponseField>

        <ResponseField name="conversations" type="number">
          Total number of conversations.
        </ResponseField>

        <ResponseField name="leads" type="number">
          Total number of leads.
        </ResponseField>

        <ResponseField name="knowledgeBaseDocuments" type="number">
          Total number of knowledge base documents.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```json Request body theme={null}
  {
    "resource": "analytics",
    "action": "overview"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "stats": {
        "genies": 4,
        "conversations": 312,
        "leads": 58,
        "knowledgeBaseDocuments": 19
      }
    }
  }
  ```
</CodeGroup>

***

## Trends

Returns daily conversation trend data points over a time period.

<ParamField body="resource" type="string" required>
  Must be `"analytics"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"trends"`.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="period" type="string">
      Time period. One of `"7d"`, `"30d"`, `"90d"`. Default: `"30d"`.
    </ParamField>

    <ParamField body="adminMode" type="boolean">
      Admin only.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/analytics \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "trends", "data": { "period": "30d" } }'
  ```
</CodeGroup>

***

## Genie performance

Returns conversation volume grouped by genie, filtered by time period. Supports custom date ranges.

<ParamField body="resource" type="string" required>
  Must be `"analytics"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"genie-performance"`.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="period" type="string">
      Time period. One of `"7d"`, `"30d"`, `"90d"`. Default: `"30d"`.
    </ParamField>

    <ParamField body="from" type="string">
      ISO 8601 start timestamp for custom date range.
    </ParamField>

    <ParamField body="to" type="string">
      ISO 8601 end timestamp for custom date range.
    </ParamField>

    <ParamField body="adminMode" type="boolean">
      Admin only.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/analytics \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "genie-performance",
      "data": { "period": "30d" }
    }'
  ```
</CodeGroup>

***

## Compare

Returns a period-over-period conversation comparison (e.g., this week vs last week).

<ParamField body="resource" type="string" required>
  Must be `"analytics"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"compare"`.
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="period" type="string">
      Time period. One of `"7d"`, `"30d"`, `"90d"`. Default: `"30d"`.
    </ParamField>

    <ParamField body="adminMode" type="boolean">
      Admin only.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only.
    </ParamField>
  </Expandable>
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.helpgenie.ai/v1/analytics \
    -H "Authorization: Bearer hg_live_YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "action": "compare", "data": { "period": "7d" } }'
  ```
</CodeGroup>