> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cludo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Answers to common questions about Cludo API authentication, rate limits, regions, v3 vs v4 endpoints, indexing, and AI search features.

<AccordionGroup>
  <Accordion title="What is the difference between v3 and v4?">
    **v4 is the recommended API version for new search, AI, and index-management integrations.**

    | API Area              | Version                  |
    | --------------------- | ------------------------ |
    | Search & Autocomplete | v3 or v4 (both work)     |
    | AI Chat & AI Summary  | v4 only                  |
    | Index Management      | v4 only                  |
    | Tracking              | v3 only                  |
    | Search Tools          | Unversioned (`/api/...`) |

    The main migration work is Index Management: v3 Content Management uses `/content/{crawlerId}/...`, while v4 uses `/index/{crawlerId}/documents`. If you use PushURLs, the v4 equivalent is `POST /api/v4/{customerId}/crawler/{crawlerId}/paths`.

    See [API Versions: v3 vs v4](/guides/migration-v3-to-v4) for details. For the full v3 API reference, see the [legacy documentation](https://docs.cludo.com/).
  </Accordion>
</AccordionGroup>

***

## Architecture

<AccordionGroup>
  <Accordion title="How do the Crawler, Content API, Engine, and Analytics relate to each other?">
    | Component       | Role                                                                                                                                                              |
    | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Engine**      | Holds your search index. Every API call references a `customerId` and `engineId`.                                                                                 |
    | **Crawler**     | Fetches and indexes your website on a schedule. Optional if you push all content via the Content API.                                                             |
    | **Content API** | Lets you push, update, or delete documents directly — no crawling needed. Requires a `crawlerId` as an index container even if the crawler never actively crawls. |
    | **Analytics**   | Populated by tracking events sent from your frontend. Requires the analytics script or manual API calls — events are not sent automatically.                      |

    A Crawler and the Content API can coexist on the same engine. If you use both, be aware that a scheduled crawl can overwrite pushed content on the same URLs. If you push all content via API, disable scheduled crawling in MyCludo.
  </Accordion>
</AccordionGroup>

***

## Search

<AccordionGroup>
  <Accordion title="How do I filter search results?">
    Use the `filters` parameter to include only results with matching field values:

    ```json theme={null}
    {
      "query": "*",
      "filters": {
        "Category": ["Guides", "Tutorials"]
      }
    }
    ```

    You can filter on standard fields and custom crawler fields, as long as the field is available in your index and configured for filtering where required. Field names are case-sensitive, so use the exact field name from your crawler or pushed document configuration.

    To exclude values, use `notFilters`. To build filter UI counts, enable facets on the relevant fields and send `enableFacetFiltering: true`.

    See the [Search API reference](/api-reference/v4/search/search) for request parameters.
  </Accordion>

  <Accordion title="What is AI Search?">
    AI Search combines keyword matching with semantic matching to improve relevance for natural-language queries. It is available when AI Search is enabled for your engine. Your search request can stay the same; Cludo handles how keyword and semantic matches are combined.
  </Accordion>

  <Accordion title="How do I track search queries for analytics?">
    Use the [Cludo API analytics script](https://help.cludo.com/analytics/) or send tracking events through the API. Query tracking uses `POST /api/v3/{customerId}/{engineId}/search/pushstat/querylog`, and click tracking uses `POST /api/v3/{customerId}/{engineId}/search/pushstat/clicklog`.

    Send both query and click events so analytics can connect searches to clicked results. See the [legacy API documentation](https://docs.cludo.com/) for the full v3 tracking reference.
  </Accordion>

  <Accordion title="How do I sort search results?">
    Use the `sort` parameter to order results by a field, including custom crawler fields that are configured for sorting. Sorting is commonly used for dates, titles, numeric fields, and custom metadata such as product price or content type.
  </Accordion>

  <Accordion title="Why do search results differ from what I see on my website?">
    Search only returns content that has been indexed. A page may be missing from the index for several reasons:

    * The crawler is blocked.
    * The page is excluded by crawler rules.
    * The content is rendered in a way the crawler cannot pick up.
    * The page has not been crawled since it changed.

    See [Troubleshooting → Content indexing issues](/troubleshooting#content-indexing-issues).
  </Accordion>

  <Accordion title="How are facet counts calculated?">
    Facet counts are calculated server-side across all matching documents, not just the current page. They reflect how many documents in the full result set match each facet value — independent of `page` and `perPage`.

    To use facets, the relevant fields must be enabled for faceting. Contact [support@cludo.com](mailto:support@cludo.com) with your engine ID and field names, then include `enableFacetFiltering: true` in your search request.
  </Accordion>
</AccordionGroup>

***

## AI Chat & AI Summary

<AccordionGroup>
  <Accordion title="What is the difference between AI Chat and AI Summary?">
    * **AI Chat** generates a conversational answer to a question, grounded in your search index. Supports multi-turn conversations.
    * **AI Summary** summarizes a set of search result documents. You provide the search results, and it returns a synthesized summary.

    Both support streaming and non-streaming modes.
  </Accordion>

  <Accordion title="How do I enable AI Chat for my engine?">
    AI Chat requires the `AiChat` feature flag to be enabled on your engine. Contact [support@cludo.com](mailto:support@cludo.com) or check your engine settings in [MyCludo](https://my.cludo.com).
  </Accordion>

  <Accordion title="What does generativeAnswerAvailable mean?">
    This boolean field in the search response indicates whether AI has enough signal to attempt an answer for the query. If `true`, you can call the [AI Chat](/api-reference/v4/ai/chat) endpoint for an answer grounded in your indexed content.

    Treat `true` as a hint, not a guarantee — the AI streaming endpoint may still return an error (such as a 502) if the model is temporarily unavailable. Always implement a fallback that hides the AI panel gracefully rather than surfacing a raw error to the user.

    If the value is `false`, the query may be too broad, the matching indexed content may not contain enough answerable text, or the relevant website content may not be indexed because of crawler configuration or crawlability issues.
  </Accordion>

  <Accordion title="Can I customize AI Summary output?">
    AI Summary is generated from the documents you provide in the request. To influence the result, choose the search results or documents you pass to the summary endpoint carefully and make sure each document includes useful title, URL, and text fields.

    See the [AI Summary API reference](/api-reference/v4/ai/summary).
  </Accordion>
</AccordionGroup>

***

## Content management

<AccordionGroup>
  <Accordion title="Should I use v3 Content Management or v4 Index Management?">
    Use **v4 Index Management** for document replacement, partial updates, and deletion. It supports partial updates (PATCH), advanced bulk-delete filters, and uses your **crawler id** in paths such as `/index/{crawlerId}/documents`. See [Index Management](/api-reference/v4/content/index-management).

    If your v3 integration uses PushURLs to queue pages for crawling, use `POST /api/v4/{customerId}/crawler/{crawlerId}/paths` in v4.

    See [API Versions: v3 vs v4](/guides/migration-v3-to-v4) for version guidance. For the full v3 API reference, see the [legacy documentation](https://docs.cludo.com/).
  </Accordion>

  <Accordion title="My pushed documents don't appear in search. Why?">
    Check these common issues:

    1. **Wrong crawler id:** v4 document APIs use `/index/{crawlerId}/documents` — use the crawler id from MyCludo (same id as in v3 `/content/{crawlerId}` flows).
    2. **Missing useful fields:** Ensure each document has an `id` and meaningful fields such as `Title`, `Url`, and `Description`.
    3. **Give it time:** Documents may take a few seconds to become searchable.
    4. **Check your region:** EU credentials don't work against the US endpoint.
    5. **Validate crawled URLs:** For website content, use the crawler URL test in MyCludo to verify that the crawler can fetch and index the page.

    See [Troubleshooting → Content Indexing](/troubleshooting#content-indexing-issues).
  </Accordion>

  <Accordion title="Do I need a crawler if I push all content via API?">
    You still need a **crawler entity** in MyCludo, but it does not need to actively crawl anything. The `crawlerId` in Content API paths (`/index/{crawlerId}/documents`) is an index container identifier, not a requirement to run crawls.

    Create a crawler in MyCludo, then disable scheduled crawling so it never runs automatically. If you leave scheduled crawling on, the crawler may overwrite or remove documents you pushed via the API.
  </Accordion>
</AccordionGroup>

***

## Analytics

<AccordionGroup>
  <Accordion title="What is the difference between Unique and Total searches?">
    * **Total searches** counts every search event received, including repeated searches from the same user in the same session.
    * **Unique searches** counts only the first search for a given query within a session.

    If your popular searches all show the same low count, it usually means each search is being tracked as a separate unique event — often caused by missing or inconsistent session identifiers in the tracking payload.
  </Accordion>

  <Accordion title="My analytics show no data. What should I check?">
    1. **Analytics events:** If you built a custom search UI, you must send tracking events manually or install the [Cludo analytics script](https://help.cludo.com/analytics/). Events are not sent automatically.
    2. **Both event types:** Send both query events (`querylog`) and click events (`clicklog`). Missing one means analytics will be incomplete.
  </Accordion>
</AccordionGroup>

***

## Still have questions?

Email [support@cludo.com](mailto:support@cludo.com) with your customer ID, engine ID, and a description of your issue.