Skip to content
Chatvia Docs
On this page

API reference

Analytics and audit log

Get in touch: Ahmad Mayahi, creator of Chatvia, Spectra and Shakomako

These endpoints read an agent's usage numbers and the record of every tool call. They only read. Nothing here changes data.

For example, a marketing lead can pull each agent's weekly conversation count and visitor mood into the company's reporting tool. A security team can copy every tool call into its own log store.

The analytics endpoints return the same numbers as the agent's Analytics pages in the dashboard. Analytics explains what they mean.

Read the overview first for the base URL, keys, errors and paging.

Date range

The overview, sentiment, tone and topics endpoints take an optional range:

Query parameter Type Default Notes
start_date string 6 days ago The first day, as 2026-10-01.
end_date string today The last day. Can't be before start_date.

Without them you get the last 7 days, today included.

Overview

Headline numbers, a series per day, activity patterns, visitor countries and the most used files.

text
GET /api/v1/agents/{agent}/analytics/overview

Who can call it: the owner, or a teammate with Chat analytics.

bash
curl "https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/analytics/overview?start_date=2026-10-19&end_date=2026-10-25" \
  -H "Authorization: Bearer $CHATVIA_API_KEY"
json
{
  "data": {
    "total_messages": 1840,
    "total_conversations": 512,
    "total_user_messages": 1902,
    "unique_sessions": 430,
    "avg_response_time": 2.4,
    "avg_first_response_time": 2.1,
    "avg_messages_per_conversation": 7.3,
    "avg_conversation_duration": 214,
    "avg_tokens_per_message": 1650,
    "total_tokens_used": 3036000,
    "peak_activity_hour": 14,
    "conversations_with_feedback": 61,
    "feedback": { "positive": 52, "negative": 9, "total": 61 },
    "messages_last_week": [
      { "day": "Sun", "date": "2026-10-25", "value": 48 }
    ],
    "country_usage": [
      { "country_code": "DE", "country_name": "Germany", "count": 210, "percentage": 41.0 }
    ],
    "daily_messages": [
      { "date": "2026-10-25", "messages": 48 }
    ],
    "conversations_trend": [
      { "date": "2026-10-25", "conversations": 14 }
    ],
    "activity_by_hour": [
      { "hour": 14, "count": 160 }
    ],
    "activity_by_day_of_week": [
      { "day": "Monday", "day_number": 1, "count": 300 }
    ],
    "top_knowledge": [
      { "name": "returns-policy.pdf", "type": "unknown", "accessed": 320 }
    ],
    "first_data_date": "2026-08-03",
    "last_updated": "2026-10-25T15:00:00+00:00"
  }
}

The arrays above are cut to one entry each. Some numbers cover all time and some follow the date range:

Field Range Meaning
total_messages all time Replies the agent sent.
total_conversations all time Conversations.
total_user_messages all time Messages visitors sent.
unique_sessions all time Different visitor sessions.
avg_response_time all time Seconds per reply.
avg_first_response_time all time Seconds until the first reply of a conversation.
avg_messages_per_conversation all time Messages per conversation.
avg_conversation_duration all time Seconds a conversation lasts.
avg_tokens_per_message, total_tokens_used all time Tokens per reply and in total.
peak_activity_hour all time The busiest hour of the day, 0 to 23.
feedback, conversations_with_feedback all time Thumbs up and down from visitors.
messages_last_week, daily_messages date range Replies per day. messages_last_week has every day of the range, with 0 for quiet days.
conversations_trend date range New conversations per day.
activity_by_hour, activity_by_day_of_week all time How many conversations started in each hour (0 to 23) and on each weekday (day_number 0 is Sunday). Every hour and day is listed, with 0 for quiet ones.
country_usage all time Conversations per visitor country, with their share in percent.
top_knowledge all time The files the agent used most, and how often. type is the kind of document Chatvia detected, or unknown.
first_data_date The first day with data.
last_updated When these numbers were made.

Sentiment

The mood of visitor messages per day: positive, neutral or negative.

text
GET /api/v1/agents/{agent}/analytics/sentiment

Who can call it: the owner, or a teammate with Sentiment.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/analytics/sentiment \
  -H "Authorization: Bearer $CHATVIA_API_KEY"
json
{
  "data": {
    "by_date": [
      { "date": "2026-10-25", "positive": 20, "neutral": 31, "negative": 4, "unspecified": 2 }
    ],
    "totals": { "positive": 140, "neutral": 210, "negative": 30, "unspecified": 12, "total": 392 }
  }
}

unspecified counts messages that were never analyzed. totals.total is every visitor message in the range.

Tone

The tone of visitor messages per day: neutral, frustrated, urgent, confused or satisfied.

text
GET /api/v1/agents/{agent}/analytics/tone

Who can call it: the owner, or a teammate with Tones.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/analytics/tone \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer has the same by_date and totals shape as sentiment, with the tone values as keys.

Topics

How many conversations each topic had per day, plus the totals.

text
GET /api/v1/agents/{agent}/analytics/topics

Who can call it: the owner, or a teammate with Topics.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/analytics/topics \
  -H "Authorization: Bearer $CHATVIA_API_KEY"
json
{
  "data": {
    "topics_by_date": [
      {
        "topic_name": "Billing & Payments",
        "counts": [
          { "date": "2026-10-24", "count": 6 },
          { "date": "2026-10-25", "count": 9 }
        ]
      }
    ],
    "total_topics": [
      { "id": 12, "name": "Billing & Payments", "count": 41 }
    ],
    "total_count": 97
  }
}

The id in total_topics is a number, not the topic id that the Topics endpoints use. Match topics by name instead.

Source usage

The sources, functions and MCP tools the agent used most, all time, with the last day each was used. The date range does not apply here.

text
GET /api/v1/agents/{agent}/analytics/sources

Who can call it: the owner, or a teammate with Sources.

bash
curl https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/analytics/sources \
  -H "Authorization: Bearer $CHATVIA_API_KEY"
json
{
  "data": {
    "knowledge": [
      { "name": "returns-policy.pdf", "kind": "source_file", "mime_type": "application/pdf", "retrievals": 320, "last_used_on": "2026-10-25" }
    ],
    "functions": [
      { "name": "lookup_order", "description": "Retrieve order details for a given order ID.", "calls": 88, "last_used_on": "2026-10-24" }
    ],
    "mcp_tools": [
      {
        "tool_name": "search_issues",
        "tool_description": "Search issues in a repository.",
        "server_name": "GitHub",
        "server_slug": "github",
        "connector_slug": "github",
        "calls": 15,
        "last_used_on": "2026-10-22"
      }
    ]
  }
}

Names are saved when a source or tool is used, so a deleted source still shows its real name. kind is the kind of source, such as source_file, source_website or source_text.

The audit entry object

The audit log has one row for every tool call an agent made, and what Chatvia decided about it. A row never changes after it is written. A trace groups the rows of one reply.

json
{
  "trace_id": "0199f450-2c3d-7e4f-8a5b-6c7d8e9f0a1b",
  "tool_call_id": "call_8Kq2",
  "agent_id": "a3f9c2e17b4d08",
  "agent_name": "Help Desk",
  "user_name": "Jane Doe",
  "tool_name": "lookup_order",
  "tool_kind": "function",
  "connector_slug": null,
  "connector_name": null,
  "outcome": "auto",
  "gated": false,
  "is_error": false,
  "latency_ms": 312,
  "arguments": { "order_id": "ORD-12345" },
  "arguments_preview": null,
  "arguments_truncated": false,
  "result_text": "{\"status\":\"shipped\"}",
  "conversation_id": "0199f3f1-0a1b-7c2d-8e3f-4a5b6c7d8e9f",
  "decided_at": null,
  "decision_note": null,
  "created_at": "2026-10-25T10:31:08+00:00"
}
Field Meaning
trace_id Groups every row of one reply.
tool_call_id The AI model's id for this call within the reply.
agent_id, agent_name The agent. agent_id is null once the agent is deleted, but the name stays.
user_name The signed-in chatter, or null for an anonymous visitor.
tool_name, tool_kind The tool, and whether it is an mcp tool or a function.
connector_slug, connector_name The catalog connector the tool belongs to, if any.
outcome auto (ran without approval), approved, denied, rate_limited or not_offered.
gated Whether the call needed a person's approval.
is_error Whether the call failed.
latency_ms How long the call took.
arguments What the model sent, as JSON. null when it was too large or not JSON.
arguments_preview, arguments_truncated The start of the arguments as text when they were too large or not JSON.
result_text What the tool answered. It may be cut.
conversation_id The conversation the call happened in.
decided_at, decision_note When the call was approved or denied, and the note left with it.
created_at When the call was recorded.

Both audit endpoints take these query parameters:

Query parameter Type Notes
outcome string Only rows with this outcome.
connector string Only rows of this catalog connector, by its slug, such as github.
per_page, cursor See Pagination.

An agent's audit log

Every tool call of one agent, newest first.

text
GET /api/v1/agents/{agent}/audit

Who can call it: the owner, or a teammate with View audit log.

bash
curl "https://chat.example.com/api/v1/agents/a3f9c2e17b4d08/audit?outcome=denied" \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [entry, …], "next_cursor": … }.

The workspace audit log

Every tool call of every agent in your workspace, newest first. It is the same log as Governance in the dashboard's workspace settings.

text
GET /api/v1/audit

Who can call it: the owner, or a teammate with Governance.

bash
curl "https://chat.example.com/api/v1/audit?connector=github" \
  -H "Authorization: Bearer $CHATVIA_API_KEY"

The answer is { "data": [entry, …], "next_cursor": … }.

Search guides, settings and commands.