Get search queries
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.
totalSearchesis the total number of search query events in the same date range (sum of all hits, not distinct queries).
Authenticate with an admin API key.
Use this endpoint to export documentation search analytics. Results are ordered by hit count descending, showing which terms your users search for most.
Paginate through results using the nextCursor parameter returned in the response. Continue fetching while nextCursor is not null.
Filtering
Section titled “Filtering”Filter search data by date range using dateFrom and dateTo parameters.
Rate limits
Section titled “Rate limits”This endpoint allows 100 requests per organization per hour. All analytics endpoints share this limit.
OpenAPI
Section titled “OpenAPI”openapi: 3.1.0
info:
title: Mintlify Analytics Export API
version: 1.0.0
description: API for exporting documentation analytics data
servers:
- url: https://api.mintlify.com
description: Production
security: []
paths:
/v1/analytics/{projectId}/searches:
get:
tags:
- Analytics
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).
Authenticate with an admin API key.
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'
security:
- bearerAuth: []
components:
parameters:
projectId:
schema:
$ref: '#/components/schemas/projectId'
required: true
name: projectId
in: path
schemas:
SearchesResponse:
type: object
properties:
searches:
type: array
description: Search terms ordered by hit count descending.
items:
type: object
properties:
searchQuery:
type: string
description: The search term entered by users.
hits:
type: number
description: Number of times this term was searched.
ctr:
type: number
description: >-
Percentage of searches for this term that resulted in a click
on a specific search result (clicks ÷ hits × 100). A click
includes selecting a result with the pointer or pressing Enter
when a result is highlighted. Submitting a query by itself
does not count as a click. Clicking the AI assistant in the
search bar, or pressing Enter to use it, counts as a search
with no click and is not tracked separately in this field.
topClickedPage:
type:
- string
- 'null'
description: The most-clicked result path for this query, if any.
lastSearchedAt:
type: string
description: 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 pagination cursor for the next page. Null if no more results.
required:
- searches
- totalSearches
- nextCursor
AnalyticsErrorResponse:
type: object
properties:
error:
type: string
description: Error message describing what went wrong.
details:
type: array
description: Additional details about the error.
items:
type: object
properties:
message:
type: string
description: Description of a specific validation or processing error.
required:
- message
required:
- error
projectId:
type: string
description: >-
Your project ID. Can be copied from the [API
keys](https://app.mintlify.com/settings/organization/api-keys) page in
your dashboard.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
The Authorization header expects a Bearer token. Use an admin API key.
This is a server-side secret key. Generate one on the [API keys
page](https://app.mintlify.com/settings/organization/api-keys) in your
dashboard.