# About the Site Keyword Research API

The Site Keyword Research API reports the status of a site's keyword research runs. A content plan flow starts a research run whose keywords are used to generate blog post briefs.

With the Site Keyword Research API, you can:

- Check whether the keyword research a content plan flow started has finished.
- Retrieve the site's most recent successful keyword research.

## Research and content plan progress

A content plan flow reaches `KEYWORD_RESEARCH` as soon as keyword research starts. This flow status doesn't establish readiness. Read the research using the flow's actual `keywordResearchId` and require both the returned research ID and `contentPlanFlowId` to match the job being followed. Research `SUCCESS` means the research has finished, not that the blog post briefs have been generated.

Some flows advance automatically. After matching research `SUCCESS`, re-read the same flow before calling [Create Content Plan](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/create-content-plan). Call it once only while the flow still reports `KEYWORD_RESEARCH` with that research ID and no release has already been attempted. Skip Create when the flow has advanced to `CONTENT_PLAN` or `SUCCESS`. See [Sample Flows](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-keyword-research-v1/sample-flows#monitor-research-for-a-content-plan-flow) for paced monitoring, stopping conditions, and retrieval of the resulting briefs.

## Before you begin

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

- The site must have the business information that keyword research requires. Until it does, the content plan flow waits at `PENDING_REQUIREMENTS` and no research starts. The public API doesn't identify the missing requirements.
- Retrieving research without an ID selects the most recent successful run. It doesn't return a run that's still in progress and can't establish readiness for a particular flow.

## Use cases

- [Monitor research for a content plan flow](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-keyword-research-v1/sample-flows#monitor-research-for-a-content-plan-flow).
- [Retrieve the site's latest successful research](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-keyword-research-v1/sample-flows#retrieve-the-sites-latest-successful-research).

## Terminology

- Keyword research run: A job that determines keywords for the site's content plan. Its ID and status identify the research being monitored.
- Content plan flow: The generation job associated with the research. Its ID remains the same while the job progresses from prerequisites through research and brief generation.
- Blog post candidate: A proposed blog post brief generated from the keyword research. Research completion and candidate generation are separate stages.

@sdk_package_setup

# Site Keyword Research: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Monitor research for a content plan flow

Your app follows a content plan flow requested by a site owner. It needs to distinguish research that has started from research that is ready before generating blog post briefs.

The field paths below use REST names. In SDK responses, the research ID is `siteKeywordResearch._id` instead of `siteKeywordResearch.id`; `contentPlanFlowId` has the same spelling in both clients.

> Prerequisite: Retain the actual flow ID returned by [Trigger Content Plan Generation Flow](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/trigger-content-plan-generation-flow) for the site owner's requested generation job.

### Part 1: Wait for matching research

To monitor the research for the requested flow:

1. Call [Get Content Plan Flow](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/get-content-plan-flow) with the actual flow ID. Retain this ID throughout monitoring. If the flow is `PENDING_REQUIREMENTS`, report that generation is waiting for required business information and ask the site owner to review their business information in the Wix dashboard. The public API does not identify the missing requirements. If the site owner wants to wait, continue monitoring within a finite window, waiting 10 to 15 seconds between requests; otherwise preserve the flow ID and stop monitoring.
1. When the flow reports `KEYWORD_RESEARCH`, read its `keywordResearchId`. This flow status means research has started; it does not establish readiness.
1. Call [Get Site Keyword Research](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-keyword-research-v1/get-site-keyword-research) with that research ID. Require the returned `siteKeywordResearch.id` and `siteKeywordResearch.contentPlanFlowId` to match the research and flow being followed.
1. While research reports `IN_PROGRESS`, wait 10 to 15 seconds between requests within a finite monitoring window. A not found response can occur before the research record exists; retry a paced read and re-read the flow if it persists. Stop for `FAIL`, `CANCELED`, `REVERTED`, mismatched IDs, or an expired monitoring window. Preserve the IDs and report the last observed status instead of automatically triggering a replacement flow.

### Part 2: Generate and retrieve briefs

After the matching research has succeeded, follow the same flow through brief generation:

1. After matching research `SUCCESS`, call Get Content Plan Flow again with the same flow ID. If it still reports `KEYWORD_RESEARCH` with the same research ID, and the site owner requested brief generation, call [Create Content Plan](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/create-content-plan) once, provided no release has already been attempted for this flow. Set the request's `contentPlanFlowId` to the retained flow ID; don't omit it. Check `success` in its response as well as the HTTP status. A `false` result is not successful generation.
1. Compare Create's returned `contentPlanFlowId` with the retained ID. A different ID means a separate generation was started, for example if the flow completed between the readiness read and Create. Preserve both IDs and report the unexpected regeneration; don't present the original flow's briefs as its result. Follow the returned ID only when the site owner intended regeneration, using the same bounded monitoring and completion checks.
1. If the flow has already advanced to `CONTENT_PLAN` or `SUCCESS`, skip Create Content Plan. Some flows advance automatically. While it is `CONTENT_PLAN`, continue paced, bounded monitoring of the same flow. Stop for `FAIL`, `CANCELED`, or an expired monitoring window.
1. Once the same flow reports `SUCCESS`, call [List Blog Post Candidates](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/list-blog-post-candidates) with that flow ID to retrieve its briefs.

Calling Create Content Plan while research is `IN_PROGRESS` fails with `FLOW_NOT_READY_FOR_CONTENT_PLAN`. Elapsed time and an ID-less research read cannot substitute for matching readiness evidence.

## Retrieve the site's latest successful research

Your app wants to display the most recent completed research run, without tracking a particular content plan flow.

To display the site's latest completed research:

1. Call [Get Site Keyword Research](fallback::https://dev.wix.com/docs/api-reference/business-management/seo/site-keyword-research-v1/get-site-keyword-research) without `keywordResearchId`.
1. Read the returned research ID (`siteKeywordResearch.id` in REST or `siteKeywordResearch._id` in the SDK), `status`, and `contentPlanFlowId`. An ID-less request selects the latest successful research, excluding runs still in progress. If no successful run exists, the method returns a not found error.
1. Display the research ID and associated flow ID alongside its status so the site owner can identify the completed run.

Do not use this ID-less request to decide whether a different flow is ready for Create Content Plan. Follow the exact-ID monitoring flow above for that decision.

Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Extend Websites with SDK

Build Apps

Client (Deprecated)

API Preview

Wix CLI

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

ID of the Wix account associated with the event.

accountId

ID of the parent Wix account. Only included when accountId belongs to a child account.

parentAccountId

ID of the Wix site associated with the event. Only included when the event is tied to a specific site.

siteId

AccountInfo

identityType

IdentificationData

WebhookIdentityType

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

data

eventType

The identification type and identity data.

instanceId

MessageEnvelope

value

BoolValue

Int64Value

values

ListValue

NullValue

StringValue

fields

Struct

nanos

seconds

Timestamp

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

bodyAsJson

ActionEvent

A sequence number that indicates the order of updates to an entity. For example, if an entity was updated at `16:00` and then again at `16:01`, the second update will always have a higher sequence number.
You can use this number to make sure you're handling updates in the right order. Just save the latest sequence number on your end and compare it to the one in each new message. If the new message has an older (lower) number, you can safely ignore it.

entityEventSequence

Fully Qualified Domain Name of an entity. This is a unique identifier assigned to the API main business entities.
For example, `wix.stores.catalog.product`, `wix.bookings.session`, `wix.payments.transaction`.

entityFqdn

ID of the entity associated with the event.

entityId

Event timestamp in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format and UTC time. For example, `2020-04-26T13:57:50.699Z`.

eventTime

Event ID. With this ID you can easily spot duplicated events and ignore them.

If present, indicates the action that triggered the event.

originatedFrom

Event action name, placed at the top level to make it easier for users to dispatch messages.
For example: `created`/`updated`/`deleted`/`started`/`completed`/`email_opened`.

slug

Whether the event was triggered as a result of a privacy regulation application
(for example, GDPR).

triggeredByAnonymizeRequest

DomainEvent

body

entityAsJson

Indicates the event was triggered by a restore-from-trashbin operation for a previously deleted entity

EntityCreatedEvent

deletedEntityAsJson

EntityDeletedEvent

Since platformized APIs only expose PATCH and not PUT we can't assume that the fields sent from the client are the actual diff.
This means that to generate a list of changed fields (as opposed to sent fields) one needs to traverse both objects.
We don't want to impose this on all developers and so we leave this traversal to the notification recipients which need it.

currentEntityAsJson

EntityUpdatedEvent

deletedDate

RestoreInfo

ID of the keyword research run to retrieve. Use the `keywordResearchId`
of a content plan flow.

Omit to retrieve the site's most recent successful research.

keywordResearchId

GetSiteKeywordResearchRequest

GetSiteKeywordResearchResponse

ID of the keyword research run to promote.

PromoteSiteKeywordResearchToSuccessRequest

PromoteSiteKeywordResearchToSuccessResponse

A site keyword research run records the progress of keyword research for a
content plan flow. Use its status and associated flow ID to monitor the run
before generating blog post briefs.

ID of the content plan flow that started the keyword research.

contentPlanFlowId

Date and time the keyword research started.

createdAt

Keyword research ID. Matches the `keywordResearchId` of the content
plan flow that started it.

status

Date and time the keyword research was last updated.

updatedAt

SiteKeywordResearch

Keyword research is running. Continue paced reads of
[Get Site Keyword Research](https://dev.wix.com/docs/api-reference/business-management/seo/site-keyword-research-v1/get-site-keyword-research)
within a finite monitoring window.

Keyword research is complete. Re-read the associated flow before
generating briefs. Call
[Create Content Plan](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/create-content-plan)
once only if the flow still reports `KEYWORD_RESEARCH` with this
research ID and no release has already been attempted.

Keyword research failed. Stop monitoring and preserve the research
and flow IDs. Don't automatically trigger a replacement flow.

The research was reverted to an earlier run.

Keyword research was canceled, together with its content plan flow.

Status

Retrieves a site keyword research run, including its status.

A content plan flow reaches `KEYWORD_RESEARCH` when research starts,
not when it finishes. Retrieve the flow with
[Get Content Plan Flow](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-content-plan-flow-v1/get-content-plan-flow),
then specify its actual `keywordResearchId` and
check that the returned research ID and `contentPlanFlowId` match.
For research still `IN_PROGRESS`, use paced reads within a finite
monitoring window. A brief not found error can occur before the
research record exists; re-read the flow if it persists.

After matching research `SUCCESS`, re-read the same flow. Call
[Create Content Plan](https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-blog-post-candidate-v1/create-content-plan)
once only if the flow still reports `KEYWORD_RESEARCH`
with that research ID and no release has already been attempted.
If the flow has advanced to `CONTENT_PLAN` or `SUCCESS`, skip Create.
Calling Create while research is `IN_PROGRESS` fails with
`FLOW_NOT_READY_FOR_CONTENT_PLAN`.

Stop for `FAIL`, `CANCELED`, `REVERTED`, mismatched IDs or an expired
monitoring window. Preserve the IDs and report the observed result.
Elapsed time alone proves neither failure nor permission to start a
replacement flow.

Omit `keywordResearchId` to retrieve the site's most recent successful
research. A run that's still in progress is never returned this way, and
a site with no successful research returns a not found error.

Polls the keyword research a content plan flow started. Here the research is still running, so status is IN_PROGRESS and the content plan can't be created yet.

Check whether a flow's keyword research has finished

GetSiteKeywordResearch

View SEO Settings

Site Keyword Research

addressLine1

addressLine2

city

country

formatted

postalCode

subdivision

Address

GoogleProtoDuration

latitude

longitude

Location

name

number

StreetAddress

GetSiteKeywordResearchOptions

GetSiteKeywordResearchRequestSignature

import { siteKeywordResearch } from "@wix/seo";

async function retrieveKeywordResearch() {
  const response = await siteKeywordResearch.getSiteKeywordResearch({
    keywordResearchId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  });
  return response;
}

/* Promise resolves to:
 * {
 *   "siteKeywordResearch": {
 *     "_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
 *     "createdAt": "2026-08-26T10:16:02.000Z",
 *     "updatedAt": "2026-08-26T10:16:02.000Z",
 *     "status": "IN_PROGRESS",
 *     "contentPlanFlowId": "d290f1ee-6c54-4b01-90e6-d701748f0851"
 *   }
 * }
 */


Illustrates an exact-ID lookup. Replace the example UUID with the actual keywordResearchId from your content plan flow. This lookup alone doesn't verify the flow association or authorize brief generation.

Retrieve a keyword research run by ID

import { createClient } from '@wix/sdk';
import { siteKeywordResearch } from '@wix/seo';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { siteKeywordResearch },
  // Include the auth strategy and host as relevant
});


async function getSiteKeywordResearch(options) {
  const response = await myWixClient.siteKeywordResearch.getSiteKeywordResearch(options);
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

Site Keyword Research Object