Skip to main content

How to request element optimisation

Element optimisation requests use AI to generate better title, meta description and H1 tag for a page, based on the search queries.

To create an element optimisation request, an Account must have AI features enabled. Additionally, your Account role must be an Editor or higher.

Requesting element optimisation and retrieving the results using API is done in 3 steps:

1. Create an element optimisation request​

Use the createElementOptimisationRequest mutation to create an element optimisation request and start the generation process.

Input requires you to pass Crawl.id and CrawlUrl.urlDigest. Optionally, you can pass up to 5 CrawlSearchQuery.searchQueryDigest values to pick the search queries you want to optimise the page for. By default, the generation process uses the top 5 search queries ordered by clicks.

mutation CreateElementOptimisationRequest($input: CreateElementOptimisationRequestInput!) {
  createElementOptimisationRequest(input: $input) {
    elementOptimisationRequest {
      id
      searchQueryDigests
      status
      url
      urlDigest
    }
  }
}

2. Wait for the generation to finish​

At first, element optimisation request status will be Created. When the generation process starts, it will change to Generating. Finally, after the process finishes, the value will be Generated. The whole process usually takes just a couple of seconds.

3. Retrieve the element optimisation request results​

Use the getElementOptimisationRequest query to retrieve element optimisation request by id.

query GetElementOptimisationRequest($id: ObjectID!) {
  getElementOptimisationRequest(id: $id) {
    generatedAt
    generatingAt
    id
    result {
      descriptionRelevance
      h1TagRelevance
      optimisedDescription
      optimisedDescriptionRelevance
      optimisedH1Tag
      optimisedH1TagRelevance
      optimisedPageTitle
      optimisedPageTitleRelevance
      pageTitleRelevance
    }
    searchQueryDigests
    status
    url
    urlDigest
  }
}

Results include relevance values calculated for the chosen search queries, suggested optimised elements, and the relevance of the optimised elements.

You can create multiple element optimisation requests for each crawl URL, using different search queries. To retrieve multiple element optimisation requests, you need to get a report stat and filter crawl URLs by the URL digest.

query GetCrawlUrlElementOptimisationRequests(
  $crawlId: ObjectID!
  $reportTemplateCode: String!
  $urlDigest: String!
) {
  getReportStat(
    input: { crawlId: $crawlId, reportTemplateCode: $reportTemplateCode }
  ) {
    crawlUrls(filter: { urlDigest: { eq: $urlDigest } }) {
      nodes {
        elementOptimisationRequests {
          nodes {
            generatedAt
            generatingAt
            id
            result {
              descriptionRelevance
              h1TagRelevance
              optimisedDescription
              optimisedDescriptionRelevance
              optimisedH1Tag
              optimisedH1TagRelevance
              optimisedPageTitle
              optimisedPageTitleRelevance
              pageTitleRelevance
            }
            searchQueryDigests
            status
          }
        }
        url
        urlDigest
      }
    }
  }
}