> For the complete documentation index, see [llms.txt](https://docs.observal.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.observal.io/self-hosting/usage-reporting.md). # Usage reporting Observal can send aggregate usage reports to the Observal-operated collector at `https://usage.observal.io/api/v1/usage-pings`. Reporting is enabled by default with a six-hour cadence, but delivery remains dormant until a super administrator configures the company name and Deployment Public URL. The collector and reporting dashboard are maintained separately in [Observal Usage](https://github.com/Observal/observal_usage). ## Enable reporting A super administrator must configure **Deployment Public URL** and then open **Admin > Settings > Usage Reporting**, which appears near the top of the settings page. Enter the company name and save the reporting configuration. The available frequencies are every six hours, daily, and weekly. Every six hours is the default. The same panel can disable reporting, change the frequency, preview the exact payload, and send a test report. Only a super administrator can change the company identity, frequency, or consent setting. Disabling the switch stops scheduled delivery immediately. It does not remove reports already received by Observal. Contact the Observal maintainers with the installation ID shown in the panel to request deletion. ## Data included * Stable, randomly generated installation ID * Company name and deployment hostname supplied by the administrator * Observal version and deployment type * Aggregate counts for users, teams, registry components, agent installations, and sessions * Aggregate session totals by harness * Distinct active-user and active-agent counts for 7- and 30-day windows * Aggregate event, prompt, tool-call, tool-result, token, cache-token, and credit totals for 7- and 30-day windows * Thirty-day session averages for duration, prompts, and tool calls * Thirty-day counts for sessions using tools or tokens, registered versus unregistered agents, top-level versus sub-agent sessions, and distinct agent/model versions * Aggregate parser-error and truncated-event counts for ingestion health * Boolean adoption signals for selected server features * Report schema version and timestamp ## Data never included Usage reports do not include names, email addresses, user IDs, agent IDs, prompts, responses, tool arguments, tool results, trace events, source code, file paths, repository names, model identifiers, IP addresses, authentication tokens, API keys, credentials, or arbitrary configuration values. Token and credit fields contain numeric totals only. Distinct model and agent-version fields contain counts, never their names or identifiers. Only the selected feature flags listed above are included. ## Delivery behavior The selected schedule uses fixed UTC boundaries: * Every six hours: 00:30, 06:30, 12:30, and 18:30 UTC * Daily: 06:30 UTC each day * Weekly: Monday at 06:30 UTC The worker evaluates due reports every six hours. If a scheduled report was missed or failed, a later worker pass retries it until the current schedule window has a successful delivery. Each pass makes up to three total delivery attempts with short backoff. A failure never blocks normal Observal operation. The last successful send, latest error, selected frequency, and next delivery time are visible in the Usage Reporting settings panel. The collector URL is fixed in production releases. `USAGE_PING_URL` exists only to direct development and isolated test deployments to a local collector. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.observal.io/self-hosting/usage-reporting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.