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. 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 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.
• Retrieve the site's 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.