IMPORTANT ASYNCHRONOUS TASK WORKFLOW
- Call this MCP generation tool once and read taskId from structuredContent.
- Do not call the generation tool again while the task is PENDING or RUNNING.
- Wait at least 5 seconds, then call nexscope_media_task_result with skillSlug set to seo-shopping-products, the exact taskId, and the same bearer API key. While the task remains PENDING or RUNNING, use 5, 10, 20, and 30-second progressive backoff. Never query more often than once every 5 seconds.
- Stop querying when the task succeeds or fails. On success, return the final Nexscope resource URLs and the returned count as the actual charged credits.
- Never invent a taskId and never expose internal provider names or provider resource URLs.
Search Results Rankings
Shopping Products MCP Tool
A bounded Google Shopping product search with observed product references and explicit missing evidence. One submit and at most eight fixed reads. Missing values are not zero. Prices and publication are unapproved. Owner-only historical results are retained seven days.
MCP tool name
nexscope_seo_shopping_productsLegacy MCP endpoint
/api/skill-api/v1/mcpJSON-RPC method
tools/callAuthentication
Send the user API key as a bearer token on every MCP JSON-RPC request.
Authorization: Bearer nk-xxxxxxxxxxxxxxxxxIf authentication is missing or invalid, ask the user to open API Access and copy a valid key before calling this tool.
Call this MCP tool
Use tools/call with the MCP tool name below. The arguments object should match the table on this page.
{
"jsonrpc": "2.0",
"id": "seo-shopping-products-1",
"method": "tools/call",
"params": {
"name": "nexscope_seo_shopping_products",
"arguments": {
"keyword": "Reusable packaging"
}
}
}Legacy endpoint
POST /api/skill-api/v1/mcpCanonical detail URL
https://www.nexscope.ai/mcp-map/seo-shopping-productsAsynchronous task workflow
This capability uses a create-and-query flow. Creating the task and retrieving its final generated resources are two connected requests.
- 1. Create onceCall the MCP tool once and keep the returned
taskId. - 2. Query with backoffCall
nexscope_media_task_resultwith this skill slug and task ID. Wait at least 5 seconds first; while pending or running, back off at 5, 10, 20, then 30-second intervals. - 3. Use final resultStop at a terminal status. Successful results contain Nexscope resource URLs and the actual charged-credit count.
MCP task result call
{
"jsonrpc": "2.0",
"id": "seo-shopping-products-result-1",
"method": "tools/call",
"params": {
"name": "nexscope_media_task_result",
"arguments": {
"skillSlug": "seo-shopping-products",
"taskId": "TASK_ID_FROM_THE_GENERATION_RESULT"
}
}
}REST fallback
GET https://api.nexscope.ai/api/skill-api/v1/skills/seo-shopping-products/tasks/{taskId}Arguments
No arguments are defined for this tool.
Response fields
Treat structuredContent as the programmatic API response payload.
| Name | Type | Required | Description |
|---|---|---|---|
data | any | required | Data value used by this API operation. |
code | integer | required | 0 means accepted or successful; nonzero is a platform error. |
msg | string | null | required | Msg value used by this API operation. |
ts | string | required | Epoch milliseconds. |
time | string | required | Server local time: yyyy-MM-dd HH:mm:ss. |
cost | string | required | Elapsed milliseconds, never credits; -1 outside web requests. |
traceId | string | null | required | Trace id value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data | any | required | Data value used by this API operation. |
One of option 1 — requires callId, status, result
| Name | Type | Required | Description |
|---|---|---|---|
data | object | required | Data value used by this API operation. |
data.result | any | required | Result value used by this API operation. |
data.callId | string | required | Call id value used by this API operation. |
data.schemaVersion | string | optional | Schema version value used by this API operation. |
data.status | string | required | Status value used by this API operation. |
data.source | string | optional | Source value used by this API operation. |
data.requestedAt | string | integer | null | optional | Requested at value used by this API operation. |
data.completedAt | string | integer | null | optional | Completed at value used by this API operation. |
data.coverage | object | null | optional | Coverage value used by this API operation. |
data.usage | object | null | optional | Usage value used by this API operation. |
data.usage.billingStatus | string | null | optional | Billing status value used by this API operation. |
data.usage.chargedCredits | string | integer | null | optional | Charged credits value used by this API operation. |
Any of option 1 — requires meta, keyword, products
| Name | Type | Required | Description |
|---|---|---|---|
data.result | object | required | Result value used by this API operation. |
data.result.meta | object | required | Meta value used by this API operation. |
data.result.meta.source | string | required | Source value used by this API operation. Constant: DATAFORSEO_GOOGLE_SHOPPING_PRODUCTS |
data.result.meta.sampledAt | any | required | Sampled at value used by this API operation. |
data.result.meta.retrievedAt | any | required | Retrieved at value used by this API operation. |
data.result.meta.market | object | required | Market value used by this API operation. |
data.result.meta.market.country | string | required | Country value used by this API operation. Constant: US |
data.result.meta.market.locationCode | integer | required | Location code value used by this API operation. Constant: 2840 |
data.result.meta.market.language | string | required | Language value used by this API operation. Constant: en |
data.result.meta.truncated | boolean | required | Truncated value used by this API operation. |
data.result.meta.missing | array | required | Missing value used by this API operation. Maximum items: 100 |
data.result.meta.missing[] | object | required | Item in data result meta missing. |
data.result.meta.missing[].path | string | required | Path value used by this API operation. Maximum length: 256 |
data.result.meta.missing[].reason | string | required | Reason value used by this API operation. Allowed: MISSING, NULL, INVALID, UNSUPPORTED, TRUNCATED |
data.result.meta.missingOverflow | boolean | required | Missing overflow value used by this API operation. |
data.result.keyword | string | required | Keyword value used by this API operation. Maximum length: 200 |
data.result.products | array | required | Products value used by this API operation. Maximum items: 40 |
data.result.products[] | object | required | Item in data result products. |
data.result.products[].productRef | string | required | Product ref value used by this API operation. Pattern: ^[0-9a-f]{64}$ |
data.result.products[].title | any | required | Title value used by this API operation. |
data.result.products[].description | any | required | Description value used by this API operation. |
data.result.products[].shoppingUrl | any | required | Shopping url value used by this API operation. |
data.result.products[].price | any | required | Price value used by this API operation. |
data.result.products[].oldPrice | any | required | Old price value used by this API operation. |
data.result.products[].currency | any | required | Currency value used by this API operation. |
data.result.products[].installmentMonths | any | required | Installment months value used by this API operation. |
data.result.products[].seller | any | required | Seller value used by this API operation. |
data.result.products[].domain | any | required | Domain value used by this API operation. |
data.result.products[].rankGroup | any | required | Rank group value used by this API operation. |
data.result.products[].rankAbsolute | any | required | Rank absolute value used by this API operation. |
data.result.products[].detailEligible | boolean | required | Detail eligible value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.meta.sampledAt | integer | required | Sampled at value used by this API operation. Minimum: 0 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.meta.sampledAt | null | required | Sampled at value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.meta.retrievedAt | integer | required | Retrieved at value used by this API operation. Minimum: 0 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.meta.retrievedAt | null | required | Retrieved at value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].title | string | required | Title value used by this API operation. Maximum length: 1024 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].title | null | required | Title value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].description | string | required | Description value used by this API operation. Maximum length: 8192 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].description | null | required | Description value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].shoppingUrl | string | required | Shopping url value used by this API operation. Maximum length: 4096 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].shoppingUrl | null | required | Shopping url value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].price | number | required | Price value used by this API operation. Minimum: 0 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].price | null | required | Price value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].oldPrice | number | required | Old price value used by this API operation. Minimum: 0 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].oldPrice | null | required | Old price value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].currency | string | required | Currency value used by this API operation. Pattern: ^[A-Z]{3}$ |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].currency | null | required | Currency value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].installmentMonths | integer | required | Installment months value used by this API operation. Minimum: 0 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].installmentMonths | null | required | Installment months value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].seller | string | required | Seller value used by this API operation. Maximum length: 1024 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].seller | null | required | Seller value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].domain | string | required | Domain value used by this API operation. Maximum length: 1024 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].domain | null | required | Domain value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].rankGroup | integer | required | Rank group value used by this API operation. Minimum: 0 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].rankGroup | null | required | Rank group value used by this API operation. |
Any of option 1
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].rankAbsolute | integer | required | Rank absolute value used by this API operation. Minimum: 0 |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result.products[].rankAbsolute | null | required | Rank absolute value used by this API operation. |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data.result | null | required | Result value used by this API operation. |
One of option 2 — requires callId, status, reason, retryable
| Name | Type | Required | Description |
|---|---|---|---|
data | object | required | Data value used by this API operation. |
data.reason | string | required | Reason value used by this API operation. |
data.callId | string | null | required | Call id value used by this API operation. |
data.status | string | required | Status value used by this API operation. |
data.retryable | boolean | required | Retryable value used by this API operation. |
data.taskId | string | null | optional | Task id value used by this API operation. |
Any of option 2
| Name | Type | Required | Description |
|---|---|---|---|
data | null | required | Data value used by this API operation. |
Examples
Example arguments
{
"keyword": "Reusable packaging"
}Example structuredContent
{
"data": {
"status": "PROCESSING",
"retryable": false,
"reason": "IN_PROGRESS",
"callId": "00000000-0000-4000-8000-000000000001"
},
"code": 0,
"msg": null,
"ts": "0",
"time": "2026-01-01 00:00:00",
"cost": "-1",
"traceId": null
}