{
  "openapi": "3.0.1",
  "info": {
    "title": "Taobao Product Analyzer — Bulk CSV Export & API",
    "description": "Analyze Taobao/Tmall product evidence and supplied datasets. Full native collection can require your cookies. Bulk export: JSON, CSV, Excel and API. PPE: from $4.25/1K product analyses; usage extra.",
    "version": "0.2",
    "x-build-id": "4TqCBw5iHYbm6jXQw"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/apivault_labs~taobao-tmall-product-analyzer/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-apivault_labs-taobao-tmall-product-analyzer",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/apivault_labs~taobao-tmall-product-analyzer/runs": {
      "post": {
        "operationId": "runs-sync-apivault_labs-taobao-tmall-product-analyzer",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/apivault_labs~taobao-tmall-product-analyzer/run-sync": {
      "post": {
        "operationId": "run-sync-apivault_labs-taobao-tmall-product-analyzer",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "purchaseStressGrid": {
            "title": "Joint FX / shipping stress scenarios",
            "type": "object",
            "description": "Optional: requires landedCost.model=resale. Supply fxChangesPercent and/or shippingChangesPercent arrays of 1–4 numeric values, each -90 to 200. Omitted axes use [0,10,20]; baseline 0 is always added and duplicates removed. Up to 25 joint scenarios per delivered product. Original listing/pack and all other user assumptions stay fixed. Unknown pack/currency/required costs yield unavailable cells. REPORT.purchaseStressGrid and PURCHASE-STRESS-CSV contain arithmetic, not probabilities or a forecast. Example: {\"fxChangesPercent\":[0,10,20],\"shippingChangesPercent\":[0,25,50]}"
          },
          "sourceMode": {
            "title": "Collection source / 数据来源",
            "enum": [
              "native",
              "public_seo"
            ],
            "type": "string",
            "description": "native uses our own direct Taobao MTOP collector for SKU, attributes and bounded reviews, with public SEO fallback when Taobao denies access. public_seo requests only sparse public pages. No third-party Actor is started. Direct full-source live acceptance is still pending; inspect SUMMARY.sourceCollection and ERRORS.",
            "default": "native"
          },
          "reviewsPerProduct": {
            "title": "Maximum native reviews per product / 评价上限",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "0 disables reviews. Native MTOP requests up to five 20-row pages in source time order, bounded by this limit. Public SEO fallback may expose a small dated or undated embedded sample; dates and buyer additions are retained when exposed. No freshness or exhaustive-review guarantee.",
            "default": 20
          },
          "taobaoCookie": {
            "title": "Optional Taobao session cookie (secret)",
            "type": "string",
            "description": "Optional Cookie header from your own Taobao session, supplied only in Apify encrypted secret input. Never paste it into a chat, public examples, notes or logs. Used only at the fixed first-party MTOP host. An accepted session may still face CAPTCHA or source restrictions; no access guarantee."
          },
          "reportType": {
            "title": "Report type / 报告类型",
            "enum": [
              "product_report",
              "competitor_report",
              "market_snapshot",
              "store_report"
            ],
            "type": "string",
            "description": "All modes include evidence, price groups and buyer topics. Store reports describe only supplied/selected products; discovery is a bounded SEO sample.",
            "default": "product_report"
          },
          "items": {
            "title": "Taobao/Tmall product URLs or IDs",
            "maxItems": 20,
            "type": "array",
            "description": "Up to 20 numeric item IDs, HTTPS product URLs or copied share text containing one HTTPS e.tb.cn/m.tb.cn /h. link. Share resolution is bounded to four requests; expired/login/unsupported targets are reported without guessing a product. Working-link live acceptance is pending. Cannot be combined with discovery or imported products.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "keyword": {
            "title": "Keyword / 搜索词",
            "type": "string",
            "description": "Alternative to items. Searches one public Taobao SEO product page, then fetches detail evidence. Chinese keywords usually provide clearer category intent. No exhaustive search or official ranking.",
            "default": ""
          },
          "categoryId": {
            "title": "Taobao category ID",
            "type": "string",
            "description": "Alternative to keyword/items, e.g. 150704. Fetches one public category page. No full category or store crawl.",
            "default": ""
          },
          "maxProducts": {
            "title": "Maximum products analyzed",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Shared 1–20 collection and delivery cap across all keyword pages; attribute filtering may yield fewer products. No full pagination.",
            "default": 5
          },
          "proxyCountryCode": {
            "title": "Residential proxy country",
            "enum": [
              "SG",
              "US",
              "HK"
            ],
            "type": "string",
            "description": "Apify Residential proxy is required for live collection. Region is part of the comparison/monitoring context. No external data-provider key required.",
            "default": "SG"
          },
          "reportLanguage": {
            "title": "HTML interface language",
            "enum": [
              "en",
              "zh"
            ],
            "type": "string",
            "description": "English or Chinese report headings and fixed research guidance. Source review text is preserved without translation.",
            "default": "en"
          },
          "monitorStoreName": {
            "title": "Your monitoring store name",
            "type": "string",
            "description": "Optional user-owned accessible named KVS (3–63 ASCII letters/digits/hyphens). Sequential runs of the same scope only. First run is a baseline. Missing products or incomplete SKUs never trigger disappearance alerts.",
            "default": ""
          },
          "monitorStoreId": {
            "title": "Existing monitoring store",
            "type": "string",
            "description": "Select your existing KVS to grant this run scoped read/write access. Use this OR monitorStoreName. Selected IDs are opened by ID, never used as a new store name. Sequential same-scope monitoring only."
          },
          "datasetIds": {
            "title": "Advanced: existing product Datasets",
            "maxItems": 3,
            "type": "array",
            "description": "Select up to three authorized existing Datasets. Imported observations only, no new scraping/provider charges. First valid product wins across Datasets in supplied order. Use without items, keyword, categoryId or products. Reading is bounded; IMPORT documents rows and unread sources."
          },
          "datasetContract": {
            "title": "Dataset row format",
            "enum": [
              "canonical_v1",
              "zen_detail_v111",
              "zen_search_v093",
              "sian_detail_v153",
              "pizani_detail_v092"
            ],
            "type": "string",
            "description": "Explicit row format for all selected Datasets: canonical, Zen Detail 0.0.111, Zen Search 0.0.93, SIAN Detail 1.5.3 or Pizani Detail 0.0.92. Format selection is not proof of producing build, freshness or completeness. Zen reviews capped at 20/product; SIAN ID-only propPath and unknown Pizani options never imply a full option/stock matrix.",
            "default": "canonical_v1"
          },
          "products": {
            "title": "Advanced: supplied product observations",
            "maxItems": 20,
            "type": "array",
            "description": "Optional canonical product objects: itemId, title, price, currency, priceKind, priceContext, categoryId, shop, reviews, skus, attributes, packQuantity/packUnit. Currency is never inferred for imports. README documents fields. Cannot be combined with live sources.",
            "items": {
              "type": "object",
              "additionalProperties": true
            },
            "default": []
          },
          "landedCost": {
            "title": "Advanced: explicit landed-cost assumptions",
            "type": "object",
            "description": "Explicit user-assumption scenario, no verified taxes/FX/profit forecast. Default simple model: cnyToTargetRate, targetCurrency, shippingPerUnit, feesPerUnit, targetGrossMarginPercent. model=resale additionally requires purchaseQuantity (whole listed packs, 1-100000), packagingPerUnit, customsPerUnit, taxPerUnit, returnsReservePerUnit, fixedOrderCosts, platformFeePercent, sellingPricePerUnit, targetContributionMarginPercent (replaces gross margin). All allowances must be explicit, including zero; percentage rates 0-99.99 with at most 2 decimal places. Resale requires a whole piece/pc/pcs pack and CNY listing price; assumes every purchased piece sells. Reports breakdown, break-even prices/units and scenario profit; missing inputs are unavailable.",
            "default": {},
            "additionalProperties": true
          },
          "keywords": {
            "title": "Niche keywords (up to five)",
            "maxItems": 5,
            "type": "array",
            "description": "Alternative to keyword/items/category. Up to five public SEO pages, shared maxProducts 20 cap, round-robin candidate selection. No exhaustive search or full pagination.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "attributeFilters": {
            "title": "Exact declared attribute filters",
            "type": "object",
            "description": "Up to ten name:value pairs. Small CN/EN name aliases (color/material/brand/model/size/capacity), exact values. Missing/conflicting properties excluded before billing; no title inference or value translation.",
            "default": {},
            "additionalProperties": true
          },
          "costScenarios": {
            "title": "Profit sensitivity scenarios",
            "maxItems": 8,
            "type": "array",
            "description": "Requires landedCost baseline. Each {name,overrides}; explicit overrides allowed: cnyToTargetRate, shippingPerUnit, returnsReservePerUnit, sellingPricePerUnit. No auto FX or inferred return rate.",
            "items": {
              "type": "object"
            },
            "default": []
          },
          "requireFullEvidence": {
            "title": "Require declared full SKU, attributes and review texts",
            "type": "boolean",
            "description": "Reject sparse products before Dataset delivery/billing. Full normalized SKU source claim plus attributes and at least one review text required. This gate is not independent completeness or recent-review verification. Native SEO normally cannot pass.",
            "default": false
          },
          "priceAlertPercent": {
            "title": "Absolute price change threshold (%)",
            "minimum": 0.01,
            "maximum": 1000,
            "type": "number",
            "description": "For monitoring: known listing/SKU prices only; first observation is a baseline.",
            "default": 5
          },
          "alertWebhookUrl": {
            "title": "Optional price-alert webhook",
            "type": "string",
            "description": "Explicit recipient for threshold price events. Requires monitorStoreName/Id. HTTPS public destination, no redirects, one POST attempt, TLS verification. Report excludes URL; no alerts on baseline/missing products. Failure does not roll back state or retry automatically."
          },
          "reviewRequirements": {
            "title": "Review sample requirements",
            "type": "object",
            "description": "Optional {minTexts:0-1000,minRecentTexts:0-1000,recentDays:1-3650(default30)}. Per product deduplicated main review counts; recent dates nonfuture. Excluded products not delivered/charged. No larger crawl/representative sample/fresh source guarantee.",
            "default": {},
            "additionalProperties": true
          },
          "maxConcurrency": {
            "title": "Concurrent product requests / 并行商品请求",
            "minimum": 1,
            "maximum": 4,
            "type": "integer",
            "description": "Go collector loads up to four public product pages concurrently. Native session and token operations are serialized. Product and request caps still apply; source blocking is reported explicitly.",
            "default": 3
          },
          "cssbuyFallback": {
            "title": "CSSBuy public SKU fallback",
            "type": "boolean",
            "description": "When native details are unavailable, request anonymous CSSBuy intermediary SKU data. No account/API key or external Actor. Prices/stock are intermediary-reported and not independently verified; full matrix, attributes and reviews are not guaranteed. Set false for first-party sources only. Taobao cookies are never forwarded. Anonymous sessions may require login after several products. The run stops further CSSBuy requests at that gate, retains available public evidence and exposes cssbuyAccessStatus/cssbuyRequestsSkipped; full batch SKU coverage is not guaranteed.",
            "default": true
          },
          "lovegobuyFallback": {
            "title": "Lovegobuy public SKU and attribute fallback",
            "type": "boolean",
            "description": "Use anonymous HTTP product data from Lovegobuy when native details fail, before CSSBuy. Default follows cssbuyFallback when omitted. No account, API key or external Actor. Prices, stock and translated attributes are intermediary-reported and unverified; full reviews and completeness are not guaranteed. Set both fallbacks false for first-party-only collection."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}