Update Keyword Research Item

Updates a keyword research item.

fieldMask is required and must name at least one of keyword or mainKeyword. Those are the only writable fields, and an omitted or empty mask is rejected rather than treated as a request to write everything.

mainKeyword only promotes. Set it to true to make the item its page's main keyword. Setting it to false, or leaving it out, changes nothing, so a main keyword can't be demoted with this method.

This method updates an item that already exists. It can't add or delete a keyword.

The first write to AI-generated research copies that research instead of changing it, so the response can carry a different keywordResearchId. Always send the ID from the most recent response on your next write. Sending the original ID again copies the research again.

Changing keyword also refreshes that item's searchVolume and competition, even though the mask doesn't name them.

Edits don't survive a later generation. A generation that completes after your edit produces fresh research that replaces the edited copy in every read.

To update multiple keyword research items in a single API call, call Bulk Update Keyword Research Items.