Usage analytics project

The Lightdash analytics project brings your organization’s usage data into Lightdash. Start with the built-in dashboards, explore the underlying metrics, or save your own charts. You do not need to connect a warehouse or maintain a dbt project for it. This project is separate from the project-level User Activity dashboard. It covers captured activity across your organization, rather than one project’s fixed report. Use this page to create the project, grant access, update its content, choose a dashboard, build your own analysis, or import retained history.

​

Create your analytics project

1. Sign in with organization administration permissions.
2. Open Settings → Lightdash analytics.
3. Click Create. Lightdash creates the project and installs its built-in models, charts and dashboards.
4. Open a dashboard from the settings page, or click Explore to browse the available tables.

Organization administrators have access automatically. Other users need an explicit analytics permission, even if they have access to other projects. Creating the project starts a background historical backfill of supported records still held in the Lightdash database. You can use the project while it runs. Events without a retained database equivalent still require normal capture and processing.

​

Grant access

The View managed analytics for the entire organization permission (view:SystemAnalytics) lets selected users, groups and service accounts read the analytics project without organization administration access. It is separate from View usage analytics (view:Analytics), which controls the older project-level usage reports. Organization Admin includes this permission. Built-in Project Admin and other non-admin system roles do not; duplicating a Project Admin role does not add it either.

​

Configure a custom role

An organization administrator can grant access using custom roles, which require an Enterprise plan:

1. Create a Project custom role and select View managed analytics for the entire organization. Keep its View project (view:Project) dependency selected.
2. Assign the role to the selected users, group or service account on the Lightdash analytics project.
3. Keep the ordinary permissions required for their work. Viewer access allows reading shared saved content; Interactive Viewer access or equivalent custom permissions is needed to build Explore queries. The analytics permission does not replace content, space or query permissions.
4. Have the recipient select Lightdash analytics in the project selector and open a dashboard. To verify query access, open a chart’s Explore from here action and run a query.

The permission can also be included in an Organization custom role. A project-level assignment makes the intended access explicit. Follow custom-role assignment for users and groups, or project-scoped service accounts for automation. Creating, syncing, backfilling and deleting the managed project through analytics settings still require organization administration permissions. The read permission does not grant those operations or access to SQL Runner, which is unavailable for managed analytics projects.

​

Agents and MCP

An agent uses the permissions of the user or service account it authenticates with. Grant access to that identity; granting it only to the service account’s creator is not enough. The usual project, content, Explore and MCP permissions still apply. Use the managed Explores for metric queries. Test with the agent’s actual credentials, including any required connection or token permissions.

​

Remove access

Permissions are additive. Remove every applicable analytics grant, including direct, group and organization-level grants, to revoke access. An organization administrator retains access through their admin role. After the normal permission/session refresh, revocation blocks project discovery, new queries, query history and cached results. It does not retract data already downloaded by a recipient.

​

Update models and dashboards

When Sync content is available in Settings → Lightdash analytics, click it to install the built-in content supplied by your instance’s release. Sync updates the models and built-in charts and dashboards in the existing project. You do not need to delete or recreate the project. Duplicate a built-in dashboard before customizing it. Sync replaces edits to built-in content; custom dashboards and separate copies are kept. Sync updates content definitions. It does not collect events, run the nightly data refresh, or add data from before capture was enabled.

​

Built-in dashboards

Each dashboard groups related questions into tabs. The collection available to you depends on your deployed release and the content installed in your analytics project. Chart descriptions explain the measure and its limits. Open a chart’s Explore from here action to inspect its fields and filters before adapting it.

​

Build your own analysis

Choose the Explore that matches what you want to count. An event, an app load, a person and an AI model call are different measures.

​

Who uses which dashboards and apps?

Start with Adoption → People & content for dashboard audiences and Adoption → Data apps for app usage. For a custom dashboard-usage table, open Content reach. Select User name, Content name, Event ts → Day and Qualifying views, and filter Content type to dashboard. For app usage, open Data app reach. Select User name, App name, Event ts → Day, Total loads and Distinct viewers. Use View context to distinguish standalone apps, dashboards, charts and builder previews. To follow the Adoption dashboard’s app-usage scope, select standalone, dashboard and chart. These are separate Explores. Put their charts on the same dashboard to review them together; there is no combined dashboard-and-app viewer table in this collection. User activity can compare event categories by person and date, but does not supply the same per-content detail.

​

How is Ask AI usage changing?

Start with Adoption → Ask AI, including Ask AI questions each day and People asking AI each week. To build the trend yourself, open Agent requests:

1. Filter Surface to web_app for Ask AI in the Lightdash web app.
2. Select Requested at → Day or Week.
3. Add Total requests and Distinct requesters.
4. Add Agent name or User name to compare agents or people.

Total requests includes captured follow-up prompts and requests that are pending or failed. Use request status to narrow the analysis. Other surfaces, such as Slack, are outside the web_app filter. Use AI usage for model calls and token consumption. Its ai.usage event represents a model call, not a question: one question can make several calls, and other AI features also make calls. Filter by Feature when comparing consumption. Tokens are not monetary cost or a complete measure of spending in external assistants.

​

Data freshness and history

Usage data is collected after capture is enabled for your organization. The scheduled refresh processes closed UTC days at 00:30 UTC and updates the snapshots used for names and content inventory. Allow that job to finish before expecting the previous day’s data; these dashboards are not real-time monitors. Captured history depends on when each event stream started and how long its files are retained. Historical backfill can recover supported database records from before capture began. It cannot reconstruct activity that was never stored. Names and inventory metadata can reflect the latest snapshot rather than the value at the event’s time. Keep these distinctions in mind when reading a chart:

• Views and loads are observed activity. Dashboard/chart views count qualifying backend fetches; app loads include reloads. They do not prove a person read the content or that an app rendered successfully.
• Distinct users are not additive. A person can appear on several days or use several items. Recalculate the distinct count for the whole period instead of adding daily or per-item counts.
• No observed use is not proof of safe deletion. Check the capture window and content dependencies before removing an item.
• Missing values are unknown. Historical errors, timings or identities may not have been captured; a blank value is not necessarily zero.

​

Historical backfill

Backfill imports supported history that is still stored in your organization’s Lightdash database into the analytics project. It can recover records from before event capture was enabled; it is not a replay of every past action or an import from your warehouse’s query logs. The Historical activity section in Settings → Lightdash analytics is available on releases that support backfill. Creating a project starts the import automatically. For an existing project, an organization administrator can click Backfill available history there. Projects that have already been collecting events for weeks or months can use the same action until a backfill succeeds. The import runs in the background. You can leave the page and continue using Analytics. Imported datasets become queryable as they are published; no additional compaction run or overnight wait is required for those rows. Refresh an open chart or dashboard to load imported results. Names may remain unavailable until the normal metadata refresh finishes. The action is disabled while backfill is running and disappears after a successful import, including when there are no eligible records. If the import fails, use Backfill available history again. If the status check fails, use Retry check first. A retry keeps completed work and does not duplicate imported records. Sync content does not start a backfill.

​

What is included

All retained dates are eligible, including eligible records from today before each source is read. How far back you can go depends on database retention and when that kind of record began to be stored. Query and AI records join their existing datasets. If the same identity already has a captured event, the captured event takes precedence, including when it arrives after backfill. Existing data does not make the whole day ineligible: missing records can still be imported without overlapping identities being counted twice. Historical activity uses different counting rules from captured events. Filter by Activity type and treat its rows as retained facts, not a complete event timeline. They are not added to the native view, request, tool or export totals. Do not add prompt or research snapshot token totals to AI usage model-call totals; they can describe the same underlying consumption.

​

What is not included

• Activity never stored in a supported database record, or database records that have been removed or expired. Backfill cannot guarantee a fixed number of months of history.
• Preview-project queries and unfinished queries.
• Compiled SQL, conversation or reasoning text, tool arguments/results, uploaded file contents, credentials or export destinations. Query error messages are backfilled with the query; error text from other activity sources is not.
• Reconstructed historical names, ownership, permissions, missing identities, timings or a full sequence of status changes. Unavailable values remain unknown.
• Rebuilt historical People / User activity summaries or a replay into every captured-event Explore. Use Query events, AI usage and Historical activity for the imported data.

Backfill recovers selected facts belonging to your organization. It does not export the entire Lightdash database, and it is not continuous synchronization of database records after the import.

​

Troubleshooting

​

I cannot see Lightdash analytics in Settings

Check that your organization has access enabled and that your account has organization administration permissions. On a self-hosted instance, also check the deployment prerequisites.

​

I have project access but cannot open analytics

Check that your account has View managed analytics for the entire organization, plus the ordinary project and content permissions. View usage analytics alone does not grant access to this project. Ask an organization administrator to follow Grant access. Readers open the project through the project selector; they do not need access to the admin-only analytics settings page. If an agent is denied, check its authenticated identity and effective permissions rather than its creator’s access.

​

A dashboard is empty or missing fields

Check the selected dates, whether the relevant activity occurred after capture began, and whether the nightly refresh has completed. Use Sync content when it is offered to update the installed definitions. Sync does not force a data refresh. If a field remains missing after an instance upgrade, contact the Lightdash team.

​

Who is “Unknown user”?

The event could not be matched to a name in the current user snapshot. It does not identify a particular type of actor. Use Explore from here and add User UUID alongside User name. A UUID distinguishes an identified actor whose name is unavailable from activity without a captured user UUID. Inspect Event name, View context, Source or Actor type where the Explore provides them. Do not assume every unknown user is an anonymous embed viewer or an AI agent. A common cause for a row with a User UUID is an account with no first or last name set. Set a name on that user’s profile, and the row shows it after the next scheduled refresh. Keep UUIDs in the grouping when two people or content items share a name. You can hide the UUID column in the visualization while retaining separate groups.