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

# Retrieve top search results

> Retrieves the object IDs of the 1,000 most frequent search results.

If you set the `clickAnalytics` query parameter to `true`, the response also includes:

* Tracked searches count.
  Tracked searches are Search API requests with `clickAnalytics` set to `true`.
  This differs from the response's `count`, which includes searches where `clickAnalytics` is `false`.
* Click count
* Click-through rate (CTR)
* Conversion count
* Conversion rate (CR)
* Average click position

If you set the `revenueAnalytics` parameter to `true`, the response also includes:

* Add-to-cart count
* Add-to-cart rate (ATCR)
* Purchase count
* Purchase rate
* Revenue details for each currency

**There's a difference between 0% rates and null rates:**

* **Null** means there were no queries. Algolia didn't receive any events, so rates are null.
* **0% rates** mean there were queries but no [click or conversion events](https://www.algolia.com/doc/guides/sending-events/getting-started) were received.

**Required ACL:** `analytics`


## OpenAPI

````yaml specs/searchstats.yml get /2/hits
openapi: 3.1.0
info:
  title: Analytics API
  summary: >-
    The Analytics API gives you access to metrics related to your Algolia search
    experience
  description: >
    ## Base URLs


    Base URLs for the Analytics API:


    - `https://analytics.us.algolia.com`

    - `https://analytics.de.algolia.com`

    - `https://analytics.algolia.com` (alias of `analytics.us.algolia.com`)


    Use the URL that matches your [analytics
    region](https://dashboard.algolia.com/account/infrastructure/analytics).


    **All requests must use HTTPS.**


    ## Availability and authentication


    Access to the Analytics API is available as part of the [Premium or Elevate
    plans](https://www.algolia.com/pricing).


    Add these headers to authenticate requests:


    - `x-algolia-application-id`. Your Algolia application ID.

    - `x-algolia-api-key`. An API key with the necessary permissions to make the
    request.
      The required access control list (ACL) to make a request is listed in each endpoint's reference.

    You can find your application ID and API key in the [Algolia
    dashboard](https://dashboard.algolia.com/account/api-keys).


    ## Rate limits


    You can make up to **100 requests per minute per app** to the Analytics API.

    The response includes headers with information about the limits.


    ## Parameters


    Query parameters must be
    [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).

    Non-ASCII characters must be UTF-8 encoded.

    Plus characters (`+`) are interpreted as spaces.


    ## Response status and errors


    The Analytics API returns JSON responses.

    Since JSON doesn't guarantee any specific ordering, don't rely on the order
    of attributes in the API response.


    - Successful responses return a `2xx` status

    - Client errors return a `4xx` status

    - Server errors are indicated by a `5xx` status.


    Error responses have a `message` property with more information.


    ## Version


    The current version of the Analytics API is version 2, indicated by the
    `/2/` in each endpoint's URL.


    ## Query aggregation


    Algolia accepts queries on each keystroke.

    To ensure you have relevant analytics data, however, the series of
    keystrokes is aggregated to keep only the latest (final) user query.

    This is called "prefix" aggregation.


    For more information, see [Query agggregation and
    processing](https://www.algolia.com/doc/guides/search-analytics/concepts/query-aggregation).


    See the analytics implementation overview for more information about query
    aggregation.
  version: 2.0.0
servers:
  - url: https://analytics.{region}.algolia.com
    variables:
      region:
        description: The region where your Algolia application is hosted.
        enum:
          - us
          - de
        default: us
  - url: https://analytics.algolia.com
security:
  - appId: []
    apiKey: []
tags:
  - name: click
    x-displayName: Clicks
    description: |
      Metrics related to click and conversion events,
      such as click and conversion rates for your search results.
  - name: filter
    x-displayName: Filters
    description: |
      Metrics related to filters.
  - name: revenue
    x-displayName: Revenue
    description: |
      Metrics related to revenue.
  - name: search
    x-displayName: Searches
    description: |
      Metrics related to searches and search results,
      such as the no-results rate or the most frequent search queries.
  - name: status
    x-displayName: Status
    description: Check the status of the Analytics API.
  - name: user
    x-displayName: Users
    description: Metrics related to the users of your search.
externalDocs:
  url: https://www.algolia.com/doc/guides/search-analytics/overview
  description: Search analytics.
paths:
  /2/hits:
    get:
      tags:
        - search
      summary: Retrieve top search results
      description: >
        Retrieves the object IDs of the 1,000 most frequent search results.


        If you set the `clickAnalytics` query parameter to `true`, the response
        also includes:


        - Tracked searches count.
          Tracked searches are Search API requests with `clickAnalytics` set to `true`.
          This differs from the response's `count`, which includes searches where `clickAnalytics` is `false`.
        - Click count

        - Click-through rate (CTR)

        - Conversion count

        - Conversion rate (CR)

        - Average click position


        If you set the `revenueAnalytics` parameter to `true`, the response also
        includes:


        - Add-to-cart count

        - Add-to-cart rate (ATCR)

        - Purchase count

        - Purchase rate

        - Revenue details for each currency


        **There's a difference between 0% rates and null rates:**


        - **Null** means there were no queries. Algolia didn't receive any
        events, so rates are null.

        - **0% rates** mean there were queries but no [click or conversion
        events](https://www.algolia.com/doc/guides/sending-events/getting-started)
        were received.
      operationId: getTopHits
      parameters:
        - $ref: '#/components/parameters/Index'
        - $ref: '#/components/parameters/ClickAnalytics'
        - $ref: '#/components/parameters/EndDate'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/RevenueAnalytics'
        - $ref: '#/components/parameters/Search'
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/Tags'
      responses:
        '200':
          description: OK
          headers:
            x-ratelimit-limit:
              $ref: '#/components/headers/x-ratelimit-limit'
            x-ratelimit-remaining:
              $ref: '#/components/headers/x-ratelimit-remaining'
            x-ratelimit-reset:
              $ref: '#/components/headers/x-ratelimit-reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getTopHitsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '402':
          $ref: '#/components/responses/FeatureNotEnabled'
        '403':
          $ref: '#/components/responses/MethodNotAllowed'
        '404':
          $ref: '#/components/responses/IndexNotFound'
      x-codeSamples:
        - lang: csharp
          label: C#
          source: |-
            // Initialize the client
            var client = new AnalyticsClient(
              new AnalyticsConfig("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION")
            );

            // Call the API
            var response = await client.GetTopHitsAsync("index");

            // print the response
            Console.WriteLine(response);
        - lang: go
          label: Go
          source: >-
            // Initialize the client with your application region, eg.
            analytics.ALGOLIA_APPLICATION_REGION

            client, err := analytics.NewClient("ALGOLIA_APPLICATION_ID",
            "ALGOLIA_API_KEY", analytics.US)

            if err != nil {
              // The client can fail to initialize if you pass an invalid parameter.
              panic(err)
            }


            // Call the API

            response, err := client.GetTopHits(client.NewApiGetTopHitsRequest(
              "index"))
            if err != nil {
              // handle the eventual error
              panic(err)
            }



            // print the response

            print(response)
        - lang: java
          label: Java
          source: >-
            // Initialize the client

            AnalyticsClient client = new
            AnalyticsClient("ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY",
            "ALGOLIA_APPLICATION_REGION");


            // Call the API

            GetTopHitsResponse response = client.getTopHits("index");


            // print the response

            System.out.println(response);
        - lang: javascript
          label: JavaScript
          source: >-
            // Initialize the client

            // Replace 'us' with your Algolia Application Region

            const client = algoliasearch('ALGOLIA_APPLICATION_ID',
            'ALGOLIA_API_KEY').initAnalytics({ region: 'us' });


            // Call the API

            const response = await client.getTopHits({ index: 'index' });



            // print the response

            console.log(response);
        - lang: kotlin
          label: Kotlin
          source: |-
            // Initialize the client
            val client =
              AnalyticsClient(
                appId = "ALGOLIA_APPLICATION_ID",
                apiKey = "ALGOLIA_API_KEY",
                region = "ALGOLIA_APPLICATION_REGION",
              )

            // Call the API
            var response = client.getTopHits(index = "index")


            // print the response
            println(response)
        - lang: php
          label: PHP
          source: >-
            // Initialize the client

            $client = AnalyticsClient::create('ALGOLIA_APPLICATION_ID',
            'ALGOLIA_API_KEY', 'ALGOLIA_APPLICATION_REGION');


            // Call the API

            $response = $client->getTopHits(
                'index',
            );



            // print the response

            var_dump($response);
        - lang: python
          label: Python
          source: >-
            # Initialize the client

            # In an asynchronous context, you can use AnalyticsClient instead,
            which exposes the exact same methods.

            client = AnalyticsClientSync(
                "ALGOLIA_APPLICATION_ID", "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION"
            )


            # Call the API

            response = client.get_top_hits(
                index="index",
            )



            # print the response

            print(response)
        - lang: ruby
          label: Ruby
          source: >-
            # Initialize the client

            client = Algolia::AnalyticsClient.create("ALGOLIA_APPLICATION_ID",
            "ALGOLIA_API_KEY", "ALGOLIA_APPLICATION_REGION")


            # Call the API

            response = client.get_top_hits("index")



            # print the response

            puts(response)
        - lang: scala
          label: Scala
          source: |-
            // Initialize the client
            val client = AnalyticsClient(
              appId = "ALGOLIA_APPLICATION_ID",
              apiKey = "ALGOLIA_API_KEY",
              region = Option("ALGOLIA_APPLICATION_REGION")
            )

            // Call the API
            val response = Await.result(
              client.getTopHits(
                index = "index"
              ),
              Duration(100, "sec")
            )

            // print the response
            println(response)
        - lang: swift
          label: Swift
          source: >-
            // Initialize the client

            let client = try AnalyticsClient(appID: "ALGOLIA_APPLICATION_ID",
            apiKey: "ALGOLIA_API_KEY", region: .us)


            // Call the API

            let response = try await client.getTopHits(index: "index")


            // print the response

            print(response)
        - lang: cURL
          label: curl
          source: |-
            curl --request GET \
              --url 'https://analytics.us.algolia.com/2/hits?index=ALGOLIA_INDEX_NAME&search=enable%20ab%20test&clickAnalytics=false&revenueAnalytics=false&startDate=2022-09-19&endDate=2023-01-21&limit=10&offset=0&tags=device%3Amobile%2520phone' \
              --header 'accept: application/json' \
              --header 'x-algolia-api-key: ALGOLIA_API_KEY' \
              --header 'x-algolia-application-id: ALGOLIA_APPLICATION_ID'
components:
  parameters:
    Index:
      in: query
      name: index
      description: Index name.
      required: true
      schema:
        type: string
        example: ALGOLIA_INDEX_NAME
    ClickAnalytics:
      in: query
      name: clickAnalytics
      description: >-
        Whether to include metrics related to click and conversion events in the
        response.
      schema:
        type: boolean
        default: false
    EndDate:
      in: query
      name: endDate
      description: End date of the period to analyze, in `YYYY-MM-DD` format.
      schema:
        type: string
        example: '2023-01-21'
    Limit:
      in: query
      name: limit
      description: |
        Number of items to return.
      required: false
      schema:
        type: integer
        default: 10
        maximum: 1000
    Offset:
      in: query
      name: offset
      description: |
        Position of the first item to return.
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
    RevenueAnalytics:
      in: query
      name: revenueAnalytics
      description: Whether to include metrics related to revenue events in the response.
      schema:
        type: boolean
        default: false
    Search:
      in: query
      name: search
      description: Search query.
      example: enable ab test
      schema:
        type: string
    StartDate:
      in: query
      name: startDate
      description: Start date of the period to analyze, in `YYYY-MM-DD` format.
      schema:
        type: string
        example: '2022-09-19'
    Tags:
      name: tags
      in: query
      description: >
        Tags by which to segment the analytics.


        You can combine multiple tags with `OR` and `AND`.

        Tags must be URL-encoded.

        For more information, see [Segment your analytics
        data](https://www.algolia.com/doc/guides/search-analytics/guides/segments).
      example: device:mobile%20phone
      schema:
        type: string
  headers:
    x-ratelimit-limit:
      description: Number of allowed requests per one minute.
      example: 100
      schema:
        type: integer
    x-ratelimit-remaining:
      description: Number of remaining requests in the current period.
      example: 99
      schema:
        type: integer
    x-ratelimit-reset:
      description: >-
        Timestamp when the rate limit will reset, measured in seconds since the
        Unix epoch.
      example: 1710682486
      schema:
        type: integer
  schemas:
    getTopHitsResponse:
      oneOf:
        - $ref: '#/components/schemas/topHitsResponse'
        - $ref: '#/components/schemas/topHitsResponseWithAnalytics'
        - $ref: '#/components/schemas/topHitsResponseWithRevenueAnalytics'
    topHitsResponse:
      type: object
      title: Top search results
      additionalProperties: false
      required:
        - hits
      properties:
        hits:
          type: array
          description: Most frequent search results.
          items:
            title: topHit
            type: object
            additionalProperties: false
            required:
              - hit
              - count
            properties:
              count:
                $ref: '#/components/schemas/parameters_count'
              hit:
                $ref: '#/components/schemas/hit'
    topHitsResponseWithAnalytics:
      type: object
      title: Top search results with click analytics
      additionalProperties: false
      required:
        - hits
      properties:
        hits:
          type: array
          description: Most frequent search results with click and conversion metrics.
          items:
            title: topHitWithAnalytics
            type: object
            additionalProperties: false
            required:
              - hit
              - count
              - clickThroughRate
              - conversionRate
              - trackedHitCount
              - clickCount
              - conversionCount
            properties:
              clickCount:
                $ref: '#/components/schemas/clickCount'
              clickThroughRate:
                $ref: '#/components/schemas/clickThroughRate'
              conversionCount:
                $ref: '#/components/schemas/conversionCount'
              conversionRate:
                $ref: '#/components/schemas/conversionRate'
              count:
                $ref: '#/components/schemas/parameters_count'
              hit:
                $ref: '#/components/schemas/hit'
              trackedHitCount:
                $ref: '#/components/schemas/trackedSearchCount'
    topHitsResponseWithRevenueAnalytics:
      type: object
      title: Top search results with revenue analytics
      additionalProperties: false
      required:
        - hits
      properties:
        hits:
          type: array
          description: >-
            Most frequent search results with click, conversion, and revenue
            metrics.
          items:
            title: topHitWithRevenueAnalytics
            type: object
            additionalProperties: false
            required:
              - hit
              - count
              - clickThroughRate
              - conversionRate
              - trackedHitCount
              - clickCount
              - conversionCount
              - purchaseCount
              - addToCartCount
              - purchaseRate
              - addToCartRate
              - currencies
            properties:
              addToCartCount:
                $ref: '#/components/schemas/addToCartCount'
              addToCartRate:
                $ref: '#/components/schemas/addToCartRate'
              clickCount:
                $ref: '#/components/schemas/clickCount'
              clickThroughRate:
                $ref: '#/components/schemas/clickThroughRate'
              conversionCount:
                $ref: '#/components/schemas/conversionCount'
              conversionRate:
                $ref: '#/components/schemas/conversionRate'
              count:
                $ref: '#/components/schemas/parameters_count'
              currencies:
                $ref: '#/components/schemas/currencies'
              hit:
                $ref: '#/components/schemas/hit'
              purchaseCount:
                $ref: '#/components/schemas/purchaseCount'
              purchaseRate:
                $ref: '#/components/schemas/purchaseRate'
              trackedHitCount:
                $ref: '#/components/schemas/trackedSearchCount'
    ErrorBase:
      description: Error.
      type: object
      x-keep-model: true
      additionalProperties: true
      properties:
        message:
          type: string
          example: Invalid Application-Id or API-Key
    parameters_count:
      description: Number of occurrences.
      example: 2
      type: integer
    hit:
      description: Object ID of a record returned as a search result.
      type: string
      example: method-export-rules-php
    clickCount:
      type: integer
      description: Number of clicks associated with this search.
      example: 162
      minimum: 0
      default: 0
    clickThroughRate:
      oneOf:
        - type: number
          format: double
          description: >
            Click-through rate: calculated as the number of tracked searches
            with at least one click event divided by the number of tracked
            searches.

            If null, Algolia didn't receive any search requests with
            `clickAnalytics` set to true.
          minimum: 0
          maximum: 1
          default: null
          example: 0.49
        - type: 'null'
    conversionCount:
      type: integer
      description: Number of conversions from this search.
      example: 10
      minimum: 0
      default: 0
    conversionRate:
      oneOf:
        - type: number
          format: double
          description: >
            Conversion rate: calculated as the number of tracked searches with
            at least one conversion event divided by the number of tracked
            searches.

            If null, Algolia didn't receive any search requests with
            `clickAnalytics` set to true.
          minimum: 0
          maximum: 1
          default: null
          example: 0.05
        - type: 'null'
    trackedSearchCount:
      type: integer
      example: 2
      default: 0
      description: >-
        Number of tracked searches. Tracked searches are search requests where
        the `clickAnalytics` parameter is true.
    addToCartCount:
      type: integer
      description: Number of add-to-cart events from this search.
      minimum: 0
      default: 0
      example: 10
    addToCartRate:
      oneOf:
        - type: number
          format: double
          description: >
            Add-to-cart rate: calculated as the number of tracked searches with
            at least one add-to-cart event divided by the number of tracked
            searches.

            If null, Algolia didn't receive any search requests with
            `clickAnalytics` set to true.
          minimum: 0
          maximum: 1
          default: null
          example: 0.1
        - type: 'null'
    currencies:
      type: object
      description: |
        Revenue associated with this search: broken down by currency.
      default: {}
      additionalProperties:
        title: currencyCode
        x-additionalPropertiesName: currency
        type: object
        description: Currency code.
        properties:
          currency:
            type: string
            description: Currency code.
            example: USD
          revenue:
            type: number
            format: float
            description: Revenue associated with this search in this currency.
            example: 999.98
    purchaseCount:
      type: integer
      description: Number of purchase events from this search.
      default: 0
      example: 10
    purchaseRate:
      oneOf:
        - type: number
          format: double
          description: >
            Purchase rate: calculated as the number of tracked searches with at
            least one purchase event divided by the number of tracked searches.

            If null, Algolia didn't receive any search requests with
            `clickAnalytics` set to true.
          minimum: 0
          maximum: 1
          default: null
          example: 0.05
        - type: 'null'
  responses:
    BadRequest:
      description: Bad request or request arguments.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    FeatureNotEnabled:
      description: This feature is not enabled on your Algolia account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    MethodNotAllowed:
      description: Method not allowed with this API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
    IndexNotFound:
      description: Index not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBase'
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: x-algolia-application-id
      description: Your Algolia application ID.
    apiKey:
      type: apiKey
      in: header
      name: x-algolia-api-key
      description: >
        Your Algolia API key with the necessary permissions to make the request.

        Permissions are controlled through access control lists (ACL) and access
        restrictions.

        The required ACL to make a request is listed in each endpoint's
        reference.

````