From 6051ee2ef243417bbd1e25d83d203da18cd3d179 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 26 Mar 2026 20:42:23 +0000 Subject: [PATCH] Add search queries analytics endpoint documentation Generated-By: mintlify-agent --- analytics.openapi.json | 147 +++++++++++++++++++++++++++++++++++++ api/analytics/searches.mdx | 27 +++++++ docs.json | 3 +- 3 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 api/analytics/searches.mdx diff --git a/analytics.openapi.json b/analytics.openapi.json index e7b80c1b6..9c1a24528 100644 --- a/analytics.openapi.json +++ b/analytics.openapi.json @@ -274,6 +274,61 @@ "error" ] }, + "SearchesResponse": { + "type": "object", + "properties": { + "searches": { + "type": "array", + "description": "List of search term aggregates, ordered by hit count descending.", + "items": { + "type": "object", + "properties": { + "searchQuery": { + "type": "string", + "description": "The search term entered by users." + }, + "hits": { + "type": "integer", + "description": "Number of times this term was searched." + }, + "ctr": { + "type": "number", + "description": "Click-through rate for this search term (0–1)." + }, + "topClickedPage": { + "type": ["string", "null"], + "description": "Path of the most-clicked result for this query, if any." + }, + "lastSearchedAt": { + "type": "string", + "description": "ISO 8601 timestamp of the last time this term was searched." + } + }, + "required": [ + "searchQuery", + "hits", + "ctr", + "topClickedPage", + "lastSearchedAt" + ] + } + }, + "totalSearches": { + "type": "integer", + "minimum": 0, + "description": "Total count of search events in the requested date range (sum of all hits, not distinct queries)." + }, + "nextCursor": { + "type": ["string", "null"], + "description": "Opaque cursor to retrieve the next page of results. Null if no more results." + } + }, + "required": [ + "searches", + "totalSearches", + "nextCursor" + ] + }, "AssistantConversationsResponse": { "type": "object", "properties": { @@ -575,6 +630,98 @@ } } } + }, + "/v1/analytics/{projectId}/searches": { + "get": { + "summary": "Get search queries", + "description": "Returns paginated documentation search terms for the date range, ordered by hit count descending. Each row includes click-through rate, the most-clicked result path for that query (if any), and the last time the term was searched. `totalSearches` is the total number of search query events in the same date range (sum of all hits, not distinct queries).", + "tags": [ + "Analytics" + ], + "security": [ + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/projectId" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format", + "example": "2024-01-01" + }, + "required": false, + "name": "dateFrom", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Date in ISO 8601 or YYYY-MM-DD format. `dateTo` is an exclusive upper limit. Results include dates before, but not on, the specified date.", + "example": "2024-01-01" + }, + "required": false, + "name": "dateTo", + "in": "query" + }, + { + "schema": { + "type": "number", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Max search terms per page (ordered by hit count descending)" + }, + "required": false, + "name": "limit", + "in": "query" + }, + { + "schema": { + "type": "string", + "description": "Opaque pagination cursor from the previous response" + }, + "required": false, + "name": "cursor", + "in": "query" + } + ], + "responses": { + "200": { + "description": "Search term aggregates with pagination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SearchesResponse" + } + } + } + }, + "400": { + "description": "Invalid query parameters or cursor", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + }, + "500": { + "description": "Server error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AnalyticsErrorResponse" + } + } + } + } + } + } } }, "webhooks": {} diff --git a/api/analytics/searches.mdx b/api/analytics/searches.mdx new file mode 100644 index 000000000..5df0e5a91 --- /dev/null +++ b/api/analytics/searches.mdx @@ -0,0 +1,27 @@ +--- +title: "Get search queries" +description: "Retrieve aggregated search query data from your documentation, including hit counts, click-through rates, and top clicked pages." +openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/searches +keywords: ["analytics", "search", "queries", "export", "search insights"] +--- + +## Usage + +Use this endpoint to export search analytics from your documentation. Each entry represents a distinct search term with aggregated metrics over the requested date range. + +Results are ordered by hit count descending. Paginate through results using the opaque `cursor` value returned in `nextCursor`. Continue fetching while `nextCursor` is non-null. + +## Filtering + +Filter search data by date range using `dateFrom` and `dateTo` parameters. + +## Response data + +Each search term entry includes: +- **searchQuery**: The term users searched for +- **hits**: Total number of times the term was searched +- **ctr**: Click-through rate for the search term (0–1) +- **topClickedPage**: The most-clicked result path for this query, if any +- **lastSearchedAt**: When the term was last searched + +The `totalSearches` field in the response is the total count of all search events in the date range (sum of all hits across all queries, not distinct query count). diff --git a/docs.json b/docs.json index af1132fe7..ce371f6dd 100644 --- a/docs.json +++ b/docs.json @@ -373,7 +373,8 @@ "icon": "chart-line", "pages": [ "api/analytics/feedback", - "api/analytics/assistant-conversations" + "api/analytics/assistant-conversations", + "api/analytics/searches" ] } ]