> ## 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. # Search engine usage > Gets how many visits a Search engine receive and from that users how many inits & searches in a time period ## OpenAPI ````yaml /openapi/stats-v2.yaml get /api/v2/stats/search_engine_users openapi: 3.0.0 info: contact: name: Doofinder Support url: https://docs.doofinder.com/ description: > # Introduction Doofinder Stats API provides statistical information about your search engines. # Basics ## Endpoint All requests should be done via `https` to the right endpoint: ``` https://{search-zone}-api.doofinder.com ``` Where `{search-zone}` is the code of the datacenter where your search engines are located. For instance: ``` https://eu1-api.doofinder.com https://us1-api.doofinder.com ``` ## Authentication To authenticate you need a Doofinder API key. If you don't have one you can generate it in the Doofinder Admin by going to your Account and then to API Keys, [here](https://admin.doofinder.com/admin/account/api). A valid API key looks like this: ``` ab46030xza33960aac71a10248489b6c26172f07 ``` ### API Token You can authenticate with the previous API key. The correct way to authenticate is to send a HTTP Header with the name `Authorization` and the value `Token {api-key}`. I.e.: ``` Authorization: Token ab46030xza33960aac71a10248489b6c26172f07 ``` ### JWT Token If you prefer you can authenticate with a [JSON Web Token](https://jwt.io). The token must be signed with an API management key and there are some claims required in the JWT payload. These claims are: * `iat` (issued at): Creation datetime timestamp, i.e. the moment when the JWT was created. * `exp` (expiration time): Expiration datetime timestamp, i.e. the moment when the JWT is going to expire and will no longer be valid. The time span between issued and expiration dates must be shorter than a week. * `name`: Your user code. It is your unique identifier as doofinder user. You can find this code in your profile page in the Doofinder's administration panel. To authenticate using JWT you must send a HTTP header with the name `Authorization` and the value `Bearer {JWT-token}`. I.e.: ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoidGVzdCIsImlhdCI6MTUxNjIzOTAyMn0.QX_3HF-T2-vlvzGDbAzZyc1Cd-J9qROSes3bxlgB4uk ``` ## Conventions Along most of the code samples you will find placeholders for some common variable values. They are: * `{hashid}`: The search engine's unique id. e.g.: d8fdeab7fce96a19d3fc7b0ca7a1e98b. * `{index}`: When storing items, they're always stored under a certain _index_. e.g.: product. * `{token}`: Your personal authentication token obtained in the control panel. ## Api limits ### Requests rate The API has a limit of 20 requests per second. If you do more than that, the next requests will get a `429 Too Many Requests` error. There is no penalty associated to that error, but you must wait one second before attempting more requests. ### Body size The body size for requests with data sending (eg: POST or PUT requests) has a limit of 8MB. If you do a request with a request body bigger than 8 MB, the response will be `413 Payload Too Large`. This is important mostly for batch calls like batch create items. # Objects ## Search Engines A search engine is a collection of indices where data is stored. It has some properties like name, language, and some other configuration options that are shared among all of its indices. Each search engine is uniquely identified by its `hashid` which is an auto-generated string. Search engines have a _"process"_ operation which takes items from all its data sources and insert them into their indices. This operation has a zero downtime, you can still search into indices while processing. termsOfService: https://www.doofinder.com/en/terms-and-conditions title: Doofinder Stats API version: '2.0' x-logo: altText: Doofinder Search Engine backgroundColor: '#33268C' url: https://admin.doofinder.com/images/logo.svg servers: - url: https://{search_zone}-api.doofinder.com variables: search_zone: default: eu1 enum: - eu1 - us1 - ap1 - url: / security: - api_token: [] - jwt_token: [] tags: - description: Session and usage statistics for your search engines. name: Usage & Sessions - description: Search activity and top search statistics. name: Searches - description: Click events and user interaction statistics. name: Clicks & Interactions - description: Sales, checkout, and conversion statistics. name: Conversions & Sales - description: Feature-specific statistics including banners, facets, quizzes, and more. name: Features - description: Visit event registration. name: Visits - description: Internal usage metrics. name: Internal paths: /api/v2/stats/search_engine_users: get: tags: - Usage & Sessions summary: Search engine usage description: >- Gets how many visits a Search engine receive and from that users how many inits & searches in a time period operationId: searchEngineUsersStats parameters: - $ref: '#/components/parameters/from' - $ref: '#/components/parameters/to' - $ref: '#/components/parameters/stats_hashids' - $ref: '#/components/parameters/stats_hashid' - $ref: '#/components/parameters/tz' - $ref: '#/components/parameters/format' - $ref: '#/components/parameters/aggregate' - $ref: '#/components/parameters/device' responses: '200': content: application/json: schema: $ref: '#/components/schemas/SearchEngineUsageResult' description: Stats retrieved. '400': $ref: '#/components/responses/StatsBadRequest' '401': $ref: '#/components/responses/StatsUnauthorized' '403': $ref: '#/components/responses/StatsForbidden' '404': $ref: '#/components/responses/StatsNotFound' '408': $ref: '#/components/responses/StatsTimeout' '429': $ref: '#/components/responses/StatsTooManyRequests' components: parameters: from: description: Start date of the period in the format of UNIX timestamp or YYYYMMDD. in: query name: from required: true schema: pattern: ^20\d{2}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$|^\d{10}|^\d{13}$ type: string to: description: End date of the period in the format of UNIX timestamp or YYYYMMDD. in: query name: to required: true schema: pattern: ^20\d{2}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$|^\d{10}$|^\d{13} type: string stats_hashids: description: >- Unique id of the search engine. It accepts an array of values. If you want to work with all user search engines just don't send this parameter. Arrays parameters must be in the format `param[]=value`. in: query name: hashids schema: items: pattern: ^[a-f0-9]{32}$ type: string type: array stats_hashid: deprecated: true in: query name: hashid schema: items: pattern: ^[a-f0-9]{32}$ type: string type: array tz: description: > The timezone for the given dates, by default, assumes ETC/UTC. In naming your time zones, you must stick to those indicated in the TZ database name column [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) example: Europe/Madrid in: query name: tz schema: default: Etc/UTC type: string format: description: Indicates which response format should be used in: query name: format schema: default: json enum: - json - csv type: string aggregate: description: Flag to indicate when to aggregate all Search Engines stats data. in: query name: aggregate required: false schema: default: true type: boolean device: description: Filter by kind of device. in: query name: device schema: enum: - desktop - mobile type: string schemas: SearchEngineUsageResult: description: Stats for user behaviour for a search engine. example: results: - inits: 2000 searches: 8000 visits: 3000 total: 0 total_count: 0 properties: results: items: properties: inits: description: >- How many times the layer has been loaded (unique clicks on search bar) example: 2000 type: integer searches: description: Total of searches done example: 8000 type: integer visits: description: How many visits a store has received example: 3000 type: number type: object type: array total: description: Always 0. example: 0 type: integer total_count: description: Always 0. example: 0 type: integer title: Search engine user stats type: object StatsError: description: Standard error wrapper for all Stats API error responses. properties: error: properties: code: description: Machine-readable error code. example: not_authenticated type: string message: description: Human-readable error description. example: Authentication required type: string required: - code type: object required: - error type: object responses: StatsBadRequest: content: application/json: example: error: code: bad_params message: Bad parameters error schema: $ref: '#/components/schemas/StatsError' description: Bad Request — invalid or missing query parameters. StatsUnauthorized: content: application/json: example: error: code: not_authenticated message: Authentication required schema: $ref: '#/components/schemas/StatsError' description: Unauthorized — no valid API token provided. StatsForbidden: content: application/json: example: error: code: access_denied message: Access denied schema: $ref: '#/components/schemas/StatsError' description: >- Forbidden — token is valid but does not have access to this search engine. StatsNotFound: content: application/json: example: error: code: not_found message: Not found schema: $ref: '#/components/schemas/StatsError' description: Not Found — the requested search engine or resource does not exist. StatsTimeout: content: application/json: example: error: code: timeout message: Request timed out schema: $ref: '#/components/schemas/StatsError' description: >- Request Timeout — the stats backend took too long; retry after a short delay. StatsTooManyRequests: content: application/json: example: error: code: too_many_requests message: Too many requests schema: $ref: '#/components/schemas/StatsError' description: Too Many Requests — rate limit exceeded; back off and retry. securitySchemes: api_token: description: | Doofinder API key. Pass it as: Authorization: Token in: header name: Authorization type: apiKey jwt_token: description: | JWT Bearer token. Sign a JWT with your API key (HS256) and pass it as: Authorization: Bearer in: header name: Authorization type: apiKey ````