diff --git a/analytics.openapi.json b/analytics.openapi.json index e7b80c1b6..8f827d217 100644 --- a/analytics.openapi.json +++ b/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": {} diff --git a/api/analytics/searches.mdx b/api/analytics/searches.mdx new file mode 100644 index 000000000..fa9f568de --- /dev/null +++ b/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. diff --git a/api/introduction.mdx b/api/introduction.mdx index d5b28d6d2..e1277638b 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -17,6 +17,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [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 @@ -24,7 +25,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - **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 @@ You can create up to 10 API keys per hour per organization. ### 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. 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" ] } ]