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