About the Page Optimization API

The Page Optimization API generates AI-powered, whole-page SEO suggestions for a page of a Wix site: a rewritten title tag, description tag, headings, and body text. Each suggestion is a before/after pair against the page's current content, aimed at the page's focus keyword.

With the Page Optimization API, you can:

  • Start an optimization job for a static page or for the site's homepage.
  • Poll for the job's status and retrieve the finished suggestion set.
  • Show site owners what to change on the page, text by text, and apply the changes they accept.

How optimization works

Generation is asynchronous. Trigger Page Optimization or Trigger Home Page Optimization starts a generation job and returns a predictionId. Poll Get Page Optimization Results until status is COMPLETED. Generation typically takes under 2 minutes.

The job reads the page from the site's latest saved revision, so unpublished changes are included and the site doesn't need to be published. To analyze the page, a temporary preview deployment of that saved revision is created on the site and removed automatically after 30 minutes. The site's editor content and live version are never modified.

Optimization targets the page's focus keyword, which is read from the page's SEO settings. Set it before triggering, for example with the Item SEO Tags API. A page without a focus keyword can't be optimized.

Suggestions are stored per page. A later trigger for the same page replaces the previous suggestion set. A predictionId can be looked up for 2 hours after its trigger, and a lookup by pageId returns the page's latest suggestions at any time.

Triggering is idempotent per page. While a job for the page is in progress, triggering again returns the same predictionId. If the page's focus keyword changed since the job started, the trigger fails with SUGGESTIONS_ALREADY_IN_PROGRESS.

Suggestions are generated by AI, so triggering the same page twice may produce different suggestions.

Before you begin

It's important to note the following points before starting to code:

  • Only static pages are supported. Other site items, such as blog posts, store products, bookings services, and events, fail with PAGE_NOT_SUPPORTED. To find a site's static pages and their IDs, call List Item SEO Tags for item type STATIC_PAGE.
  • The page must have a focus keyword set in its SEO settings. Otherwise the trigger fails with FOCUS_KEYWORD_NOT_SET.
  • Only Wix-rendered sites are supported. Headless projects fail with SITE_NOT_SUPPORTED.
  • All methods accept both a Wix user identity, for example an app acting on behalf of a signed-in site owner, and an API key.
  • Each call has a time budget of 60 seconds.
  • Calls are rate limited. Calls over the limit are rejected with HTTP 429.

Use cases

Terminology

  • Focus keyword: The search term a page targets, set in the page's SEO settings. Suggestions are written to rank the page for it.
  • Generation job: One run of the AI optimization for a page, identified by its predictionId. A job is IN_PROGRESS, COMPLETED, or FAILED.
  • Text suggestion: A before/after pair. before is the page's current text and after the suggested replacement. before is empty when the page has no text in that slot, such as a missing meta description.
  • Title tag and description tag: The page's <title> element and meta description, shown in search results.
  • Body text: The page's paragraph and section texts. Up to 100 of them get a suggested rewrite.

Last updated: 2 November 2026

Did this help?