Query usage log

In Liberator 2.4 and later, Super Admins can query usage_log — a standard Liberator dataset of one row per query per dataset. Use it to see who queried which dataset, which as_of / back_to window they requested, how many rows came back, and whether the query succeeded or was rejected. This is the per-query drill-down that monthly usage totals and AI-based reporting do not provide. It uses the same liberator.query API as any other dataset, including Python, REST, Excel, and MCP.

usage_log is Super Admin only. It is private and hidden from the standard user catalog. Regular users cannot discover or query it, and it is not granted through ordinary Data Permissions.

Who can query it

Role	Can query `usage_log`
Super Admin	Yes
Admin / User	No

If a Super Admin query returns “not entitled” or the dataset is missing, usage logging may not be enabled on that instance. Contact CloudQuant.

Query the log

The query parameters as_of and back_to select when the usage occurred (when someone ran a query). They are not the date range those users requested — those values are columns on each row. The symbol / key is the dataset that was queried, not a ticker. symbols='daily_bars' returns usage rows for queries against daily_bars.

import liberator

# Every query on 2026-08-28 (daily granularity)
df = liberator.get_dataframe(liberator.query(
    name='usage_log',
    back_to='2026-08-28',
    as_of='2026-08-29',
))

# Only queries against one dataset
df = liberator.get_dataframe(liberator.query(
    name='usage_log',
    symbols='daily_bars',
    back_to='2026-08-28',
    as_of='2026-08-29',
))

# One user's queries in August
df = liberator.get_dataframe(liberator.query(
    name='usage_log',
    back_to='2026-08-01',
    as_of='2026-09-01',
    where="user_id = $$jane.doe$$",
))

# Rejections and errors
df = liberator.get_dataframe(liberator.query(
    name='usage_log',
    back_to='2026-08-28',
    as_of='2026-08-29',
    where="status != $$success$$",
))

Recent queries are included as they complete — you do not wait for a daily rollup.

Record grain

One row per (query, dataset). A request that names several datasets produces several rows that share the same qid. Rejected queries still appear, with rows_returned of 0 and status of not_entitled, limit_exceeded, or error.

Columns

Column	Meaning
`timestamp` / `muts`	When the usage record was stored (Liberator’s usual time axis)
`symbol`	Key field — the dataset that was queried (same value as `dataset_name`)
`dataset_name`	Dataset the user requested
`user_id`	Liberator username that ran the query
`system`	Client / system identifier from the request (for example `API`)
`as_of`	`as_of` the caller passed (the original query’s end time)
`back_to`	`back_to` the caller passed (the original query’s start time)
`rows_returned`	Rows delivered for that dataset; `0` if the query was rejected
`status`	Outcome — see below
`qid`	Query id; shared by every dataset row from the same request
`request_id`	Optional correlation id from the connection
`detail`	Extra reason text (for example an error class, or a client disconnect)
`query_timestamp`	UTC microseconds when the original query finished

Do not confuse the columns as_of / back_to (what the user asked for) with the parameters as_of / back_to on your usage_log query (which slice of the log you want).

Status values

`status`	Meaning
`success`	Query completed and returned data (including an empty result that was allowed)
`limit_exceeded`	Rejected by a usage or entitlement cap (for example max rows or max query days)
`not_entitled`	Caller is not entitled to the dataset
`error`	Any other failure

Retention

Records are kept for at least 30 days. Retention is configured for the instance — contact CloudQuant to change it.

AI-based reporting

Aggregated usage, user, and entitlement reports in the Admin UI

System monitoring

Cluster health, long queries, and license utilization

Fine-grained permissions

Caps that show up as limit_exceeded on usage_log

What's new in 2.4

Liberator 2.4 release notes

Getting Started

What's New

Administration

CloudQuant Data Liberator Python Guide

System Monitoring

Data Science Recipes

Query Usage Log

Query usage log

Who can query it

Query the log

Record grain

Columns

Status values

Retention

AI-based reporting

System monitoring

Fine-grained permissions

What's new in 2.4

​Query usage log

​Who can query it

​Query the log

​Record grain

​Columns

​Status values

​Retention

​Related

AI-based reporting

System monitoring

Fine-grained permissions

What's new in 2.4

Query usage log

Who can query it

Query the log

Record grain

Columns

Status values

Retention

Related