# \[$1.00/1k] AliExpress Everything (`cocoa_kit/aliexpress-everything`) Actor

Collect AliExpress listings, product details, variants, seller data, and reviews.

- **URL**: https://apify.com/cocoa_kit/aliexpress-everything.md
- **Developed by:** [Cocoa Kit](https://apify.com/cocoa_kit) (community)
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 aliexpress results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### AliExpress Everything

Collect AliExpress listings, product details, seller data, and public reviews. Start with a search term or a search, category, or product URL. The Actor writes one dataset row per product or review. Use Apify Console to export JSON, CSV, Excel, or XML. You can also run the Actor through the Apify API or on a schedule.

#### Quick start

1. Enter a search term in `searchQuery`, or add URLs to `startUrls`.
2. Set `shipCountry` and `maxResults`.
3. Enable `detailedItems` for specifications and variants. Enable `includeReviews` for reviews.
4. Run the Actor. Check the run result and the dataset.

```json
{
    "searchQuery": "wireless earbuds",
    "maxResults": 50,
    "shipCountry": "US"
}
```

For a known product and its reviews:

```json
{
    "startUrls": [{ "url": "https://www.aliexpress.us/item/3256811621288203.html" }],
    "includeReviews": true,
    "maxReviews": 25,
    "shipCountry": "US"
}
```

Direct product URLs always request details. `detailedItems` controls whether the Actor opens products found on listing pages.

### Input

| Field                | Function                                                    | Default                                       |
| -------------------- | ----------------------------------------------------------- | --------------------------------------------- |
| `searchQuery`        | Search text. Set this or `startUrls`.                       | None                                          |
| `startUrls`          | HTTPS search, category, or product URLs.                    | `[]`                                          |
| `maxResults`         | Maximum unique listing and product rows, from 1 to 5,000.   | `50`                                          |
| `detailedItems`      | Get details for products found in listings.                 | `false`                                       |
| `includeReviews`     | Get public review text, country, date, variant, and images. | `false`                                       |
| `maxReviews`         | Maximum reviews per product, from 1 to 1,000.               | `20`                                          |
| `site`               | AliExpress regional site. See the input form for the list.  | `aliexpress.com`                              |
| `shipCountry`        | Two-letter delivery country.                                | `US`                                          |
| `currency`           | Optional currency override.                                 | Country currency, or USD if no mapping exists |
| `proxyConfiguration` | Apify automatic proxy selection or custom proxy settings.   | Apify automatic                               |
| `maxConcurrency`     | Concurrent requests, from 1 to 5.                           | `1`                                           |
| `maxRequestRetries`  | Retries for a failed request.                               | `2`                                           |
| `requestDelaySecs`   | Delay before each HTTP request.                             | `1`                                           |
| `requestTimeoutSecs` | Timeout for a network request or browser navigation.        | `60`                                          |
| `maxPages`           | Maximum listing pages for each source URL.                  | `100`                                         |

The Actor sends the selected country and currency to AliExpress. Prices can depend on delivery address, stock, tax, sale conditions, and new-customer offers. The output currency comes from the response. The Actor does not convert prices. Conditional free-gift offers can have no standalone price. In that case, `price` is `null`, `priceNote` contains the condition, and the row has a warning. The `site` field identifies the selected site; AliExpress can redirect to another regional site.

### Output

All rows contain `recordType`, `productId`, `site`, `shipCountry`, `scrapedAt`, and `_warnings`.

Listing and product rows contain:

- `productUrl`, `title`, `price`, `originalPrice`, `discountPercent`, `currency`, and `priceNote`.
- `rating`, `reviewsCount`, and `ordersCount` when the source supplies numeric values.
- `imageUrl`, `images`, `storeName`, `storeUrl`, and `storeId`.
- `specifications`, `variants`, `description`, and `detailStatus`.

Each specification contains `name` and `value`. Each variant contains `skuId`, `attributes`, `price`, `currency`, `stock`, and `available`. IDs remain strings. The Actor leaves an unknown scalar field as `null` and an unavailable list as `[]`. Description text is available only when page data includes it. It does not download separate description documents.

Review rows contain `reviewId`, `reviewRating`, `reviewText`, `reviewerCountry`, `reviewDate`, `reviewSku`, `reviewImages`, and `reviewScope`. Ratings use a five-star scale. Dates keep the source format. Names, account IDs, profile images, and profile links are excluded. Review text and product photos are collected only when `includeReviews` is enabled.

AliExpress can combine reviews for similar items from different sellers. When it gives this notice, `reviewScope` stores the notice and `_warnings` includes `reviews_may_include_similar_products`.

#### Run result

The `OUTPUT` key-value record contains `outcome`, product and review counts, failed request count, partial product count, page count, warnings, and start and finish times.

- `SUCCEEDED`: requested pages completed without a known data failure.
- `EMPTY`: AliExpress returned a valid listing response with no products.
- `PARTIAL`: some data is incomplete, a page limit stopped the search, or a request failed.
- `FAILED`: no result could be obtained from the failed requests.
- `ABORTED`: the run was stopped. State was saved before exit.

`MIGRATING` is a temporary state while Apify moves the run. A request that exhausts its retries causes a failed platform run, even if other requests returned data. A blocked product page with valid listing data returns `PARTIAL`; it is not presented as a complete product.

#### Blocked or unavailable pages

AliExpress can return verification pages or remove a product. The Actor retries failed requests. If a product page stays blocked, it can use a previously collected listing, with `detailStatus: "blocked"` and `detail_page_blocked_used_listing_data`. If there is no matching listing, it records a failed request. It does not invent a title, price, seller, or variant. No scraper can guarantee access to every product at all times.

### Cost and limits

Apify compute, storage, and proxy charges apply. This source does not charge a separate result event or call another paid Actor. Start with a small run. Browser requests cost more than listing and review requests. Keep concurrency at 1 for detail runs with 2 GB of memory. Increase memory before you increase browser concurrency. `maxResults` limits products; reviews have a separate per-product limit. A run can therefore produce up to `maxResults × (1 + maxReviews)` rows when reviews are enabled.

### Development

Use Node.js 22 or later. The existing Docker image includes Camoufox and Playwright. Put local input in `storage/key_value_stores/default/INPUT.json`, then use `apify run`. Use `apify run --no-purge` to keep existing local storage. For a separate test, set `CRAWLEE_STORAGE_DIR` to a new folder that contains its own `key_value_stores/default/INPUT.json`.

Run `npm test`, `npm run build`, `npm run lint`, and `apify validate-schema` before deployment. Local files do not prove platform behavior. Check a platform run and its dataset after each deployment.

The crawler checks robots.txt and adds a request delay. Use public data within the site's terms and the permissions that apply to your use. This Actor is independent of AliExpress.

# Actor input Schema

## `searchQuery` (type: `string`):

Find products with this search text.

## `startUrls` (type: `array`):

Start from HTTPS AliExpress search, category, or product URLs.

## `maxResults` (type: `integer`):

Maximum number of unique product or listing rows. Reviews have a separate limit.

## `detailedItems` (type: `boolean`):

Open each product page for specifications, variants, images, and seller data.

## `includeReviews` (type: `boolean`):

Collect public review text, country, date, purchased variant, and images. Names and profile data are excluded.

## `maxReviews` (type: `integer`):

Maximum number of review rows for each product.

## `site` (type: `string`):

Select the site and page language.

## `shipCountry` (type: `string`):

Two-letter country code. The Actor sends this market to AliExpress.

## `currency` (type: `string`):

Optional three-letter currency code. If blank, use the normal currency for the ship-to country, or USD if no mapping is available.

## `proxyConfiguration` (type: `object`):

Use the existing automatic Apify proxy selection, or supply your own settings. Proxy usage can have a cost.

## `maxConcurrency` (type: `integer`):

Maximum requests at the same time. Product requests can start a browser.

## `maxRequestRetries` (type: `integer`):

Number of retries after the first request fails.

## `requestDelaySecs` (type: `integer`):

Delay in seconds before each HTTP request.

## `requestTimeoutSecs` (type: `integer`):

Timeout in seconds for one network request or browser navigation.

## `maxPages` (type: `integer`):

Stop each search or category at this page limit.

## Actor input object example

```json
{
  "searchQuery": "wireless earbuds",
  "startUrls": [],
  "maxResults": 50,
  "detailedItems": false,
  "includeReviews": false,
  "maxReviews": 20,
  "site": "aliexpress.com",
  "shipCountry": "US",
  "currency": "",
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "maxConcurrency": 1,
  "maxRequestRetries": 2,
  "requestDelaySecs": 1,
  "requestTimeoutSecs": 60,
  "maxPages": 100
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `summary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchQuery": "wireless earbuds"
};

// Run the Actor and wait for it to finish
const run = await client.actor("cocoa_kit/aliexpress-everything").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "searchQuery": "wireless earbuds" }

# Run the Actor and wait for it to finish
run = client.actor("cocoa_kit/aliexpress-everything").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQuery": "wireless earbuds"
}' |
apify call cocoa_kit/aliexpress-everything --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,cocoa_kit/aliexpress-everything"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ERnXWxT9oLPAr3pv6/builds/h63zyfDyJi8RmvY7y/openapi.json