Doofinder

Lists the excluded results—products hidden from search individually by `dfid`, or by a filter rule—for one search engine. Requires a search-engine hashid; use `account_info` to discover it only when unknown. Call this before concluding that a product is missing for any other reason, and before proposing a new exclusion. Omit `kind` for both kinds, or set it to "item" for individually hidden products and "rule" for filter-based exclusions. Each entry carries the `position` a write has to name; positions shift whenever anything is added, so read them again immediately before writing. `exclusions_enabled` reports whether the engine applies its exclusion list at all: when it is false nothing here is being hidden. `total` is the number of matching entries and `count` is the number returned on this page. Continue with `offset` when `total` is greater than `count`.

list_excluded_results

Lists the redirections configured for one search engine: a matching query sends the shopper straight to a target link instead of returning results. Requires a search-engine hashid; use `account_info` to discover it only when unknown. Use this tool before treating a no-results query as a relevance problem — it may be redirected away instead. `automatic` fires as soon as the term is typed; otherwise the redirection's own term configuration decides exact or partial matching. Disabled redirections are included when `enabled` is omitted. `total` is the number of matching redirections and `count` is the number returned on this page; continue with `offset` when necessary.

list_redirections

Lists synonyms configured for one search engine. Requires a search-engine hashid; use `account_info` to discover it only when unknown. Use this tool to check whether terms are already connected before diagnosing a no-results query or proposing another synonym. `equivalent` synonyms are interchangeable in both directions; `one_way` synonyms replace only `from` terms with `to` terms. The original stored rule is returned as `expression`. Disabled synonyms are included when `enabled` is omitted. `total` is the number of matching synonyms and `count` is the number returned on this page; continue with `offset` when necessary.

list_synonyms

Scoped to the authenticated account: pass the search engine `hashid`, which is what the `identifier` argument described below is built from. The store-level identifiers, and the product surfaces that need one, are not available here. Reads a metric series for one store or search engine, one point per date: what a period aggregate cannot answer - trends, regressions, seasonality, when something started, before-and-after around a change. Requires an `identifier` (a search engine `hashid`/`hashids`, or a store `store_id`/`stores_id`) and an inclusive `from`/`to` range of at most 90 days, a ClickHouse memory limit, so split a longer window across calls rather than widening one. `bucket` is DAY (default), WEEK or MONTH; a weekly or monthly rate is read over that bucket's own window, not averaged from the daily points, and every non-daily row carries `days` because the first and last bucket are usually partial. A non-daily count is the sum of its days, which for `sessions` counts a session that crossed midnight in both of them - so a WEEK/MONTH `sessions` runs slightly above the distinct sessions the `metrics` tool reports for the same window, while the rates on that row match it exactly. One call returns at most 90 rows and 6 metrics, so the payload is bounded without a separate limit. This catalogue is narrower than the `metrics` tool's: there is no daily clicks, inits, checkouts, no-results, abandonment or average-click-position series. `products` takes one surface or a list of them, and the response carries one block per surface; read its own description before comparing figures across blocks, because LEAVING `products` OUT IS NOT THE SAME AS `ALL` - it reads the store's whole traffic, Doofinder or not, while `ALL` reads only sessions that touched some Doofinder surface. IMPORTANT semantics you cannot infer from the numbers: `searches` is always store-wide, `products` does not reach it, so it is identical in every block. `sales` is revenue, and `products: SEARCH` sales means "purchased in a session that used Doofinder", NOT "purchased because of a search" - it is not attribution. `displays` requires a `products` and counts only carousels that actually rendered. A rate's denominator is another metric in this list, so request it alongside to judge whether a move is real: `ctr` divides by `searches` (no filter, SEARCH or ALL), by `displays` (RECOMMENDATION or CATEGORY_PAGE) or by chat sessions (AICHAT); `cr` divides by `sessions(products: SEARCH)`, by `displays` or by chat sessions the same way. `products: AICHAT` and `products: ALL` need a singular `store_id`, because the chat tables are scoped by a chat id no other identifier resolves. A 0 means no events that day, not "not measured". Returns raw numbers only, no verdicts - the analysis is yours.

time_series

Scoped to the authenticated account: pass the search engine `hashid`, which is what the `identifier` argument described below is built from. The store-level identifiers, and the product surfaces that need one, are not available here. Reads period aggregates for one store or search engine: how it did over a date range. Ask for several metrics in one call via `metrics`; every rate comes back next to the counts that produce it, so a CTR or CR can be judged against its volume. Returns raw numbers only, no verdicts — the analysis is yours. ## Arguments - `identifier` (required) — a search engine `hashid`/`hashids`, or a store `store_id`/`stores_id`. - `from`/`to` (required) — an inclusive range of at most 90 days. A wider window costs too much to answer in one call, so split a longer range across calls rather than widening one. - `products: AICHAT` and `products: ALL` need a singular `store_id` specifically: the AI-chat numbers can only be narrowed to one store from a store id, and with any other identifier they would cover every store rather than this one. ## What `products` does, and does not, reach Not every metric respects it: `searches`, `inits`, and `no_results` stay store-wide regardless, `abandonment` always uses its own search formula, and `checkouts` drops its `previous_script` count. See which do in the `metrics` list. **IMPORTANT** — where it does apply, `products` resolves two different ways, and the difference changes what the number means: - For clicks and the CTR dividing them, it filters events whose product type is that surface. - For sales and sessions, it filters whole sessions that touched that surface at any point, by whichever signal the surface uses: an init for SEARCH, a click for RECOMMENDATION, a conversation for AICHAT, a display for CATEGORY_PAGE, any of them for ALL. So `products: SEARCH` sessions means "a session that opened the search layer", NOT "a session driven by a search", and `products: SEARCH` sales means "purchased in a session that opened the search layer", NOT "purchased because of a search" — it is not attribution. ## Why `checkouts` returns two counts Purchases are recorded once per generation of the store's installed script — the Single Script, and the previous script it replaced — and neither record is a superset of the other. `single_script` misses stores that have not migrated yet; `previous_script` misses sessions whose client-side flag claimed the layer never opened, which is not a reliable flag. So the two are reported separately rather than as one total that would be wrong for some stores. `cr` already accounts for both. `sales` does not: revenue is only recorded by the Single Script, so a store still on the previous one reports `sales.amount: 0` while `checkouts.previous_script` is well above zero. Read the two together before concluding a store sells nothing.

metrics

Scoped to the authenticated account: pass the search engine `hashid`, which is what the `identifier` argument described below is built from. The store-level identifiers, and the product surfaces that need one, are not available here. Reads one row per product for a store or search engine: which products people click in search results, and what those sessions went on to do. Requires an `identifier` (a search engine `hashid`/`hashids`, or a store `store_id`/`stores_id`) and an inclusive `from`/`to` range of at most 90 days — this is a hard API limit, so split a longer window across calls rather than widening one. Returns raw per-product numbers only, no verdicts and no filtering: every product in the pool comes back, whatever its volume, and deciding which ones are a problem is yours. Products are identified by `dfid`, structured `hashid@index@id_hash` — the same format carried by visit and cart events, so the agent can join click behaviour to purchase behaviour itself. IMPORTANT, five things the numbers do not say on their own. 1. The two halves of a row do not count the same clicks. `clicks`, `ctr` and `average_click_position` count only clicks correlated to a real search in the same session, while `revenue`, `checkouts` and `cr` count sessions that clicked the product ANYWHERE — recommendations, category pages, quizzes and AI chat included — so the commercial columns can rest on clicks the engagement columns never counted. 2. The pool is capped. The engagement columns cover the top 1000 products by clicks and the commercial ones only the top 50 by revenue or checkouts, so `sort` orders that pool rather than every product that exists — read `truncated` and `sales_columns_cover` before calling an answer complete. 3. A commercial column is null, not zero, for a product outside those 50. Null means not covered, and reading it as no sales is wrong. 4. `revenue` is attributed to every product a converting session clicked, at its full session value, so it overcounts across products by design — do not sum it into a store total. It is 0 for a session that checked out without a recorded cart. 5. `cr` and `checkouts` count checkout sessions from both checkout tables unioned, so no population is missing there, but `device` narrows the clicks only and not the checkout side. `product_page_visits` is neither device-filtered nor deduplicated by session, and is null rather than 0 across every row for a window with no visit tracking recorded at all. Use `query_terms` for the same shape per search term.

items

Reads the search security configuration of one of the account's stores: the IP ranges blocked from the search endpoint, the origins allowed to query it, and whether CORS is enabled for search. PREREQUISITE: call account_info first to get a store id — this is store-level configuration and applies to every search engine the store owns, so it takes no hashid. Use it before add_blocked_ips or remove_blocked_ips to see what is already blocked. The origins and the CORS flag are read-only here: no tool changes them, they are changed in the admin panel.

read_security_settings

Stops blocking specific IP ranges on a store's search endpoint. This LOOSENS the store's protection: the traffic from those ranges reaches search again. PREREQUISITE: call account_info for the store id, and read_security_settings for the entries as they are stored. Remove only the entries the user asked you to unblock, one by one, exactly as read_security_settings reports them. Do NOT remove entries because they look stale, redundant, expired or too numerous — you cannot tell why a range was blocked, and there is no undo here beyond adding it back. There is no way to clear the list. Entries that are not blocked are reported back rather than treated as an error. The response echoes exactly what was removed and returns the full resulting list.

remove_blocked_ips

Stops hiding one excluded result, so the product or the products a rule matched can appear in search again. Call `list_excluded_results` immediately before this and pass both the `position` it reported and, as `expect`, the entry that was at it: positions shift whenever an exclusion is added, and the write is refused rather than applied to a different entry. Destructive: the entry is gone, though the response echoes it so it can be re-created. No reindex is needed — the next search reflects it.

remove_excluded_result

Runs a read-only search preview against one search engine and returns the results a shopper would see, including facets and totals. Requires a search-engine hashid; use `account_info` to discover it only when unknown. Use this tool to reproduce a query, inspect filters, sorting, and facets, or verify business-rule behavior. `total` is the number of matches across all pages; `count` is the number returned on this page. Results are condensed by default; set `full_results` to true only when raw document fields are needed. Preview calls do not record analytics.

search

Scoped to the authenticated account: pass the search engine `hashid`, which is what the `identifier` argument described below is built from. The store-level identifiers, and the product surfaces that need one, are not available here. Reads one row per search term for a store or search engine: what people typed, and how each term did. Requires an `identifier` (a search engine `hashid`/`hashids`, or a store `store_id`/`stores_id`) and an inclusive `from`/`to` range of at most 90 days — that ceiling is a ClickHouse memory limit, so split a longer window across calls rather than widening one. Returns raw per-term numbers only, no verdicts and no filtering: every term in the pool comes back, whatever its volume, and deciding which ones are a problem is yours. Every rate ships next to its operands, so a CTR or an exit rate can be judged against the volume behind it. IMPORTANT, three things the numbers do not say on their own. First, the pool is capped: the engagement columns cover the top 1000 terms by search volume and the commercial ones only the top 50 by revenue, checkouts or exits, so `sort` orders that pool rather than every term that exists — read `truncated` and `sales_columns_cover` before calling an answer complete. Second, a commercial column is null, not zero, for a term outside those 50: null means not covered, and reading it as no sales is wrong. Third, `revenue` is attributed to sessions that SEARCHED the term, not to sessions that bought because of it, and a session that searched several terms contributes its full revenue to each of them — it overcounts across terms by design, so do not sum it into a store total.

query_terms

Sets a redirection's active state to the supplied `enabled` value; it never infers or flips the current state. PREREQUISITE: call list_redirections for the id and current state, and account_info for the hashid. IMPORTANT: enabling a redirection can silently disable every enabled redirection with a matching term. Warn the merchant before enabling a colliding rule, then inspect `disabled_redirections` and call list_redirections to read the resulting configuration. This only changes the active state; it leaves the redirection's name, link, automatic setting, and terms unchanged.

toggle_redirection

Rewrites one excluded result in place, keeping its position — use it to narrow or widen an existing rule rather than removing and re-adding it. Call `list_excluded_results` immediately before this and pass both the `position` it reported and, as `expect`, the entry that was at it: positions shift whenever an exclusion is added, and the write is refused rather than applied to a different entry. `replacement` replaces the entry outright, so include every condition or field it should still have; it may also turn an individual exclusion into a rule or the other way round. Destructive: the previous version is gone. No reindex is needed — the next search reflects it.

update_excluded_result

Switches whether a search engine applies its excluded-results list at all. When this is off, every entry from exclude_item, exclude_by_rule, and list_excluded_results is saved but hides nothing — this is the tool that fixes that. Call list_excluded_results first to see what is configured, since turning this on can immediately hide products that were quietly excluded while it was off.

update_excluded_results_settings

Updates one redirection on a search engine. PREREQUISITE: call list_redirections for the id and current values, and account_info for the hashid. Send only the fields that should change; omitted fields are preserved. When sending `terms`, send the complete replacement list, not only terms to add. IMPORTANT: updating a redirection silently disables every enabled redirection with a matching term. Warn the merchant before an update that would collide, then inspect `disabled_redirections` and call list_redirections to read the resulting configuration. Each term has a `value`; set `exact_match` true only when the query must exactly match that term. Send `automatic` to change whether the redirect fires while a shopper types, and `enabled` to change whether it is active.

update_redirection

Rewrites one synonym on one of the account's search engines, switches it on or off, or both. PREREQUISITE: call list_synonyms to get the id, and account_info for the hashid. EXPENSIVE: this schedules a full reindex of the search engine, so make the whole change in one call. To rewrite the rule, send "type" and its term lists: this REPLACES the rule, so send every term the synonym should end up with, not just the ones you are adding, using the same "type"/"terms"/"from"/"to" shape list_synonyms reports. To only switch a synonym on or off — for instance to check whether an existing synonym is what is polluting a query's results — send "enabled" and omit the rule fields entirely: the terms are then left exactly as they are, and you do not have to know them. The response reports the stored rule and that a reindex was requested: results will not reflect the change until it completes.

update_synonym