{
  "openapi": "3.0.1",
  "info": {
    "title": "MercadoLibre Scraper",
    "description": "Scrape MercadoLibre products, reviews, buyer Q&A, and sellers across 9 LATAM marketplaces. One actor replaces Search, Product, Reviews, and Seller scrapers.",
    "version": "1.0",
    "x-build-id": "8Wyr8BTohUkG5WIBA"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/parsebird~mercadolibre-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-parsebird-mercadolibre-scraper",
        "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/parsebird~mercadolibre-scraper/runs": {
      "post": {
        "operationId": "runs-sync-parsebird-mercadolibre-scraper",
        "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/parsebird~mercadolibre-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-parsebird-mercadolibre-scraper",
        "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": {
          "mode": {
            "title": "Mode",
            "enum": [
              "reviews",
              "product",
              "seller"
            ],
            "type": "string",
            "description": "What to scrape. 'reviews' returns paginated reviews for one product across all 9 LATAM marketplaces. 'product' returns full PDP fields (title, price, brand, attributes, variations, seller, inline reviews, Q&A). 'seller' returns a seller's storefront profile.",
            "default": "reviews"
          },
          "country": {
            "title": "Country",
            "enum": [
              "MX",
              "AR",
              "BR",
              "EC",
              "DO",
              "CL",
              "CO",
              "PE",
              "UY"
            ],
            "type": "string",
            "description": "MercadoLibre country marketplace. All nine Latin-American sites are supported across every mode (reviews, product, seller). The selected country routes the residential proxy to in-country IPs for product mode and selects the right TLD for built URLs. Runs that find no records for a country are not charged per-result.",
            "default": "MX"
          },
          "productUrls": {
            "title": "Product URLs",
            "type": "array",
            "description": "One or more MercadoLibre product URLs. Used by 'reviews' and 'product' modes. Accepts both catalog (.../p/MLM…) and article (articulo.*/MLM-…) URLs. The prefilled example is an iPhone PDP on MLM.",
            "items": {
              "type": "string"
            }
          },
          "maxItems": {
            "title": "Max Items",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum items to return. 0 = no limit. Product: PDPs; Reviews: reviews PER PRODUCT, so 3 product URLs at 50 returns up to 150 rows (the practical ceiling for a very popular product is ~900, because MeLi hard-caps single-bucket pagination at offset 300). Not used in 'seller' mode (always one profile row per seller URL).",
            "default": 50
          },
          "reviewRating": {
            "title": "Review Rating Filter",
            "enum": [
              "all",
              "1",
              "2",
              "3",
              "4",
              "5"
            ],
            "type": "string",
            "description": "In 'reviews' mode, scrape only reviews with this star rating. Default 'all' triggers the deep-sweep strategy — 12 concurrent queries across rating + sort buckets — to recover the maximum unique reviews per product (up to ~950 on popular products vs ~330 single-bucket).",
            "default": "all"
          },
          "reviewOrder": {
            "title": "Review Sort Order",
            "enum": [
              "relevance",
              "dateCreated"
            ],
            "type": "string",
            "description": "Sort order for reviews. 'relevance' is MeLi's helpfulness-ranked default; 'dateCreated' returns newest first. This applies when 'Review Rating Filter' is set to a specific rating (1-5). When the filter is 'all', the deep sweep already runs both sort orders in parallel, so it returns the full result set either way and this setting has no effect on how much you get.",
            "default": "relevance"
          },
          "sellerUrls": {
            "title": "Seller URLs",
            "type": "array",
            "description": "One or more seller storefront URLs: brand stores (https://www.mercadolibre.com.mx/tienda/phone-depot), BR brand stores (https://www.mercadolivre.com.br/loja/samsung), or independent eshops (.../pagina/...). Each seller produces one profile row with followers, dates, banner, brand info, and corridor menu. Not supported on AR (different storefront framework).",
            "items": {
              "type": "string"
            }
          },
          "includeReviews": {
            "title": "Include Inline Reviews",
            "type": "boolean",
            "description": "In 'product' mode, include the top 5 reviews from JSON-LD. Full paginated reviews require 'reviews' mode.",
            "default": true
          },
          "includeQuestions": {
            "title": "Include Q&A",
            "type": "boolean",
            "description": "In 'product' mode, include buyer questions + seller answers (up to 20 per product) from the listing's dedicated Q&A page.",
            "default": true
          },
          "includeVariations": {
            "title": "Include Variations",
            "type": "boolean",
            "description": "In 'product' mode, include product variations (color/size/storage) when the listing has them.",
            "default": true
          },
          "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "Direct URLs to scrape. Accepts product URLs (both .../p/MLM… and articulo./MLM-…) or seller storefront URLs (.../tienda/..., .../loja/..., .../pagina/...). Pasting full URLs is supported — country/mode will be auto-detected. Alternative to the mode-specific URL fields above.",
            "items": {
              "type": "string"
            }
          },
          "maxConcurrency": {
            "title": "Max Concurrency",
            "minimum": 1,
            "maximum": 24,
            "type": "integer",
            "description": "Maximum parallel requests across all (product × rating × sort) slice tasks in 'reviews' mode. 8 is a safe default; bump up for large batches (50+ products) if you see throughput stalling. Capped at 24 to avoid MeLi rate-limits.",
            "default": 8
          },
          "useResidentialProxy": {
            "title": "Use Residential Proxy (paid plans)",
            "type": "boolean",
            "description": "Reviews and seller modes run without residential proxy. Product mode always routes through Apify's residential pool (matched to the selected country) via a real browser — this toggle is informational for product mode. Residential traffic adds Apify's ~$8/GB usage fee on top of actor pricing.",
            "default": true
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}