AliExpress Keyword Search

Search public AliExpress product listings by keyword.

API selector

What this API does

Search public AliExpress product listings by keyword. Send a keyword of up to 120 normalized characters; use pageNum (1–20) and limit (1–100) to bound the search. The response provides a taskId. Poll GET /aliexpress/tasks/{taskId} with the same Nexscope API key to retrieve the completed product results. The request accepts keyword, pageNum, limit. Its documented result includes error. Generation runs as a task: retain the task ID and retrieve the completed result before using the output.

AliExpress Keyword Search API use cases

Submit a AliExpress Keyword Search request

Search public AliExpress product listings by keyword. Send a keyword of up to 120 normalized characters; use pageNum (1–20) and limit (1–100) to bound the search.

Retrieve the completed result

Keep the taskId from the initial response. Poll GET /aliexpress/tasks/{taskId} with the same Nexscope API key to retrieve the completed product results.

AliExpress Keyword Search API FAQ

What does the AliExpress Keyword Search API return?

Search public AliExpress product listings by keyword. The initial response includes a taskId and status. Use the task result endpoint to retrieve the completed result.

How many credits does the AliExpress Keyword Search API cost?

Published rate: At least 10 credits / call. Actual credits depend on the request; review API usage records after completion. Looking up a task result does not start another collection.

How do I call the AliExpress Keyword Search API?

Send a POST request to https://api.nexscope.ai/aliexpress/productSearch with your Nexscope API key in the Authorization Bearer header and the documented JSON inputs. Poll GET /aliexpress/tasks/{taskId} with the same Nexscope API key to retrieve the completed product results.

View plans and credits Connect this API with MCP

Try this API

Endpoint

https://api.nexscope.ai/aliexpress/productSearch

MCP method

nexscope_aliexpress_product_search

Authentication

Use an API key to authenticate your requests.

Authorization: Bearer YOUR_API_KEY

Task result

Poll the returned task ID with the same Nexscope API key.

GET /aliexpress/tasks/{taskId}

POSThttps://api.nexscope.ai/aliexpress/productSearch

Run an API

Send a JSON request body using the parameters described below.

Slug	`aliexpress-product-search`
Headers	`Authorization: Bearer nk-...` `Content-Type: application/json`
Request body	API-specific JSON object.
Response body	Platform envelope: code, msg, data, ts, time, cost, traceId. Inspect data.status for asynchronous completion.

Status codes

Code	Description
200	Default HTTP response for both success and many business errors. Only outer JSON code 0 indicates success or asynchronous acceptance; inspect data for the result.
429	Execution admission rate limit; honor Retry-After when present.
503	Execution admission is temporarily unavailable; honor Retry-After when present.
Opt-in	X-Nexscope-Http-Status: semantic maps controller-handled business errors to HTTP status on run and task routes. Pre-authentication failures, such as a missing or invalid API key (code 11209, including an incomplete or corrupted copy) or an expired website login session (code 12001), may still return HTTP 200 before this mapping. Always check the outer JSON code; malformed requests and infrastructure failures may also return non-200 HTTP responses.

Example request

Replace YOUR_API_KEY, then run this command in your terminal.

curl -X POST 'https://api.nexscope.ai/aliexpress/productSearch' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "wireless earbuds",
  "pageNum": 1,
  "limit": 1
}'

Code example

Try this request →

Replace YOUR_API_KEY, then run this command in your terminal.

curl -X POST 'https://api.nexscope.ai/aliexpress/productSearch' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "wireless earbuds",
  "pageNum": 1,
  "limit": 1
}'

All categories/ AliExpress

POSThttps://api.nexscope.ai/aliexpress/productSearch

Run this API

Send a JSON request to execute this API and receive the documented response payload.

Open tester

Endpoint

Method	`POST`
Path	`https://api.nexscope.ai/aliexpress/productSearch`
Auth	`Bearer API key`
Content-Type	`application/json`

Request parameters

Name	Type	Required	Description
`keyword`	`string`	required	required string, up to 120 normalized characters
`pageNum`	`integer`	optional	integer 1–20, default 1
`limit`	`integer`	optional	integer 1–100, default 20.

Response example

Platform response envelope. code 0 indicates success or acceptance; data contains the business result.

{
  "code": 0,
  "data": {
    "taskId": "TASK_ID",
    "status": "SUBMITTING",
    "result": null,
    "usage": {
      "billingStatus": "PENDING",
      "chargedCredits": 0
    },
    "error": null
  }
}

Response fields

Name	Type	Required	Description
`code`	`integer`	optional	0 means the tool call succeeded; nonzero is a Nexscope error.
`msg`	`string \| null`	optional	Msg value used by this API operation.
`data`	`object \| null`	optional	Data value used by this API operation.
`data.taskId`	`string`	required	Use this identifier with the corresponding AliExpress MCP task result tool.
`data.status`	`string`	required	The current task state; a successful tool call does not mean collection has finished.
`data.result`	`any`	optional	Provider result when available; null while pending or when no verified result exists.
`data.usage`	`object`	required	Usage value used by this API operation.
`data.usage.billingStatus`	`string`	optional	Billing status value used by this API operation.
`data.usage.chargedCredits`	`integer`	optional	Charged credits value used by this API operation.
`data.error`	`string \| null`	optional	Error value used by this API operation.
`ts`	`integer`	optional	Ts value used by this API operation.
`time`	`string`	optional	Time value used by this API operation.
`cost`	`integer`	optional	Cost value used by this API operation.
`traceId`	`string \| null`	optional	Trace id value used by this API operation.

Responses

Code	Description
200	Default HTTP response for both success and many business errors. Only outer JSON code 0 indicates success or asynchronous acceptance; inspect data for the result.
429	Execution admission rate limit; honor Retry-After when present.
503	Execution admission is temporarily unavailable; honor Retry-After when present.
Opt-in	X-Nexscope-Http-Status: semantic maps controller-handled business errors to HTTP status on run and task routes. Pre-authentication failures, such as a missing or invalid API key (code 11209, including an incomplete or corrupted copy) or an expired website login session (code 12001), may still return HTTP 200 before this mapping. Always check the outer JSON code; malformed requests and infrastructure failures may also return non-200 HTTP responses.

Data source, freshness, and limitations

Source, freshness, coverage, rate limits, and estimation notes are not specified in this API definition unless they appear in the request or response field documentation above. Do not assume official marketplace data or real-time freshness when it is not explicitly documented.

MCP

Connect your agent

Copy the setup prompt and paste it into your agent. The prompt includes the selected tool when available. Your agent will check access and ask for any missing inputs before calling it.

Tool name: nexscope_aliexpress_product_search

Call the tool manually

For an existing MCP client, use the endpoint and JSON-RPC request below.

Use the MCP endpoint when an agent needs to discover and call API tools with JSON-RPC.

GET /mcp/legacy

POST /mcp/legacy
Authorization: Bearer nk-xxxxxxxxxxxxxxxxx
Content-Type: application/json

Call a tool

{
  "jsonrpc": "2.0",
  "id": "tool-call-1",
  "method": "tools/call",
  "params": {
    "name": "nexscope_aliexpress_product_search",
    "arguments": {
      "keyword": "wireless earbuds",
      "pageNum": 1,
      "limit": 1
    }
  }
}

Task result tool

Query the returned taskId with the same Nexscope API key. Result queries do not submit a new collection or charge again.

{
  "jsonrpc": "2.0",
  "id": "task-result-1",
  "method": "tools/call",
  "params": {
    "name": "nexscope_aliexpress_task_result",
    "arguments": {
      "taskId": "TASK_ID"
    }
  }
}

Data Example

Sample request and response

Request parameters

{
  "keyword": "wireless earbuds",
  "pageNum": 1,
  "limit": 1
}

Response

{
  "code": 0,
  "msg": null,
  "data": {
    "taskId": "EXAMPLE_TASK_ID",
    "status": "SUCCEEDED",
    "result": {
      "items": [
        {
          "url": "https://www.aliexpress.com/item/3256811621288203.html",
          "price": null,
          "title": "2026 New Air 3【 Pro3 】 Bluetooth Wireless Earbuds With Heart Rate Monitoring, Active Noise Cancellation Headphones, Waterproof for Daily Use, For IPhone IOS Smartphone, Gaming /Sports /Fitness Earphones.",
          "images": [],
          "currency": null,
          "priceType": null,
          "productId": "3256811621288203",
          "variantId": null,
          "collectedAt": null,
          "availability": null,
          "missingFields": [
            "images",
            "collectedAt",
            "variantId",
            "availability",
            "completeSkuMatrix",
            "price",
            "currency"
          ],
          "variantAttributes": [],
          "listingHasVariations": null,
          "variantGroups": []
        }
      ],
      "discovered": [],
      "retrievedAt": "1793687830552",
      "errorRecords": 0,
      "limitReached": true,
      "variantCoverage": "NOT_REQUESTED"
    },
    "usage": {
      "billingStatus": "CHARGED",
      "chargedCredits": "10"
    },
    "error": null
  }
}

Related APIs

AliExpress Product Detail

Collect public product details from an AliExpress product URL. Submit a supported HTTPS AliExpress product URL in url; this operation has no limit parameter. The response provides a taskId. Poll GET /aliexpress/tasks/{taskId} with the same Nexscope API key to inspect the completed product details.

AliExpress Category Discovery

Discover products from a public AliExpress category navigation URL. Submit a supported category navigation URL in url and optionally set limit (1–100, default 20) to bound the returned products. The response provides a taskId. Poll GET /aliexpress/tasks/{taskId} with the same Nexscope API key for the completed discovery results.

AliExpress Category Variants

Collect observed product variants from a public AliExpress category navigation URL. Submit a supported category URL in url; limit (1–100, default 20) bounds product groups, and one product may return several variant rows. The response provides a taskId. Poll GET /aliexpress/tasks/{taskId} with the same Nexscope API key to review the completed variant results.

AliExpress Google Organic Search

Retrieve structured Google organic search results for AliExpress research. Send a UUID requestId and keyword; pageNum (1–10) and limit (1–10) bound the result set. The response provides a taskId. Poll GET /aliexpress/accessTasks/{taskId} with the same Nexscope API key to retrieve the completed search results.