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.

Part 1: Wait for matching research

To monitor the research for the requested flow:

1. Call 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.
2. When the flow reports KEYWORD_RESEARCH, read its keywordResearchId. This flow status means research has started; it does not establish readiness.
3. Call Get Site Keyword Research with that research ID. Require the returned siteKeywordResearch.id and siteKeywordResearch.contentPlanFlowId to match the research and flow being followed.
4. 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 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.
2. 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.
3. 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.
4. Once the same flow reports SUCCESS, call 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 without keywordResearchId.
2. 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.
3. 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.