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

# Get agent analytics

> Fetch the full analytics summary for one agent.

Returns analytics for one agent over a requested time window. The response includes summary metrics, comparison metrics, chart datasets, knowledge usage, rule analytics, escalation reasons, hourly volume, and CSAT data when available.

Use this route when you need the complete analytics payload. If you only need one part of the payload, use [Get agent analytics section](/en/api-reference/get-agent-analytics-section). For the analytics endpoint family, see [Analytics](/en/api-reference/analytics).

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `read` scope.
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>
  Agent ID whose analytics you want to read. Use [List agents](/en/api-reference/list-agents) to get the `botId`.
</ParamField>

## Query parameters

<ParamField query="startEpoch" type="number" required>
  Start of the analytics window as a Unix epoch timestamp.
</ParamField>

<ParamField query="endEpoch" type="number" required>
  End of the analytics window as a Unix epoch timestamp.
</ParamField>

<ParamField query="source" type="string | string[]">
  Conversation source filter. Pass `all` to include all supported sources, or pass one or more source values accepted by Fini.
</ParamField>

<ParamField query="channel" type="string | string[]">
  Optional channel filter.
</ParamField>

<ParamField query="latestStatus" type="string | string[]">
  Optional latest-status filter.
</ParamField>

<ParamField query="latestSentiment" type="string | string[]">
  Optional latest-sentiment filter.
</ParamField>

<ParamField query="usedSubfolderIds" type="string | string[]">
  Optional knowledge subfolder IDs to filter by.
</ParamField>

<ParamField query="tagIds" type="string | string[]">
  Optional tag IDs to filter by.
</ParamField>

<ParamField query="ruleIds" type="string | string[]">
  Optional rule IDs to filter by.
</ParamField>

<ParamField query="escalationReasonTagIds" type="string | string[]">
  Optional escalation-reason tag IDs to filter by.
</ParamField>

<ParamField query="csatRatings" type="number | number[]">
  Optional CSAT ratings to filter by. Values must be integers from `1` through `5`.
</ParamField>

<ParamField query="timezone" type="string">
  Optional timezone used for date grouping.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-analytics/public?startEpoch=1784073600000&endEpoch=1784678400000&source=all' \
    --header 'Authorization: Bearer fini_your_api_key'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-analytics/public",
      headers={"Authorization": "Bearer fini_your_api_key"},
      params={
          "startEpoch": 1784073600000,
          "endEpoch": 1784678400000,
          "source": "all",
      },
  )
  analytics = response.json()
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    startEpoch: "1784073600000",
    endEpoch: "1784678400000",
    source: "all",
  });

  const response = await fetch(
    `https://api-prod.usefini.com/v2/bots/4f5ef695-d03b-4d56-8fef-7f2bd5c17ef3/hc-analytics/public?${params.toString()}`,
    {
      headers: {
        Authorization: "Bearer fini_your_api_key",
      },
    }
  );
  const analytics = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "botId": "2a1cf0f0-f35d-46ad-8e61-a15c86b2b312",
    "range": {
      "from": "2026-07-01T00:00:00.000Z",
      "to": "2026-07-28T00:00:00.000Z"
    },
    "overview": {
      "totalConversations": 1240,
      "escalationRate": 0.18,
      "resolutionRate": 0.74
    },
    "sections": [
      {
        "id": "escalations",
        "title": "Escalations",
        "value": 223,
        "trend": "down"
      }
    ]
  }
  ```
</ResponseExample>

## Response

Returns an `AgentAnalyticsSummary` object.

<ResponseField name="summary" type="AnalyticsMetrics">
  Current-window totals and rates.
</ResponseField>

<ResponseField name="comparisonSummary" type="AnalyticsMetrics">
  Comparison-window totals and rates.
</ResponseField>

<ResponseField name="summaryCards" type="object">
  Metric-card values for conversation volume, AI resolution rate, human escalation rate, average response time, and average CSAT rating.
</ResponseField>

<ResponseField name="statusBreakdown" type="array">
  Conversation counts grouped by status.
</ResponseField>

<ResponseField name="usageByChannel" type="array">
  Conversation counts and resolved counts grouped by channel.
</ResponseField>

<ResponseField name="conversationVolumeChartData" type="array">
  Daily resolved, escalated, and waiting-for-customer counts.
</ResponseField>

<ResponseField name="resolutionRateChartData" type="array">
  Daily total conversations, resolved conversations, and AI resolution rate.
</ResponseField>

<ResponseField name="responseTimeChartData" type="array">
  Daily average first-response time in milliseconds.
</ResponseField>

<ResponseField name="knowledgeUsage" type="object">
  Current and comparison knowledge-folder usage arrays.
</ResponseField>

<ResponseField name="ruleAnalytics" type="array">
  Rule-level conversation, resolution, escalation, and CSAT metrics.
</ResponseField>

<ResponseField name="escalationReasons" type="array">
  Escalation-reason tag counts.
</ResponseField>

<ResponseField name="hourlyVolume" type="array">
  Volume by day of week and hour.
</ResponseField>

<ResponseField name="csatChartData" type="array">
  Optional daily CSAT percentage chart data.
</ResponseField>

## AnalyticsMetrics object

<ResponseField name="totalConversations" type="number">
  Total conversations in the window.
</ResponseField>

<ResponseField name="resolvedConversations" type="number">
  Conversations resolved by AI.
</ResponseField>

<ResponseField name="escalatedConversations" type="number">
  Conversations escalated to a human.
</ResponseField>

<ResponseField name="waitingForCustomerConversations" type="number">
  Conversations waiting for the customer.
</ResponseField>

<ResponseField name="aiResolutionRate" type="number">
  AI resolution rate for the window.
</ResponseField>

<ResponseField name="humanEscalationRate" type="number">
  Human escalation rate for the window.
</ResponseField>

<ResponseField name="averageResponseTimeMs" type="number">
  Average response time in milliseconds.
</ResponseField>

<ResponseField name="averageCsatRating" type="number">
  Average CSAT rating.
</ResponseField>

## Errors

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    The path ID or query parameters are invalid. `startEpoch` and `endEpoch` are required.
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    The API key is missing, malformed, revoked, or invalid.
  </Accordion>

  <Accordion title="403 Forbidden" icon="shield-halved">
    The API key does not include the `read` scope required for this route.
  </Accordion>

  <Accordion title="406 Not Acceptable" icon="circle-question">
    The agent belongs to a different workspace.
  </Accordion>

  <Accordion title="500 Internal Server Error" icon="triangle-exclamation">
    Fini failed while loading analytics.
  </Accordion>
</AccordionGroup>