Get HelpCenter Search Queries And Content Gaps
helpcenter_get_search_queriesWhat visitors searched for in the connected HelpCenter.io help center, and what they did not find.
Read-only. START HERE when the question is "what content is missing?", "what should I write next?", or "why are customers still contacting support?". The content_gaps list is close to a literal backlog of articles that do not exist yet, ranked by how many people wanted them — it is the single most actionable thing this API returns, and the natural input to helpcenter_create_article.
COST AND RATE LIMIT: this is an expensive query, and the three analytics tools share a limit of 6 requests per minute per API key — far below the other read tools. The underlying figures are recomputed only once a day, so asking again in a few seconds returns identical numbers at full cost. Read once, keep the answer, and do NOT poll or retry in a loop. If you are refused with a rate-limit error, stop rather than backing off and retrying.
Leave from/to unset unless the user asked about a specific period: the default window is the trailing 7 days, is served from a pre-computed cache rather than the warehouse, and is the right answer for a general question. Maximum window is 92 days; wider is refused.
Args:
limit (number, optional): rows per list, 1-50 (default 20). Raising it is free — these read pre-aggregated daily tables, so the same data is scanned either way. Ask for more when building a content plan.
from / to / lang (optional): see above.
response_format ('markdown' | 'json'): default 'markdown'.
Returns: { range, content_gaps: [...], frequent_queries: [...], common_terms: [...], meta: { limit, lists_are_top_n } }.
Each gap row is { query, searches, unique_visitors, zero_result_searches, no_click_searches, failed_searches, failure_rate, reason, last_searched_at, top_hit, article_clicked }.
The two failure modes need DIFFERENT fixes, so read reason:
'0 results' — nothing matched. Write the article.
'no click' — results came back and nobody opened one. The article probably exists but does not look like the answer; fix its title and opening lines rather than writing a new one.
'mixed' — both happened across different searches of the same query.
Two things not to get wrong:
Every list is a TOP-N, not a complete list.
limitrows of content_gaps means "the N worst gaps", NOT "there were N gaps". Never state or infer a total from it.There are NO search totals here. Use
traffic.searchesfrom helpcenter_get_analytics_summary if you need volume. Deriving one from these truncated lists would produce a number that disagrees with the real one.
common_terms are single words pulled out of queries, so they overlap with the query rows and the two lists do not sum to anything. Terms spot a topic; queries are what you write an article from.
Privacy: everything here is aggregated. No visitor identifiers, IP addresses or per-search rows are available through this API at all.
Errors: 429 if the shared analytics rate limit is exceeded — stop, do not retry. 503 if the analytics backend is temporarily unavailable.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "helpcenter_get_search_queries"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End of the reporting window, YYYY-MM-DD, inclusive. Defaults to today. | |
| from | No | Start of the reporting window, YYYY-MM-DD. OMIT unless the user asked for a specific period — the default window is cheaper to serve and is the right answer for a general 'how are we doing' question. | |
| lang | No | Restrict to one language code. Must be enabled on the help center. Costs more to serve than the unfiltered call, so only send it for a genuinely multilingual question. | |
| limit | No | Rows per list, 1-50 (default 20). Raising it is free — these read pre-aggregated daily tables — so ask for more when you are building a content plan rather than answering one question. | |
| site_id | No | Which help center to act on: an id from helpcenter_list_sites. Needed when this connection reaches more than one help center; omit it when it reaches one. Applies to this call only — pass it on every call of a task, and ask the user which help center they mean if their request does not say. | |
| response_format | No | Output format: 'markdown' for a human-readable summary or 'json' for the full structured payload. | markdown |