Using the Insights API

Insights API Documentation

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.

---

Query

Sample Query:

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

Result:

{
  "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:

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

Result:

{
  "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: 7 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 5th of December 2023 at 1pm to the 12th of December 2023 at 1pm.

Note: Data is retained for a maximum of 7 days. After this period, it is no longer available.

Sample Query:

{
  insights(
    from: "2023-12-05T13:00:00",
    to: "2023-12-12T13: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.

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.

"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
                        }
                    ]
                }
            ]
        }
    }