---
title: Insights API
description: Using the WP Engine Smart Search Insights API
url: https://developers.wpengine.com/docs/smart-search/graphql-api/insights/
image: https://developers.wpengine.com/og/docs/smart-search/graphql-api/insights.png
---

# Insights API

The Insights API allows you fetch insights on search terms that returned results and search terms that did not return any results.

## Authentication

Clients calling the API are required to add an authentication header with the valid authentication token.

```
Authorization: Bearer {ACCESS_TOKEN}
```

Data needed to consume API can be found in your WP Admin area in the WP Engine Smart Search tab under `Settings`.

![WP Engine Smart Search Settings](https://developers.wpengine.com/_astro/as-plugin-settings.Bs9gXCGQ_Z2idWUG.webp)

---

### Query

Sample Query:

```graphql
{
  insights {
    searchTerms {
      term
      numberOfSearches
    }
    searchTermsNoResults {
      term
      numberOfSearches
    }
    from
    to
  }
}
```

Result:

```json
{
  "data": {
    "insights": {
      "searchTerms": [
        {
          "term": "hello",
          "numberOfSearches": 5
        },
        {
          "term": "sample page",
          "numberOfSearches": 3
        }
      ],
      "searchTermsNoResults": [
        {
          "term": "shoes",
          "numberOfSearches": 3
        }
      ],
      "from": "2023-12-05T13:25:44",
      "to": "2023-12-12T13:25:44"
    }
  }
}
```

By default, the maximum number of search terms returned is 100. If you want to change this limit, you can use the `top` input variable. Sample Query with `top` variable:

```graphql
{
  insights {
    searchTerms(top: 3) {
      term
      numberOfSearches
    }
    searchTermsNoResults(top: 3) {
      term
      numberOfSearches
    }
    from
    to
  }
}
```

Result:

```json
{
  "data": {
    "insights": {
      "searchTerms": [
        {
          "term": "*",
          "numberOfSearches": 308
        },
        {
          "term": "hello",
          "numberOfSearches": 162
        },
        {
          "term": "sample page",
          "numberOfSearches": 106
        }
      ],
      "searchTermsNoResults": [
        {
          "term": "no results",
          "numberOfSearches": 36
        },
        {
          "term": "shoes",
          "numberOfSearches": 24
        },
        {
          "term": "jackets",
          "numberOfSearches": 23
        }
      ],
      "from": "2025-05-17T10:43:58",
      "to": "2025-06-16T10:43:58"
    }
  }
}
```

#### Filtering by time window

- If the values for `to` and `from` are not provided the following values are the defaults:

  - `to: now`
  - `from: 30 days ago`

- You can filter by a time window using the `from` and `to` input variables These variables accept the URX time format `yyyy-MM-ddTHH:mm:ss`

- The example below filters insights data from the `1st of December 2023 at 1pm` to the `31st of December 2023 at 1pm`.

> **Note**
>
> Data is retained for a maximum of 30 days. After this period, it is no longer available.

Sample Query:

```graphql
{
  insights(from: "2023-12-01T13:00:00", to: "2023-12-31T13:00:00") {
    searchTerms {
      term
      numberOfSearches
    }
    searchTermsNoResults {
      term
      numberOfSearches
    }
    from
    to
  }
}
```

## Site Analytics API

SiteAnalytics returns user interaction data for a customer’s site, including user events and click-through rates for each document. This endpoint allows you to retrieve valuable insights into how users are engaging with your content.

### GraphQL Query

To fetch site analytics, you will use the insights query. The results are returned in descending order of total impressions.

```graphql
query Insights($top: Int, $from: String, $to: String) {
  insights {
    siteAnalytics(top: $top, from: $from, to: $to) {
      documentID
      totalImpressions
      clickThroughRate {
        total
      }
      events {
        name
        numberOfHits
      }
    }
  }
}
```

### Input Parameters

The siteAnalytics field accepts the following optional arguments to filter the results:

| Parameter | Type   | Description                                                                              |
| --------- | ------ | ---------------------------------------------------------------------------------------- |
| top       | Int    | The number of document analytics to return. Defaults to a preset limit if not specified. |
| from      | String | The start date for the analytics data (e.g., "YYYY-MM-DD").                              |
| to        | String | The end date for the analytics data (e.g., "YYYY-MM-DD").                                |

### Response Payload

The query returns an array of siteAnalytics objects, each containing the following fields:

| Field            | Type   | Description                                                                                                     |
| ---------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| documentID       | String | The unique identifier for the document.                                                                         |
| totalImpressions | Int    | The total number of times a document was viewed, appeared in search results or clicked from the search results. |
| clickThroughRate | Object | An object containing the click-through rate percentage.                                                         |
| › total          | Float  | The overall click-through rate ((clicks / impressions) \* 100).                                                 |
| events           | Array  | A list of user interaction events associated with the document.                                                 |
| › name           | String | The name of the event. Possible values are page_view, search, and search_click.                                 |
| › numberOfHits   | Int    | The number of times this specific event occurred for the document.                                              |

### Example Response

Below is an example of the data structure returned by the query.

```json
"data": {
        "insights": {
            "siteAnalytics": [
                {
                    "documentID": "post:138",
                    "totalImpressions": 9,
                    "clickThroughRate": {
                        "total": 0
                    },
                    "events": [
                        {
                            "name": "page_view",
                            "numberOfHits": 3
                        },
                        {
                            "name": "search",
                            "numberOfHits": 6
                        }
                    ]
                },
                {
                    "documentID": "post:149",
                    "totalImpressions": 8,
                    "clickThroughRate": {
                        "total": 50
                    },
                    "events": [
                        {
                            "name": "page_view",
                            "numberOfHits": 2
                        },
                        {
                            "name": "search_click",
                            "numberOfHits": 2
                        },
                        {
                            "name": "search",
                            "numberOfHits": 4
                        }
                    ]
                }
            ]
        }
    }
```

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```