Add search queries analytics API endpoint

analytics.openapi.json

@@ -355,6 +355,67 @@
           "nextCursor",
           "hasMore"
         ]
+      },
+      "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 a user."
+                },
+                "hits": {
+                  "type": "integer",
+                  "description": "Total number of times this term was searched."
+                },
+                "ctr": {
+                  "type": "number",
+                  "description": "Click-through rate: the ratio of searches that led to a result click (0–1)."
+                },
+                "topClickedPage": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Path of the most-clicked search result for this query, if any."
+                },
+                "lastSearchedAt": {
+                  "type": "string",
+                  "description": "ISO 8601 timestamp of the most recent search for this term."
+                }
+              },
+              "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 pagination cursor for the next page. Null if no more results."
+          }
+        },
+        "required": [
+          "searches",
+          "totalSearches",
+          "nextCursor"
+        ]
       }
     },
     "parameters": {
@@ -575,6 +636,98 @@
           }
         }
       }
+    },
+    "/v1/analytics/{projectId}/searches": {
+      "get": {
+        "summary": "Get search queries",
+        "description": "Returns paginated search terms from your documentation, 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.",
+        "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": {}

api/analytics/searches.mdx

@@ -0,0 +1,29 @@
+---
+title: "Get search queries"
+description: "Retrieve search terms from your documentation with hit counts, click-through rates, and top clicked pages."
+openapi: /analytics.openapi.json GET /v1/analytics/{projectId}/searches
+keywords: ["analytics", "search", "queries", "export", "search analytics"]
+---
+
+## Usage
+
+Use this endpoint to export search query data from your documentation. Each result includes the search term, how many times it was searched, the click-through rate, and the most-clicked result page.
+
+Results are ordered by hit count descending, so the most popular search terms appear first.
+
+Paginate through results using the `cursor` parameter returned in the response. Continue fetching while `nextCursor` is not null.
+
+## Filtering
+
+Filter search data by date range using `dateFrom` and `dateTo` parameters.
+
+## Search data
+
+Each search term includes:
+- **searchQuery**: The term users searched for
+- **hits**: Total number of times this term was searched in the date range
+- **ctr**: Click-through rate, the ratio of searches that led to a result click (0–1)
+- **topClickedPage**: Path of the most-clicked search result for this query
+- **lastSearchedAt**: When the term was last searched
+
+The `totalSearches` field in the response is the sum of all search events in the date range, not the number of distinct queries.

api/introduction.mdx

@@ -4,9 +4,9 @@
 keywords: ["REST API", "endpoints", "API keys"]
 ---
 
 The Mintlify REST (Representational State Transfer) API enables you to programmatically interact with your documentation, trigger updates, embed AI-powered chat experiences, and export analytics data.
 
 ## Endpoints
 
 - [Trigger update](/api/update/trigger): Trigger an update of your site when desired.
 - [Get update status](/api/update/status): Get the status of an update and other details about your docs.
@@ -17,14 +17,15 @@
 - [Search documentation](/api/assistant/search): Search through your documentation.
 - [Get user feedback](/api/analytics/feedback): Export user feedback from your documentation.
 - [Get assistant conversations](/api/analytics/assistant-conversations): Export AI assistant conversation history.
+- [Get search queries](/api/analytics/searches): Export search term analytics from your documentation.
 
 ### Common use cases
 
 - **Automated deployments**: Trigger site updates at set intervals or when events occur with [Trigger update](/api/update/trigger) and [Get update status](/api/update/status).
 - **CI/CD integration**: Update documentation as part of your deployment pipeline when code changes with [Trigger update](/api/update/trigger).
 - **Custom integrations**: Embed the AI assistant into your product, support portal, or internal tools with [Create assistant message](/api/assistant/create-assistant-message-v2) and [Search documentation](/api/assistant/search).
 - **Automated editing**: Use agent jobs to programmatically update documentation at scale with [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), and [Send follow-up message](/api/agent/v2/send-message).
-- **Analytics export**: Export feedback and assistant conversations for external analysis with [Get user feedback](/api/analytics/feedback) and [Get assistant conversations](/api/analytics/assistant-conversations).
+- **Analytics export**: Export feedback, assistant conversations, and search analytics for external analysis with [Get user feedback](/api/analytics/feedback), [Get assistant conversations](/api/analytics/assistant-conversations), and [Get search queries](/api/analytics/searches).
 
 ## Authentication
 
@@ -34,7 +35,7 @@
 
 ### Admin API key
 
-Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), and [Get assistant conversations](/api/analytics/assistant-conversations).
+Use the admin API key to authenticate requests to [Trigger update](/api/update/trigger), [Get update status](/api/update/status), [Create agent job](/api/agent/v2/create-agent-job), [Get agent job](/api/agent/v2/get-agent-job), [Send follow-up message](/api/agent/v2/send-message), [Get user feedback](/api/analytics/feedback), [Get assistant conversations](/api/analytics/assistant-conversations), and [Get search queries](/api/analytics/searches).
 
 Admin API keys begin with the `mint_` prefix. 
 

docs.json

@@ -373,7 +373,8 @@
                 "icon": "chart-line",
                 "pages": [
                   "api/analytics/feedback",
-                  "api/analytics/assistant-conversations"
+                  "api/analytics/assistant-conversations",
+                  "api/analytics/searches"
                 ]
               }
             ]