AliExpress Page Read

Read a bounded public AliExpress page.

API selector

What this API does

Read a bounded public AliExpress page. Send a UUID requestId with either keyword and optional pageNum (1–20), or a supported public AliExpress url. Do not combine url with keyword or pageNum. The response provides a taskId. Poll GET /aliexpress/accessTasks/{taskId} with the same Nexscope API key to retrieve the completed page result. The request accepts requestId, keyword, pageNum, url. Its documented result includes error. Generation runs as a task: retain the task ID and retrieve the completed result before using the output.

AliExpress Page Read API use cases

Submit a AliExpress Page Read request

Read a bounded public AliExpress page. Send a UUID requestId with either keyword and optional pageNum (1–20), or a supported public AliExpress url. Do not combine url with keyword or pageNum.

Retrieve the completed result

Keep the taskId from the initial response. Poll GET /aliexpress/accessTasks/{taskId} with the same Nexscope API key to retrieve the completed page result.

AliExpress Page Read API FAQ

What does the AliExpress Page Read API return?

Read a bounded public AliExpress page. The initial response includes a taskId and status. Use the task result endpoint to retrieve the completed result.

How many credits does the AliExpress Page Read 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 Page Read API?

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

View plans and credits Connect this API with MCP

Try this API

Endpoint

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

MCP method

nexscope_aliexpress_page_read

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/accessTasks/{taskId}

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

Run an API

Send a JSON request body using the parameters described below.

Slug	`aliexpress-page-read`
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/pageRead' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "requestId": "11111111-1111-4111-8111-111111111111",
  "keyword": "wireless earbuds",
  "pageNum": 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/pageRead' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "requestId": "11111111-1111-4111-8111-111111111111",
  "keyword": "wireless earbuds",
  "pageNum": 1
}'

All categories/ AliExpress

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

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/pageRead`
Auth	`Bearer API key`
Content-Type	`application/json`

Request parameters

Name	Type	Required	Description
`requestId`	`string`	required	Client-generated UUID. Reuse it when retrying an uncertain submission. Format: uuid
`keyword`	`string`	optional	The normalized keyword must be at most 120 characters. Minimum length: 1 Maximum length: 240
`pageNum`	`integer`	optional	requestId: required UUID. Supply keyword and optional pageNum (1–20), or a supported public AliExpress url. Do not combine url with keyword/pageNum. Default: 1 Minimum: 1 Maximum: 20
`url`	`string`	optional	Supported AliExpress product detail or category navigation URL. Format: uri Maximum length: 2048

One of option 1 — requires keyword

One of option 2 — requires url

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": {
      "nexscopeBillingState": "PENDING",
      "supplierChargeState": "UNVERIFIED",
      "observedBytes": 0,
      "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.nexscopeBillingState`	`string`	optional	Nexscope billing state value used by this API operation.
`data.usage.supplierChargeState`	`string`	optional	Supplier charge state value used by this API operation.
`data.usage.observedBytes`	`integer`	optional	Observed bytes 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_page_read

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_page_read",
    "arguments": {
      "requestId": "11111111-1111-4111-8111-111111111111",
      "keyword": "wireless earbuds",
      "pageNum": 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_access_task_result",
    "arguments": {
      "taskId": "TASK_ID"
    }
  }
}

Data Example

Sample request and response

Request parameters

{
  "requestId": "d55c91b1-7352-4e24-84cc-d7c248ce48e8",
  "keyword": "phone case",
  "pageNum": 1
}

Response

{
  "code": 0,
  "data": {
    "status": "SUCCEEDED",
    "result": {
      "page": {
        "title": "",
        "finalUrl": "https://www.aliexpress.com/w/wholesale.html?SearchText=phone+case&page=1",
        "productLinks": [],
        "outcome": "READ",
        "stopReason": "DOCUMENT_READ",
        "observedBytes": 0,
        "text": "Help\nCustomer Service\nDisputes & Reports\nReport IPR infringement\nBuyer Protection\nApp\n?\nShip to\nLanguage\nCurrency\nSave\nCart\nWish List\nAccount\n\nWelcome to AliExpress!\n\nWelcome back\n\nSign Out\n\nJoin Sign in\n\n?\nMy Orders\nMessage Center\nWish List\nMy Favorite Stores\nMy Coupons",
        "requestedUrl": "https://www.aliexpress.com/w/wholesale.html?SearchText=phone+case&page=1"
      }
    }
  }
}

Related APIs

AliExpress Keyword Search

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.

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.