Analytics

Skirre automatically logs every search query. The analytics endpoints let you understand what users are searching for and where your content has gaps. Intelligence features use embedding similarity to suggest fixes for zero-result queries and discover synonym candidates from your indexed corpus.

For document-level popularity metrics computed from behavioral events, see Document Scoring.

GET /v1/analytics/timeseries Admin key

Get account-level query volume, latency, and no-result rate aggregated into time buckets. Useful for dashboard charts and trend analysis.

Note
This is an account-level endpoint (not per-index). It aggregates data across all indices unless filtered with index_uid.

Query parameters

ParameterTypeDescription
period optionalstringLookback period: "24h", "7d", or "30d".
Default: "7d"
granularity optionalstringBucket granularity: "hour" or "day". Default: auto (hour for 24h, day for 7d/30d).
index_uid optionalstringFilter to a specific index. Omit for account-wide aggregation.

Example

text
curl "https://search.example.com/v1/analytics/timeseries?period=7d" \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const ts = await client.getTimeseries({ period: '7d' });
console.log(ts.summary.total_queries);
console.log(ts.buckets.length); // one bucket per day

Response 200 OK

text
{
  "buckets": [
    {
      "timestamp": "2026-10-03T00:00:00Z",
      "queries": 142,
      "avg_latency_ms": 12.4,
      "no_result_count": 8
    },
    {
      "timestamp": "2026-10-04T00:00:00Z",
      "queries": 198,
      "avg_latency_ms": 11.7,
      "no_result_count": 5
    }
  ],
  "summary": {
    "total_queries": 1250,
    "avg_latency_ms": 12.1,
    "no_result_rate": 0.045,
    "queries_trend": 15.3
  }
}

Bucket fields

ParameterTypeDescription
timestamp requiredstringISO 8601 bucket start time.
queries requirednumberTotal queries in this bucket.
avg_latency_ms requirednumberAverage search latency in milliseconds.
no_result_count requirednumberNumber of queries returning zero results.

Summary fields

ParameterTypeDescription
total_queries requirednumberTotal queries in the period.
avg_latency_ms requirednumberAverage latency across the period.
no_result_rate requirednumberFraction of queries returning zero results (0.0 to 1.0).
queries_trend requirednumberPercent change vs the previous equivalent period (e.g. +15.3 means 15.3% more queries than the prior 7 days).
GET /v1/indices/{uid}/analytics/top-queries Admin key

Get the most frequent search queries within a time window.

Query parameters

ParameterTypeDescription
days optionalnumberLookback period in days.
Default: 7
limit optionalnumberMaximum results to return.
Default: 20

Example

text
curl "https://search.example.com/v1/indices/products/analytics/top-queries?days=30&limit=10" \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const top = await idx.getTopQueries({ days: 30, limit: 10 });

Response 200 OK

text
{
  "results": [
    {
      "query": "nike shoes",
      "count": 450,
      "avg_hits": 123.5
    },
    {
      "query": "running",
      "count": 320,
      "avg_hits": 85.2
    }
  ]
}

Response fields

ParameterTypeDescription
query requiredstringThe search query text.
count requirednumberNumber of times this query was searched.
avg_hits requirednumberAverage number of results returned for this query.
GET /v1/indices/{uid}/analytics/no-result-queries Admin key

Get queries that returned zero results, indicating content gaps.

Query parameters

ParameterTypeDescription
days optionalnumberLookback period in days.
Default: 7
limit optionalnumberMaximum results to return.
Default: 20

Example

text
curl "https://search.example.com/v1/indices/products/analytics/no-result-queries?days=7" \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const noResults = await idx.getNoResultQueries({ days: 7 });

Response 200 OK

text
{
  "results": [
    {
      "query": "waterproof jacket",
      "count": 12,
      "last_searched": "2026-01-15T09:22:00Z"
    }
  ]
}

Response fields

ParameterTypeDescription
query requiredstringThe search query text.
count requirednumberNumber of times this query returned zero results.
last_searched requiredstringISO 8601 timestamp of the most recent search.
GET /v1/indices/{uid}/analytics/events Admin key

Get aggregated behavioral event data for an index — summary counts, top documents by event type, and timeseries breakdown.

This endpoint queries the behavioral events you've sent via POST /v1/events. Use it to understand which documents get the most clicks, views, or purchases over a given time window.

Query parameters

ParameterTypeDescription
event_type optionalstringFilter by event type: click, view, add_to_cart, purchase, or conversion.
Default: "view"
days optionalnumberLookback period in days. Must be 1, 7, 14, 30, or 90.
Default: 7
limit optionalnumberMaximum number of top documents to return.
Default: 20
granularity optionalstringTimeseries bucket granularity: "hour" or "day". Default: "hour" for 1 day, "day" otherwise.

Example

text
curl "https://search.example.com/v1/indices/products/analytics/events?event_type=click&days=30" \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const analytics = await idx.getEventAnalytics({
  event_type: 'click',
  days: 30,
  limit: 10,
});

console.log(analytics.summary.total);            // total click events
console.log(analytics.summary.unique_documents);  // distinct documents clicked
console.log(analytics.top_documents);             // top 10 most-clicked documents
console.log(analytics.timeseries);                // daily click counts

Response 200 OK

text
{
  "summary": {
    "total": 1847,
    "unique_documents": 312
  },
  "top_documents": [
    { "document_id": "prod_abc123", "count": 94 },
    { "document_id": "prod_def456", "count": 71 }
  ],
  "timeseries": [
    { "timestamp": "2026-10-01", "count": 62 },
    { "timestamp": "2026-10-02", "count": 78 }
  ]
}

Summary fields

ParameterTypeDescription
total requirednumberTotal number of events matching the filter.
unique_documents requirednumberNumber of distinct documents with at least one event.

Top document fields

ParameterTypeDescription
document_id requiredstringPrimary key of the document in the index.
count requirednumberNumber of events for this document in the time window.

Timeseries fields

ParameterTypeDescription
timestamp requiredstringBucket start time. Format depends on granularity: "2026-10-01 14:00" for hourly, "2026-10-01" for daily.
count requirednumberNumber of events in this bucket.

Zero-Result Suggestions

When semantic search is enabled, Skirre automatically identifies queries that return zero results and uses embedding similarity to suggest alternative queries that do produce results. For example, if users search for "fone cases" and get nothing, Skirre may suggest redirecting to "phone cases" (which has 87 results).

Suggestions are computed by a nightly background job. You review and apply or dismiss each suggestion — they are never auto-applied.

Note
Zero-result suggestions require semantic search to be enabled on the index (the embedding model is used to compute query similarity). See Semantic Search to enable it.
GET /v1/indices/{uid}/analytics/zero-result-suggestions Admin key

List zero-result query suggestions with optional status filter.

Query parameters

ParameterTypeDescription
status optionalstringFilter by status: pending, applied, or dismissed.
Default: "pending"
limit optionalnumberMaximum results to return.
Default: 50

Example

text
curl "https://search.example.com/v1/indices/products/analytics/zero-result-suggestions" \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const suggestions = await idx.getZeroResultSuggestions({ status: 'pending' });

Response 200 OK

text
{
  "suggestions": [
    {
      "id": 1,
      "zero_result_query": "fone cases",
      "zero_result_count": 87,
      "suggested_query": "phone cases",
      "suggested_query_hits": 42,
      "similarity": 0.89,
      "status": "pending",
      "created_at": "2026-10-08T03:00:00Z"
    }
  ]
}

Suggestion fields

ParameterTypeDescription
id requirednumberSuggestion ID.
zero_result_query requiredstringThe query that returned zero results.
zero_result_count requirednumberNumber of times this query was searched with zero results.
suggested_query requiredstringA semantically similar query that does produce results.
suggested_query_hits requirednumberNumber of results the suggested query returns.
similarity requirednumberCosine similarity between the two queries (0 to 1).
status requiredstringOne of: pending, applied, dismissed.
created_at requiredstringISO 8601 timestamp.
resolved_at requiredstring | nullISO 8601 timestamp when applied or dismissed.
POST /v1/indices/{uid}/analytics/zero-result-suggestions/{id}/apply Admin key

Apply a zero-result suggestion by creating a synonym mapping from the zero-result query to the suggested query.

Example

text
curl -X POST https://search.example.com/v1/indices/products/analytics/zero-result-suggestions/1/apply \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const result = await idx.applyZeroResultSuggestion(1);

Response 200 OK

text
{
  "id": 1,
  "status": "applied",
  "synonym_added": {
    "key": "fone cases",
    "values": ["phone cases"]
  }
}

Applying creates a one-way synonym: the zero-result query is mapped to the suggested query. The synonym is saved to the index settings and takes effect immediately.

POST /v1/indices/{uid}/analytics/zero-result-suggestions/{id}/dismiss Admin key

Dismiss a zero-result suggestion without creating a synonym.

Example

text
curl -X POST https://search.example.com/v1/indices/products/analytics/zero-result-suggestions/1/dismiss \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
await idx.dismissZeroResultSuggestion(1);

Response 200 OK

text
{
  "id": 1,
  "status": "dismissed"
}
POST /v1/indices/{uid}/analytics/zero-result-suggestions/batch Admin key

Batch apply or dismiss multiple zero-result suggestions at once. Maximum 100 per request.

Request body

ParameterTypeDescription
ids requirednumber[]Array of suggestion IDs to resolve. Max 100.
action requiredstringEither "applied" or "dismissed".

Example

text
curl -X POST https://search.example.com/v1/indices/products/analytics/zero-result-suggestions/batch \
  -H "Authorization: Bearer sk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": [1, 2, 3], "action": "applied" }'

SDK

text
const result = await idx.batchResolveZeroResultSuggestions({
  ids: [1, 2, 3],
  action: 'applied',
});
console.log(result.resolved); // 3

Response 200 OK

text
{
  "resolved": 3
}

Auto-Synonym Suggestions

Skirre analyzes your indexed documents to discover terms that are semantically equivalent but not yet linked by synonyms. A nightly background job extracts unique terms from your corpus, embeds them with BGE-small, and identifies pairs with high cosine similarity (threshold: 0.85). These are surfaced as actionable suggestions.

For example, Skirre might discover that "ring" and "rings" (similarity: 0.92) or "sneakers" and "trainers" (similarity: 0.91) appear in your catalog but aren't mapped as synonyms. You review each pair and apply or dismiss — suggestions are never auto-applied.

Note
Auto-synonym suggestions require semantic search to be enabled on the index. The embedding model is used to compute term similarity. See Semantic Search to enable it.
GET /v1/indices/{uid}/analytics/auto-synonym-suggestions Admin key

List auto-synonym suggestions with optional status filter.

Query parameters

ParameterTypeDescription
status optionalstringFilter by status: pending, applied, or dismissed.
Default: "pending"
limit optionalnumberMaximum results to return.
Default: 50

Example

text
curl "https://search.example.com/v1/indices/products/analytics/auto-synonym-suggestions" \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const suggestions = await idx.getAutoSynonymSuggestions({ status: 'pending' });

Response 200 OK

text
{
  "suggestions": [
    {
      "id": 1,
      "term_a": "display",
      "term_a_count": 3,
      "term_b": "displays",
      "term_b_count": 4,
      "similarity": 0.95,
      "status": "pending",
      "created_at": "2026-10-08T03:04:00Z"
    },
    {
      "id": 2,
      "term_a": "ring",
      "term_a_count": 3,
      "term_b": "rings",
      "term_b_count": 48,
      "similarity": 0.92,
      "status": "pending",
      "created_at": "2026-10-08T03:04:00Z"
    }
  ]
}

Suggestion fields

ParameterTypeDescription
id requirednumberSuggestion ID.
term_a requiredstringFirst term in the pair (alphabetically ordered).
term_a_count requirednumberNumber of documents containing term_a.
term_b requiredstringSecond term in the pair.
term_b_count requirednumberNumber of documents containing term_b.
similarity requirednumberCosine similarity between the term embeddings (0 to 1).
status requiredstringOne of: pending, applied, dismissed.
created_at requiredstringISO 8601 timestamp.
resolved_at requiredstring | nullISO 8601 timestamp when applied or dismissed.
POST /v1/indices/{uid}/analytics/auto-synonym-suggestions/{id}/apply Admin key

Apply an auto-synonym suggestion by creating bidirectional synonym mappings.

Example

text
curl -X POST https://search.example.com/v1/indices/products/analytics/auto-synonym-suggestions/1/apply \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
const result = await idx.applyAutoSynonymSuggestion(1);

Response 200 OK

text
{
  "id": 1,
  "status": "applied",
  "synonyms_added": [
    { "key": "display", "values": ["displays"] },
    { "key": "displays", "values": ["display"] }
  ]
}

Applying creates bidirectional synonyms: term_a maps to term_b and term_b maps to term_a. Both mappings are saved to the index settings and take effect immediately.

Note
Applying a suggestion that is already resolved (applied or dismissed) returns 400.
POST /v1/indices/{uid}/analytics/auto-synonym-suggestions/{id}/dismiss Admin key

Dismiss an auto-synonym suggestion without creating synonyms.

Example

text
curl -X POST https://search.example.com/v1/indices/products/analytics/auto-synonym-suggestions/1/dismiss \
  -H "Authorization: Bearer sk_search_live_..."

SDK

text
await idx.dismissAutoSynonymSuggestion(1);

Response 200 OK

text
{
  "id": 1,
  "status": "dismissed"
}
POST /v1/indices/{uid}/analytics/auto-synonym-suggestions/batch Admin key

Batch apply or dismiss multiple auto-synonym suggestions at once. Maximum 100 per request.

Request body

ParameterTypeDescription
ids requirednumber[]Array of suggestion IDs to resolve. Max 100.
action requiredstringEither "applied" or "dismissed".

Example

text
curl -X POST https://search.example.com/v1/indices/products/analytics/auto-synonym-suggestions/batch \
  -H "Authorization: Bearer sk_search_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "ids": [1, 2, 3], "action": "applied" }'

SDK

text
const result = await idx.batchResolveAutoSynonymSuggestions({
  ids: [1, 2, 3],
  action: 'applied',
});
console.log(result.resolved); // 3

Response 200 OK

text
{
  "resolved": 3
}
Note
When action is "applied", bidirectional synonyms are created for each suggestion. Suggestions that are already resolved or belong to a different index are skipped silently.