On this page

Usage analytics and query logs

Find the cause of a failed or slow answer

  1. As a space owner, open Analytics → Questions and choose a Period. Filter by outcome, mode, entry point or rating. Open a row and compare stage times, model calls, passages found and passages sent to the model. Stored question and answer-check text requires a separate text grant.

  2. Check the daily totals by mode or entry point. For example, open queries with Nothing found to check those questions against the index. After a fix, ask the same question in Work. If it returned a query ID, Open query details takes an owner directly to the logged row.

  3. For a latency spike, compare p50 and p95 overall and by stage. In Cost, check for unpriced calls. The total sums priced calls. Per-answer cost percentiles cover queries with prices for every call. Compare helpful and unhelpful counts alongside the share of rated queries.

After individual query rows expire, daily totals remain. Latency percentiles, per-answer cost and unique askers cover only the retained portion of the period. The analytics response gives the start of that portion in rows_since. Use Document use to see which documents were retrieved and which were included in model context.

Export questions or collect an evaluation dataset

Export CSV downloads up to the newest 50,000 rows matching the selected period and filters. Narrow the period or filters for a smaller export. Text is included only if it was retained and you hold the text-reading grant.

Select up to 500 questions whose text you can read and choose Build an evaluation set. At least one question must have reached a document that still has extracted text. ContextBase copies the logged questions and the documents’ current text when you collect the dataset. If a document was replaced since the query, this text can differ from what the query used. Collected datasets and exported files are independent copies.

Open the result in Datasets. To run metrics that need relevance labels or reference answers, read the collected corpus and questions, annotate them, and upload a new dataset. See Evaluate retrieval and answers for the JSON format and the paginated REST reads.

Control storage and access to text

In Settings → Stored query and answer-check text, turn off Keep question and answer-check text to stop retaining text for new queries. The switch also covers drafts, generation context and check explanations. Timings, outcomes, costs and source metadata continue to be recorded. Previously saved text remains subject to the normal retention policy.

In Analytics → Who may read query and answer-check text, an owner who already holds the text grant can give it to another owner or revoke it. The account that created the space receives the grant when the space is created. Reads of query and answer-check text shows who viewed text in a list or detail, exported it or collected a dataset with it.

The installation sets QUERY_LOG_RETENTION_DAYS (90 days by default) and QUERY_LOG_MASK_PATTERNS, a JSON list of regular expressions to mask matching text before storage. Masking can miss personal information. The self-service API DELETE /api/v1/query-log/mine removes the signed-in account’s retained query rows in every space. Older, anonymous daily totals remain available.

Read analytics through REST

The analytics endpoints use an interactive access token in Authorization: Bearer <access_token>. For the space routes, the token must belong to an owner. All paths in the table use the prefix /api/v1/spaces/{space_id}/analytics.

Request

What to inspect or change

GET on the prefix

Summary for the last days days counting today in UTC.

GET /queries and GET /queries/{query_id}

Filterable log and a single query’s details.

GET /queries/export and POST /datasets

CSV export and dataset collection. To collect a dataset, pass name and query_ids.

GET /settings and PUT /settings

Read or set store_query_texts.

GET /text-accesses and PUT /text-readers/{user_id}

Audit text reads and grant or revoke access.

See REST API reference for the full request and response schemas. The analytics summary and retention settings define the period and data available.

ContextBase0.1.0

Search the documentation