Skip to main content

How to Create an Analytics Export Template

An analytics export template defines a usage report for a tenant. Each run of a template (a job) produces an Excel workbook describing how the tenant is being used — the users in scope, the queries they run, the search results they engage with, the tags they create, and chat conversations. A job can be triggered on demand or on a recurring schedule, and the resulting file is emailed to a mailing list and stored in the tenant's report storage.

A tenant can have many templates (for example, a weekly report for one team and a monthly report for another). This guide walks you through creating one and explains what each tab of the generated workbook contains.

Prerequisites​

  • Admin access to the Zeta Alpha Platform UI, with permission to manage analytics for the tenant.
  • An existing tenant (see Creating a new tenant).
  • Tenant analytics export settings — see Tenant analytics export settings. Templates cannot be saved until report storage is configured there.

Tenant analytics export settings​

Data sources and report storage are configured once per tenant and shared by all of that tenant's templates — you do not enter them on a template. They are read from the tenant each time a job runs, so changing them applies to every future run. Set them in the tenant's edit view, under Analytics Export:

  • Report storage (required) — the object storage (S3 or Azure) reports are written to. Reports are keyed analytics-reports/<tenant>/<template>/<job>.xlsx under the storage base URL.
  • Tracing Configuration — the tenant's agent tracing configuration whose traces feed the Chats, User-Agent Interaction and Agent Calls tabs. Select None to leave them unavailable.

While a tenant has no analytics export settings, the Analytics page shows a warning with a link to the tenant's Features page, and templates cannot be saved for it.

Creating a Template​

  1. Navigate to the Analytics tab.
  2. Select the tenant you want to report on using the tenant selector.
  3. Click Create Export Template. The selected tenant is carried over and pre-selected on the form.

The form is organized into a series of cards.

Basic Information​

  • Tenant: The tenant the report covers. Pre-filled from your selection on the Analytics page.
  • Name: A descriptive name for the template, e.g. Weekly usage — Research team.

User Filtering​

Control which users appear in the report.

  • Excluded Users: Email addresses to leave out (one per line), e.g. internal or test accounts.
  • Included Users: If provided, only these users appear in the report (one per line). Leave empty to include everyone except the excluded users.
  • Invited Users: Users who have not yet logged in but should still appear, one per line in the format email,first_name,last_name.

Recipients​

  • Mailing List: Email addresses that receive the generated report, one per line. Recipients still need admin access, or manager access for the tenant, to open the report — see Running and Downloading Reports.

Date Range​

Choose the period the report covers.

  • Relative: A rolling window of the last N days (Number of Days). Quick presets for 7, 14, and 30 days are available. Use this for recurring reports.
  • Absolute: A fixed From Date and To Date.

Report Tabs​

Select which tabs to include in the workbook. Each tab corresponds to a sheet in the Excel file (see What the Excel Report Contains).

Queries, Search Results, Chats and Tags contain confidential user information

Queries, Search Results, Chats and Tags are off by default on a new template.

  • Enabling Queries includes information about the users' search queries and generated answers, which may contain confidential information.
  • Enabling Search Results includes information about the users' search queries and the documents returned for them, which may contain confidential information.
  • Enabling Chats includes all users' conversation transcripts, which may contain confidential information.
  • Enabling Tags includes all users' tag names, which may contain confidential information.

The workbook is emailed to the mailing list and stored in the tenant's report storage, so every recipient can read all of it.

note

The Chats, User-Agent Interaction and Agent Calls tabs are only offered when the tenant's analytics export settings select an agent tracing configuration.

Schedule​

Use the Schedule card to run the report automatically on a recurring basis.

  • Common Schedule: Pick a ready-made schedule — Every Monday at 9:00 am, First Monday of every month at 12:00 pm, First day of the month at 1:00 am, or Custom. Selecting a preset fills in the Cron Expression for you.
  • Cron Expression: A standard cron expression controlling when the report runs, e.g. 0 9 * * 1 for every Monday at 9am.
  • Timezone: The timezone the cron expression is evaluated in. Your local timezone is pre-selected.
  • Active: Whether the template runs on its schedule.
note

An active template must have a schedule. For a manual-only report — one you run yourself with Trigger Export — leave the schedule empty and turn Active off. Turning Active off also pauses a scheduled template without deleting it.

When you are done, click Create Export Template to save.

Running and Downloading Reports​

Saved templates are listed on the Analytics page for the selected tenant. From a template's actions you can:

  • Trigger Export to start a job immediately, regardless of any schedule.
  • View the Job History for the template, including each job's status, who requested it, and its start/finish times.
  • Download the generated workbook for a completed job.

Scheduled templates also run automatically according to their cron expression and timezone, and email the result to the mailing list. If a job fails, the mailing list is notified so it can be re-run with Trigger Export.

note

Downloading a report requires admin access, or manager access for the report's tenant. Users without one of those roles can still receive the notification email but cannot open the report.

What the Excel Report Contains​

The generated workbook contains one sheet per enabled tab. User Members is always present; the remaining sheets appear only when their tab is enabled (and, for Chats, User-Agent Interaction and Agent Calls, when the tenant has agent tracing enabled).

User Members​

Always included. One row per user in scope, with summary metrics for the reporting period. The metrics are counts only, with no query text, transcripts or tag names, so they are reported whichever tabs are enabled:

  • email, first_name, last_name — user identity.
  • Logged In (count) — number of logins.
  • Queries — number of search queries the user ran.
  • Engagement Rate — share of the user's queries that led to an engagement with a result.
  • Chats — number of chat conversations the user had (only when the tenant has agent tracing enabled).
  • User Turns — number of messages the user sent to agents (only when the tenant has agent tracing enabled).
  • Total Tokens — LLM tokens used to answer the user, across all agents (only when the tenant has agent tracing enabled).
  • Tags — number of tags the user created.

Invited users who have not yet logged in appear here as well, with empty metrics. A blank Chats, User Turns or Total Tokens cell means that data could not be fetched for the run; the job's warnings say which.

User-Agent Interaction​

Enabled by default on a new template. One row per user and agent they used during the reporting period. Like User Members, it holds counts only:

  • user_uuid — the user, matching the user_uuid column of User Members.
  • agent_identifier — the agent the user chatted with.
  • conversations — number of conversations with the agent.
  • user_turns — number of messages the user sent.
  • llm_calls — number of LLM calls made to answer them.
  • sub_agent_calls — number of sub-agents that ran.
  • tool_calls — number of tool calls.
  • input_tokens, output_tokens, total_tokens — LLM tokens used.

LLM calls, tool calls and tokens of sub-agents count towards the agent the user chatted with.

Agent Calls​

Enabled by default on a new template. One row per agent, showing how often it is used and how. An agent can run as the main agent (the one a user chats with) or as a sub-agent called by another agent.

  • agent_identifier — the agent.
  • role — main, sub-agent or both.
  • conversations, unique_users — conversations with the agent as main agent, and the users who had them.
  • user_adoption — share of the users in the report who used the agent.
  • returning_users — users who used the agent on two or more days.
  • active_days, first_used, last_used — when the agent was used in the period.
  • user_turns, avg_turns_per_conversation — messages users sent the agent.
  • avg_response_seconds — mean time the agent took to answer a message.
  • turns_with_errors — messages where a step of the answer logged an error.
  • sub_agent_runs, called_by — runs as a sub-agent, and which agents called it.
  • llm_calls, avg_llm_calls_per_run — LLM calls the agent made, in total and per run (a message answered as main agent or a run as sub-agent).
  • tool_calls, top_tools — tool calls the agent made, and its three most used tools.
  • input_tokens, output_tokens, total_tokens, avg_tokens_per_run — LLM tokens the agent used.

LLM calls, tool calls and tokens count towards the agent that made them, so a sub-agent's usage appears on its own row. In User-Agent Interaction the same usage counts towards the main agent, so per-agent totals differ between the two sheets while the overall totals match.

Building User-Agent Interaction or Agent Calls reads every step the tenant's agents traced in the period, so reports that include them take longer for tenants with heavy agent use.

Queries​

One row per search query. Columns describe the query and the generated answer, including the query text, timestamp, the bot answer and number of cited references, whether the answer included references, any answer feedback score, and the number of results the user engaged with.

Chats​

One row per chat conversation (only when agent tracing is enabled). Columns include the user, the conversation start time, the agent used, the user's first message, and the full conversation transcript.

Tags​

One row per tag activity record, linking users to the tags they created during the reporting period.

Search results​

One row per result returned for the queries in the Queries tab. Columns include the originating query, the document (id, title, expanded abstract), whether the user clicked the title, and any relevance feedback recorded for the result.

note

Columns vary slightly depending on the data available for the tenant and period — for example, feedback-related columns only appear when feedback exists.