# Taobao Reviews API (taobao.reviews)

- Canonical page: https://everyinfra.com/en/taobao-api/reviews
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "taobao", "action": "reviews", "params": {...}}
- Price: $0.005556 per call ($5.56 per 1,000 requests); failed calls and empty results are not charged
- Billing unit: every 20 rows you ask for count as one call; blocks that come back with no rows are not charged
- Returns: list, default 20, max 100 per call
- Pagination: pass next_page_token back as page_token for the next page, other params unchanged; each page is billed by its row count, one call per 20 rows, tokens last 24 hours
- Mode: sync; add "mode": "async" for slow tasks

Taobao Reviews reads buyer reviews for one product: the review text, rating, publish time, the variant purchased, the buyer's nickname, images, and the seller's reply. Use it to learn whether buyers are satisfied and where complaints cluster, for reputation analysis, tracing negative reviews to causes, or pulling selling points and pain points from a competitor's product.

`url` takes the same product identifiers as Product details: a numeric ID, a product link or share text with exactly one product link. `sku` ties each review to a specific variant, so you can compare feedback across colors or sizes, and `seller_reply` shows how the shop handles criticism. Check `rating_scale` on the same row before comparing ratings.

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=taobao&action=reviews

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| url | not declared | yes | not declared | For product_detail, reviews, or questions, use a numeric item ID, a Taobao/Tmall product URL, or a share message containing exactly one product URL. e.tb.cn and m.tb.cn links work only when they can be safely resolved to a product page. TaoPassword-only tokens, expired links, and non-product pages are rejected. |
| page | integer | no | not declared | Page number of the item's reviews, from 1 to 50, newest first, usually 20 reviews per page and fewer on the last. With `page`, you get that whole page directly and `limit` has no effect; without it, paging starts at page 1 as before and continues with `next_page_token`. Each page is billed as one call; a page past the last one returns an empty result and is not charged. Taobao shows at most the first 1,000 reviews of an item (page 50), so pages above 50 are rejected before charging. `pagination.has_more` true means there is a next page: ask for `page` + 1, or pass `next_page_token` back as `page_token`. When both `page` and `page_token` are sent, `page_token` wins. If new reviews arrive while you page, neighbouring pages can repeat a review or two, so dedupe by review `id` when merging. |
| page_token | not declared | no | not declared | Page token. Leave it out for the first page. When the response has a `next_page_token`, pass it back as `page_token`, exactly as received, to get the next page, with the other parameters unchanged (`limit` can change). You can also skip the token and ask for a page number with `page`; when both are sent, `page_token` wins. A token is valid for 24 hours and works only for the same product and the same account; a token used with another product is rejected with 422 and not charged. No `next_page_token` (or `pagination.has_more` false) means you have reached the end. Each page returns `limit` reviews (default 20, up to 100), and the next page continues after the last review returned. Reviews are newest first; if new reviews arrive while you page, neighbouring pages can repeat a review or two, so dedupe by review `id` when merging. Each page is billed on its own by its row count, one call per 20 rows (20 rows is one call, 21–40 is two, 100 is five); calls not used because fewer rows came back are refunded, and an empty page is not charged. |
| limit | integer (1–100) | no | 20 | The most rows to return in this call, an integer from 1 to 100. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge. |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| id | The record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms. |
| text | Body text with HTML removed, returned in full and never cut short (on a few platforms the list results themselves carry only an excerpt; the platform's field notes say so). |
| rating | Rating. **The scale varies by platform**: rating_scale on the same row gives the maximum (usually 5; Booking, Douban, iQIYI and NAVER use 10). Convert with rating_scale before comparing across platforms, or the comparison can come out backwards. |
| rating_scale | Maximum of rating in the same row: 5 for five-star scales, 10 for ten-point scales. Present only when the row has a rating. |
| posted_at | Publish time in ISO 8601, UTC (for example 2026-08-07T12:34:56+00:00). Non-standard strings from the platform are passed through as is, so parse defensively. null means the platform does not disclose it. |
| sku | Variant the buyer purchased (reviews), such as color or size, as written on the review. |
| buy_count | How many times the reviewer bought the product, as shown on the review. |
| useful_count | How many times the review was marked useful. |
| author_name | Author's display name. |
| author_avatar_url | Reviewer avatar link (reviews). |
| images | Image links: product photos on product_detail, the buyer's photos on reviews (absent when the review has none). |
| review_append | Buyer's follow-up (appended) review text. Several follow-ups are joined with line breaks in posting order; the field is absent when there is none. |
| platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |
| next_page_token | Page token: pass it back unchanged as `page_token`, with the other parameters the same, to fetch the next page; valid for 24 hours and only for the same product. Every row of a page carries the same value, which also appears at the top level of the response. Absent on the last page. |
| seller_reply | The seller's reply to the review; absent when there is none. |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "taobao",
  "action": "reviews",
  "params": {
    "url": "https://item.taobao.com/item.htm?id=744983869996"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "taobao",
        "action": "reviews",
        "params": {
            "url": "https://item.taobao.com/item.htm?id=744983869996",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-09-26T08:56:04Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "taobao",
  "action": "reviews",
  "results": [
    {
      "text": "質量過關，用着挺放心的，之前那個用了幾年時間，用不了，綠聯質量太好了",
      "rating": 5,
      "posted_at": "2026.08.27 21:28",
      "platform": "taobao",
      "rating_scale": 5
    }
  ],
  "next_page_token": …,
  "pagination": { … },
  "count": 1,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### Can I separate reviews by variant?

Yes. `sku` on each review is the variant the buyer purchased, so grouping by it compares feedback across colors, sizes or bundles. `useful_count`, the number of times a review was marked useful, helps you pick the most informative ones.

### How do I see how a shop responds to complaints?

Read `seller_reply`, the seller's reply to that review. Reading low ratings next to the replies shows which problems keep coming up and how the shop usually deals with them.

### Can I page through reviews or jump to a page, and how is it billed?

Yes, two ways. By page number: pass `page` (1–50) to get that page directly, usually 20 reviews; each page is one call and `limit` has no effect. By token: pass the response's `next_page_token` back unchanged as `page_token`; each page returns `limit` reviews (default 20, up to 100), billed one call per 20 reviews, and calls not used because fewer reviews came back are refunded. Either way, a `next_page_token` in the response means there is a next page, an empty page is not charged, and `page_token` wins when both are sent. Taobao shows at most the first 1,000 reviews of an item.

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=taobao
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
