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

# Stats API

> Retrieve analytics and usage data for your Doofinder search engines.

The Stats API provides access to aggregated analytics data for your search engines — search volumes, click-through rates, conversion metrics, facet usage, and more. All data is read-only.

**Version:** v2

## Base URL

```
https://{search_zone}-api.doofinder.com
```

Example: `https://eu1-api.doofinder.com`

## Authentication

```http theme={null}
Authorization: Token ab46030xza33960aac71a10248489b6c26172f07
```

JWT authentication is also supported. See the [Authentication guide](/introduction/authentication).

***

## Common Query Parameters

Most endpoints accept these parameters to define the reporting window:

| Parameter | Type | Description |
| - | - | - |
| `hashid` | string | **Required.** Your search engine's identifier. |
| `from` | string | Start date in `YYYY-MM-DD` format. |
| `to` | string | End date in `YYYY-MM-DD` format. |
| `tz` | string | Timezone for date aggregations (e.g. `Europe/Madrid`). |

***

## Endpoint Groups

<CardGroup cols={2}>
  <Card title="Usage & Sessions" icon="users" href="#usage--sessions">
    Session counts, user activity, geographic breakdowns, and per-engine usage.
  </Card>

  <Card title="Searches" icon="magnifying-glass" href="#searches">
    Search volume, top queries, popular terms, location data.
  </Card>

  <Card title="Clicks & Interactions" icon="arrow-pointer" href="#clicks--interactions">
    Click-through rates, clicked items, position analysis, redirects.
  </Card>

  <Card title="Conversions & Sales" icon="bag-shopping" href="#conversions--sales">
    Checkout and sales data attributed to search sessions.
  </Card>

  <Card title="Features" icon="puzzle-piece" href="#features">
    Banners, facets, custom results, recommendations, quizzes.
  </Card>
</CardGroup>

***

## Usage & Sessions

Track how users are engaging with your search engine over time.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v2/stats/inits` | Total session counts over time |
| `GET` | `/api/v2/stats/inits/locations` | Sessions broken down by geographic location |
| `GET` | `/api/v2/stats/inits/users` | Sessions with identified users |
| `GET` | `/api/v2/stats/usage` | Overall usage metrics |
| `GET` | `/api/v2/stats/search_engine_users` | Per-engine usage by user |

***

## Searches

Understand what your users are searching for.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v2/stats/searches` | Search volume over time |
| `GET` | `/api/v2/stats/searches/top` | Top search queries ranked by volume |
| `GET` | `/api/v2/stats/searches/popular` | Popular searches (trending) |
| `GET` | `/api/v2/stats/searches/locations` | Searches broken down by location |
| `GET` | `/api/v2/stats/results/top` | Most-returned results across searches |

***

## Clicks & Interactions

Measure how users interact with search results.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v2/stats/clicks` | Click volume over time |
| `GET` | `/api/v2/stats/clicks/users` | Clicks attributed to identified users |
| `GET` | `/api/v2/stats/clicked_items` | Items most frequently clicked |
| `GET` | `/api/v2/stats/clicked_items/searches` | Searches that led to clicks on each item |
| `GET` | `/api/v2/stats/clicked_items/position` | Average click position per item |
| `GET` | `/api/v2/stats/redirects` | Redirect rule trigger counts |

***

## Conversions & Sales

Attribute revenue and conversions to search-driven sessions.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v2/stats/checkouts` | Checkout events initiated from search sessions |
| `GET` | `/api/v2/stats/sales` | Sales data |
| `POST` | `/api/v2/stats/sales` | Confirm a sale event |
| `GET` | `/api/v2/stats/top-sales` | Top-selling items attributed to search |
| `POST` | `/api/v2/stats/carts` | Process checkout cart data |

***

## Features

Track usage of specific Doofinder features.

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v2/stats/banners` | Banner impression and click stats |
| `GET` | `/api/v2/stats/facets` | Facet usage — which filters users apply |
| `GET` | `/api/v2/stats/facets_by_day` | Daily facet usage breakdown |
| `GET` | `/api/v2/stats/facets/top` | Top facet values by usage |
| `GET` | `/api/v2/stats/custom-results` | Custom result rule usage |
| `GET` | `/api/v2/stats/recommendations` | Recommendation widget stats |
| `GET` | `/api/v2/stats/quizzes` | Quiz feature stats |
| `GET` | `/api/v2/stats/sector/{name}` | Industry-specific benchmark data |
| `POST` | `/api/v2/stats/visit` | Log a page visit event |

***

## Key Metrics Explained

### Click-Through Rate (CTR)

The ratio of search sessions that result in at least one click. A low CTR on a query suggests results are not relevant.

### Zero Results Rate

The percentage of searches that return no results. Monitor `GET /api/v2/stats/searches` for queries with `total_results: 0`.

### Session Attribution

Doofinder attributes a sale or checkout to a search session if the user clicked a search result and subsequently completed a purchase within the same session window.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.