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 account-level query volume, latency, and no-result rate aggregated into time buckets. Useful for dashboard charts and trend analysis.
index_uid.Query parameters
| Parameter | Type | Description |
|---|---|---|
| period optional | string | Lookback period: "24h", "7d", or "30d". Default: "7d" |
| granularity optional | string | Bucket granularity: "hour" or "day". Default: auto (hour for 24h, day for 7d/30d). |
| index_uid optional | string | Filter to a specific index. Omit for account-wide aggregation. |
Example
curl "https://search.example.com/v1/analytics/timeseries?period=7d" \
-H "Authorization: Bearer sk_search_live_..."SDK
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
{
"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
| Parameter | Type | Description |
|---|---|---|
| timestamp required | string | ISO 8601 bucket start time. |
| queries required | number | Total queries in this bucket. |
| avg_latency_ms required | number | Average search latency in milliseconds. |
| no_result_count required | number | Number of queries returning zero results. |
Summary fields
| Parameter | Type | Description |
|---|---|---|
| total_queries required | number | Total queries in the period. |
| avg_latency_ms required | number | Average latency across the period. |
| no_result_rate required | number | Fraction of queries returning zero results (0.0 to 1.0). |
| queries_trend required | number | Percent change vs the previous equivalent period (e.g. +15.3 means 15.3% more queries than the prior 7 days). |
Get the most frequent search queries within a time window.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| days optional | number | Lookback period in days. Default: 7 |
| limit optional | number | Maximum results to return. Default: 20 |
Example
curl "https://search.example.com/v1/indices/products/analytics/top-queries?days=30&limit=10" \
-H "Authorization: Bearer sk_search_live_..."SDK
const top = await idx.getTopQueries({ days: 30, limit: 10 });
Response 200 OK
{
"results": [
{
"query": "nike shoes",
"count": 450,
"avg_hits": 123.5
},
{
"query": "running",
"count": 320,
"avg_hits": 85.2
}
]
}Response fields
| Parameter | Type | Description |
|---|---|---|
| query required | string | The search query text. |
| count required | number | Number of times this query was searched. |
| avg_hits required | number | Average number of results returned for this query. |
Get queries that returned zero results, indicating content gaps.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| days optional | number | Lookback period in days. Default: 7 |
| limit optional | number | Maximum results to return. Default: 20 |
Example
curl "https://search.example.com/v1/indices/products/analytics/no-result-queries?days=7" \
-H "Authorization: Bearer sk_search_live_..."SDK
const noResults = await idx.getNoResultQueries({ days: 7 });
Response 200 OK
{
"results": [
{
"query": "waterproof jacket",
"count": 12,
"last_searched": "2026-01-15T09:22:00Z"
}
]
}Response fields
| Parameter | Type | Description |
|---|---|---|
| query required | string | The search query text. |
| count required | number | Number of times this query returned zero results. |
| last_searched required | string | ISO 8601 timestamp of the most recent search. |
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
| Parameter | Type | Description |
|---|---|---|
| event_type optional | string | Filter by event type: click, view, add_to_cart, purchase, or conversion. Default: "view" |
| days optional | number | Lookback period in days. Must be 1, 7, 14, 30, or 90. Default: 7 |
| limit optional | number | Maximum number of top documents to return. Default: 20 |
| granularity optional | string | Timeseries bucket granularity: "hour" or "day". Default: "hour" for 1 day, "day" otherwise. |
Example
curl "https://search.example.com/v1/indices/products/analytics/events?event_type=click&days=30" \
-H "Authorization: Bearer sk_search_live_..."SDK
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
{
"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
| Parameter | Type | Description |
|---|---|---|
| total required | number | Total number of events matching the filter. |
| unique_documents required | number | Number of distinct documents with at least one event. |
Top document fields
| Parameter | Type | Description |
|---|---|---|
| document_id required | string | Primary key of the document in the index. |
| count required | number | Number of events for this document in the time window. |
Timeseries fields
| Parameter | Type | Description |
|---|---|---|
| timestamp required | string | Bucket start time. Format depends on granularity: "2026-10-01 14:00" for hourly, "2026-10-01" for daily. |
| count required | number | Number 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.
List zero-result query suggestions with optional status filter.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| status optional | string | Filter by status: pending, applied, or dismissed. Default: "pending" |
| limit optional | number | Maximum results to return. Default: 50 |
Example
curl "https://search.example.com/v1/indices/products/analytics/zero-result-suggestions" \
-H "Authorization: Bearer sk_search_live_..."SDK
const suggestions = await idx.getZeroResultSuggestions({ status: 'pending' });
Response 200 OK
{
"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
| Parameter | Type | Description |
|---|---|---|
| id required | number | Suggestion ID. |
| zero_result_query required | string | The query that returned zero results. |
| zero_result_count required | number | Number of times this query was searched with zero results. |
| suggested_query required | string | A semantically similar query that does produce results. |
| suggested_query_hits required | number | Number of results the suggested query returns. |
| similarity required | number | Cosine similarity between the two queries (0 to 1). |
| status required | string | One of: pending, applied, dismissed. |
| created_at required | string | ISO 8601 timestamp. |
| resolved_at required | string | null | ISO 8601 timestamp when applied or dismissed. |
Apply a zero-result suggestion by creating a synonym mapping from the zero-result query to the suggested query.
Example
curl -X POST https://search.example.com/v1/indices/products/analytics/zero-result-suggestions/1/apply \
-H "Authorization: Bearer sk_search_live_..."SDK
const result = await idx.applyZeroResultSuggestion(1);
Response 200 OK
{
"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.
Dismiss a zero-result suggestion without creating a synonym.
Example
curl -X POST https://search.example.com/v1/indices/products/analytics/zero-result-suggestions/1/dismiss \
-H "Authorization: Bearer sk_search_live_..."SDK
await idx.dismissZeroResultSuggestion(1);
Response 200 OK
{
"id": 1,
"status": "dismissed"
}Batch apply or dismiss multiple zero-result suggestions at once. Maximum 100 per request.
Request body
| Parameter | Type | Description |
|---|---|---|
| ids required | number[] | Array of suggestion IDs to resolve. Max 100. |
| action required | string | Either "applied" or "dismissed". |
Example
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
const result = await idx.batchResolveZeroResultSuggestions({ ids: [1, 2, 3], action: 'applied', }); console.log(result.resolved); // 3
Response 200 OK
{
"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.
List auto-synonym suggestions with optional status filter.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| status optional | string | Filter by status: pending, applied, or dismissed. Default: "pending" |
| limit optional | number | Maximum results to return. Default: 50 |
Example
curl "https://search.example.com/v1/indices/products/analytics/auto-synonym-suggestions" \
-H "Authorization: Bearer sk_search_live_..."SDK
const suggestions = await idx.getAutoSynonymSuggestions({ status: 'pending' });
Response 200 OK
{
"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
| Parameter | Type | Description |
|---|---|---|
| id required | number | Suggestion ID. |
| term_a required | string | First term in the pair (alphabetically ordered). |
| term_a_count required | number | Number of documents containing term_a. |
| term_b required | string | Second term in the pair. |
| term_b_count required | number | Number of documents containing term_b. |
| similarity required | number | Cosine similarity between the term embeddings (0 to 1). |
| status required | string | One of: pending, applied, dismissed. |
| created_at required | string | ISO 8601 timestamp. |
| resolved_at required | string | null | ISO 8601 timestamp when applied or dismissed. |
Apply an auto-synonym suggestion by creating bidirectional synonym mappings.
Example
curl -X POST https://search.example.com/v1/indices/products/analytics/auto-synonym-suggestions/1/apply \
-H "Authorization: Bearer sk_search_live_..."SDK
const result = await idx.applyAutoSynonymSuggestion(1);
Response 200 OK
{
"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.
400.Dismiss an auto-synonym suggestion without creating synonyms.
Example
curl -X POST https://search.example.com/v1/indices/products/analytics/auto-synonym-suggestions/1/dismiss \
-H "Authorization: Bearer sk_search_live_..."SDK
await idx.dismissAutoSynonymSuggestion(1);
Response 200 OK
{
"id": 1,
"status": "dismissed"
}Batch apply or dismiss multiple auto-synonym suggestions at once. Maximum 100 per request.
Request body
| Parameter | Type | Description |
|---|---|---|
| ids required | number[] | Array of suggestion IDs to resolve. Max 100. |
| action required | string | Either "applied" or "dismissed". |
Example
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
const result = await idx.batchResolveAutoSynonymSuggestions({ ids: [1, 2, 3], action: 'applied', }); console.log(result.resolved); // 3
Response 200 OK
{
"resolved": 3
}action is "applied", bidirectional synonyms are created for
each suggestion. Suggestions that are already resolved or belong to a different index are
skipped silently.