> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# ListKeywordResearchItems

# Package: seo

# Namespace: KeywordResearchServiceV1

# Method link: https://dev.wix.com/docs/api-reference/business-management/seo/content-plan-keyword-research-v1/list-keyword-research-items.md

## Permission Scopes:
View SEO Settings: SCOPE.PROMOTE.VIEW-SEO

## Introduction

Retrieves the keyword research behind the site's current content plan.

Returns the research produced by the last completed generation. Research
from a generation that's still running, or that failed, isn't readable.
Poll Get Content Plan Flow until its status is `SUCCESS`, then call this
method.

The result is scoped to the site rather than to a flow. This method
always returns the site's most recent research and can't target an
earlier one. If another generation finishes between your trigger and this
read, you receive the newer research instead. Compare `keywordResearchId`
across reads to detect that the research was replaced.

Omit `paging` to return every item in a single response. When `paging` is
present, `limit` accepts 1 to 100 and defaults to 50.

A site with no keyword research returns a not found error rather than an
empty list.

---

## REST API

### Schema

```
 Method: listKeywordResearchItems
 Description: Retrieves the keyword research behind the site's current content plan.  Returns the research produced by the last completed generation. Research from a generation that's still running, or that failed, isn't readable. Poll Get Content Plan Flow until its status is `SUCCESS`, then call this method.  The result is scoped to the site rather than to a flow. This method always returns the site's most recent research and can't target an earlier one. If another generation finishes between your trigger and this read, you receive the newer research instead. Compare `keywordResearchId` across reads to detect that the research was replaced.  Omit `paging` to return every item in a single response. When `paging` is present, `limit` accepts 1 to 100 and defaults to 50.  A site with no keyword research returns a not found error rather than an empty list.
 URL: https://www.wixapis.com/promote/seo/v1/content-plan-keyword-research-items
 Method: GET
 Method parameters:
   query param name: contentPlanFlowId | type: contentPlanFlowId | description: Reserved for future use.  This method currently resolves the site's most recent keyword research, and this field is ignored.  | validation: format GUID
   param name: paging | type: CursorPaging    
        - name: limit | type: integer | description: Max items per page. Default 50, max 100.  | validation: minimum 0, maximum 100, format int32
        - name: cursor | type: string | description: Cursor from a previous response. Omit for the first page.  | validation: maxLength 16000
 Return type: ListKeywordResearchItemsResponse
  - name: keywordResearchItems | type: array<KeywordResearch> | description: Retrieved keyword research items.  | validation: maxItems 1000
     - name: id | type: string | description: Keyword research item GUID.  | read-only: true | validation: format GUID
     - name: keyword | type: string | description: The keyword itself.  An update is rejected if the new keyword is longer than 80 characters, or if it duplicates another keyword in the same research.  | validation: maxLength 1000
     - name: pageId | type: string | description: GUID of the site page the keyword is assigned to.  | validation: maxLength 1000
     - name: itemType | type: string | description: Type of the site page the keyword is assigned to, such as a static page or a blog post.  | validation: maxLength 1000
     - name: pageUrl | type: string | description: URL of the site page the keyword is assigned to.  | validation: maxLength 1000
     - name: competition | type: integer | description: How hard it is to rank for the keyword, on a scale where a higher number means more competition.  Recalculated when `keyword` changes, even if you don't name this field in the field mask.  | validation: format int32
     - name: searchVolume | type: integer | description: Estimated number of searches for the keyword per month.  Recalculated when `keyword` changes, even if you don't name this field in the field mask.  | validation: format int32
     - name: pageDeleted | type: boolean | description: Whether the site page this keyword is assigned to has been deleted.  A keyword assigned to a deleted page stays in the research.  
     - name: primary | type: boolean | description: Whether this keyword is the main keyword for its page.  A page has a single main keyword, and the other keywords in its cluster support it.  
     - name: clusterName | type: string | description: Name of the cluster that groups this keyword with the others covering the same topic.  | validation: maxLength 1000
  - name: keywordResearchId | type: string | description: GUID of the keyword research these items belong to.  Send this GUID when you update an item. Compare it across reads to detect that a newer generation replaced the research.  | validation: format GUID
  - name: createdByUser | type: boolean | description: Whether this research has been edited.  `false` means the research is exactly as the content plan generated it, so the next edit copies it onto a new `keywordResearchId`.  
  - name: mainKeywordMap | type: object | description: GUID of the main keyword for each page, keyed by page GUID.  Built from the site's full item set, so on a paged response it can name items that aren't in `keywordResearchItems`.  | validation: format map
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata.  
     - name: count | type: integer | description: Items returned in this page.  | validation: format int32
     - name: cursors | type: Cursors | description: Cursors for next/previous page.  
        - name: next | type: string | description: Cursor for the next page.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor for the previous page.  | validation: maxLength 16000
     - name: hasNext | type: boolean | description: Whether there are more pages.  


```

### Examples

### List the keywords behind the site's content plan
Returns the site's most recent keyword research. Omit paging to receive every item in one response.

```curl
curl -X GET \
'https://www.wixapis.com/seo-content-plan-service/v1/content-plan-keyword-research-items' \
-H 'Authorization: <AUTH>'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.seo.keywordResearch.listKeywordResearchItems(options)
 Description: Retrieves the keyword research behind the site's current content plan.  Returns the research produced by the last completed generation. Research from a generation that's still running, or that failed, isn't readable. Poll Get Content Plan Flow until its status is `SUCCESS`, then call this method.  The result is scoped to the site rather than to a flow. This method always returns the site's most recent research and can't target an earlier one. If another generation finishes between your trigger and this read, you receive the newer research instead. Compare `keywordResearchId` across reads to detect that the research was replaced.  Omit `paging` to return every item in a single response. When `paging` is present, `limit` accepts 1 to 100 and defaults to 50.  A site with no keyword research returns a not found error rather than an empty list.
 Method parameters:
   param name: options | type: ListKeywordResearchItemsOptions  none  
        - name: contentPlanFlowId | type: string | description: Reserved for future use.  This method currently resolves the site's most recent keyword research, and this field is ignored.  | validation: format GUID
        - name: paging | type: CursorPaging | description: Cursor paging. Omit for the first page.  Omit this object entirely to return every item in a single response.  
           - name: limit | type: integer | description: Max items per page. Default 50, max 100.  | validation: minimum 0, maximum 100, format int32
           - name: cursor | type: string | description: Cursor from a previous response. Omit for the first page.  | validation: maxLength 16000
 Return type: PROMISE<ListKeywordResearchItemsResponse>
  - name: keywordResearchItems | type: array<KeywordResearch> | description: Retrieved keyword research items.  | validation: maxItems 1000
     - name: _id | type: string | description: Keyword research item GUID.  | read-only: true | validation: format GUID
     - name: keyword | type: string | description: The keyword itself.  An update is rejected if the new keyword is longer than 80 characters, or if it duplicates another keyword in the same research.  | validation: maxLength 1000
     - name: pageId | type: string | description: GUID of the site page the keyword is assigned to.  | validation: maxLength 1000
     - name: itemType | type: string | description: Type of the site page the keyword is assigned to, such as a static page or a blog post.  | validation: maxLength 1000
     - name: pageUrl | type: string | description: URL of the site page the keyword is assigned to.  | validation: maxLength 1000
     - name: competition | type: integer | description: How hard it is to rank for the keyword, on a scale where a higher number means more competition.  Recalculated when `keyword` changes, even if you don't name this field in the field mask.  | validation: format int32
     - name: searchVolume | type: integer | description: Estimated number of searches for the keyword per month.  Recalculated when `keyword` changes, even if you don't name this field in the field mask.  | validation: format int32
     - name: pageDeleted | type: boolean | description: Whether the site page this keyword is assigned to has been deleted.  A keyword assigned to a deleted page stays in the research.  
     - name: primary | type: boolean | description: Whether this keyword is the main keyword for its page.  A page has a single main keyword, and the other keywords in its cluster support it.  
     - name: clusterName | type: string | description: Name of the cluster that groups this keyword with the others covering the same topic.  | validation: maxLength 1000
  - name: keywordResearchId | type: string | description: GUID of the keyword research these items belong to.  Send this GUID when you update an item. Compare it across reads to detect that a newer generation replaced the research.  | validation: format GUID
  - name: createdByUser | type: boolean | description: Whether this research has been edited.  `false` means the research is exactly as the content plan generated it, so the next edit copies it onto a new `keywordResearchId`.  
  - name: mainKeywordMap | type: object | description: GUID of the main keyword for each page, keyed by page GUID.  Built from the site's full item set, so on a paged response it can name items that aren't in `keywordResearchItems`.  | validation: format map
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata.  
     - name: count | type: integer | description: Items returned in this page.  | validation: format int32
     - name: cursors | type: Cursors | description: Cursors for next/previous page.  
        - name: next | type: string | description: Cursor for the next page.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor for the previous page.  | validation: maxLength 16000
     - name: hasNext | type: boolean | description: Whether there are more pages.  


```

### Examples

### Read the site's current keyword research
Returns the keywords behind the site's most recent successful content plan generation. Omit `paging` to get every item in one response.

```javascript
import { keywordResearch } from "@wix/seo";

async function listKeywordResearchItems() {
  const response = await keywordResearch.listKeywordResearchItems({
    paging: { limit: 10 },
  });
}

/* Promise resolves to:
 * {
 *   "keywordResearchItems": [
 *     {
 *       "_id": "c5f9e1a4-7b62-4d18-9a35-1e8f4c2d6b70",
 *       "keyword": "handmade ceramic mugs",
 *       "pageId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
 *       "itemType": "STATIC_PAGE",
 *       "pageUrl": "https://example.com/shop",
 *       "competition": 34,
 *       "searchVolume": 2900,
 *       "pageDeleted": false,
 *       "primary": true,
 *       "clusterName": "ceramic drinkware"
 *     },
 *     {
 *       "_id": "d7a341c4-196b-46e7-813c-2b0fc1847ec6",
 *       "keyword": "glazed stoneware mug",
 *       "pageId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
 *       "itemType": "STATIC_PAGE",
 *       "pageUrl": "https://example.com/shop",
 *       "competition": 21,
 *       "searchVolume": 480,
 *       "pageDeleted": false,
 *       "primary": false,
 *       "clusterName": "ceramic drinkware"
 *     }
 *   ],
 *   "keywordResearchId": "8f3b6d2e-4c17-4a90-b5e3-9d70c1af2b48",
 *   "createdByUser": false,
 *   "mainKeywordMap": {
 *     "a1b2c3d4-e5f6-4890-abcd-ef1234567890": "c5f9e1a4-7b62-4d18-9a35-1e8f4c2d6b70"
 *   },
 *   "pagingMetadata": {
 *     "count": 2,
 *     "cursors": {},
 *     "hasNext": false
 *   }
 * }
 */

```

### listKeywordResearchItems (self-hosted)
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.md).

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

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


async function listKeywordResearchItems(options) {
  const response = await myWixClient.keywordResearch.listKeywordResearchItems(options);
};
```

---