> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# AliExpress Products API

> AliExpress product listings with title, URL, price, original price, discount and currency. Search by keyword or pass product URLs.

`POST /v1/data/aliexpress/products/run`

**Pricing:** $0.0035 per product ($3.50 per 1,000).

## Ways to call it

* **Search Query**: set `query` (optional: `maxResults`, `sortBy`, `country`)
* **URL**: set `url` (optional: `maxResults`, `sortBy`, `country`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**query** `string`

Search Query.

**url** `string`

URL.

Format e.g. `https://www.example.com`.

**maxResults** `integer` (default: 100)

How many products to return in total. Defaults to 100; use 0 for all.

**sortBy** `string` (default: default)

Sort By to use. Best match by default.

Allowed values: `default` (Best match), `orders` (Most orders), `priceAsc` (Price low to high), `priceDesc` (Price high to low).

**country** `string` (default: US)

Country to use. US by default.

50 allowed values, for example `US`, `GB`, `DE`, `FR`, `ES`, `IT`, `NL`, `PL`, `PT`, `SE`. Fetch the full list with `GET /v1/data/aliexpress/products?expand=options`.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/aliexpress/products/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "query": "mechanical keyboard",
    "maxResults": 10
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/aliexpress/products/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "query": "mechanical keyboard",
    "maxResults": 10
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/aliexpress/products/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "query": "mechanical keyboard",
  "maxResults": 10
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one product, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `productId` | Product ID | text |
| `title` | Title | text |
| `productUrl` | Product URL | url |
| `price` | Price | number |
| `originalPrice` | Original Price | number |
| `discountPercent` | Discount Percent | number |
| `currency` | Currency | text |
| `rating` | Rating | rating |
| `ordersCount` | Orders Count | number |
| `isChoice` | Is Choice | boolean |
| `isAd` | Is Ad | boolean |
| `mainImage` | Main Image | image |
| `images` | Images | array |
| `categoryId` | Category ID | text |
| `listedAt` | Listed At | date |
| `searchQuery` | Search Query | text |
| `searchRank` | Search Rank | number |
| `region` | Region | text |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "aliexpress/products",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "rating": 4.8,
      "searchQuery": "mechanical keyboard",
      "productId": "1005007442133418",
      "images": [
        "https://ae-pic-a1.aliexpress-media.com/kf/Sd95e19e05c1b497a9f31cb30a76328fa9.png",
        "https://ae-pic-a1.aliexpress-media.com/kf/S29869561c32e4e2995f8d2dfc3344605q.jpg"
      ],
      "isChoice": null,
      "discountPercent": 58,
      "listedAt": "2024-07-26 00:00:00",
      "categoryId": "70802",
      "mainImage": "https://ae-pic-a1.aliexpress-media.com/kf/Sd95e19e05c1b497a9f31cb30a76328fa9.png",
      "region": "US",
      "isAd": true,
      "searchRank": 4,
      "title": "Mechanical Keyboard Hot-swappable Gaming Royal Kludge RK R75 Wired Gaming Keyboard 80 Keys 80% Gasket RGB Backlit Hot-swappable Mechanical Keyboard with MDA ...",
      "productUrl": "https://www.aliexpress.com/item/1005007442133418.html",
      "originalPrice": 143.98,
      "currency": "USD",
      "ordersCount": 250,
      "price": 60.37
    }
  ]
}
```

## Related APIs

For review text use [`aliexpress/reviews`](https://docs.mindcase.co/apis/aliexpress/reviews).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.