{
  "openapi": "3.0.1",
  "info": {
    "title": "Trustpilot Reviews Scraper - Full Review Coverage",
    "description": "Scrape trustpilot.com - full review coverage beyond Trustpilot’s 200-review display limit. TrustScores, star ratings, reviewer profiles, company contact data, and transparency reports. Incremental mode detects new reviews. Compact output for AI agents.",
    "version": "0.1",
    "x-build-id": "ETKPosmcWuLiItMFe"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~trustpilot-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-trustpilot-reviews-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/blackfalcondata~trustpilot-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-trustpilot-reviews-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/blackfalcondata~trustpilot-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-trustpilot-reviews-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",
              "searchCompanies",
              "categories",
              "companyInfo"
            ],
            "type": "string",
            "description": "What to scrape. reviews = review data (default). searchCompanies = find companies by keyword. categories = browse a Trustpilot category. companyInfo = company profiles only (no reviews).",
            "default": "reviews"
          },
          "companyDomain": {
            "title": "Company Domain",
            "type": "string",
            "description": "Company domain as used on Trustpilot, e.g. 'booking.com' or 'www.amazon.com'."
          },
          "companyName": {
            "title": "Company Name",
            "type": "string",
            "description": "Company name to search for. Resolved automatically to the Trustpilot domain slug."
          },
          "startUrls": {
            "title": "🔗 Start URLs",
            "type": "array",
            "description": "List of Trustpilot review page URLs, e.g. https://www.trustpilot.com/review/booking.com",
            "items": {
              "type": "string"
            }
          },
          "searchQuery": {
            "title": "Search Query",
            "type": "string",
            "description": "Company search keyword (for searchCompanies mode). E.g. 'car insurance', 'web hosting'."
          },
          "searchCountry": {
            "title": "Search Country",
            "type": "string",
            "description": "ISO country code for company search results. Default: US.",
            "default": "US"
          },
          "searchMaxPages": {
            "title": "Search Max Pages",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Max pages of search/category results to fetch (5 results per page). Default: 5.",
            "default": 5
          },
          "categoryUrl": {
            "title": "Category URL",
            "type": "string",
            "description": "Trustpilot category URL for categories mode. E.g. 'https://www.trustpilot.com/categories/electronics_technology'."
          },
          "maxResults": {
            "title": "💯 Max Results",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum reviews to return per company (0 = unlimited). Default: 200.",
            "default": 200
          },
          "stars": {
            "title": "Star Ratings",
            "type": "array",
            "description": "Only return reviews with these star ratings. Leave empty for all ratings.",
            "items": {
              "type": "integer",
              "minimum": 1,
              "maximum": 5
            }
          },
          "languages": {
            "title": "Languages",
            "type": "array",
            "description": "Filter by review language ISO codes, e.g. ['en', 'de', 'fr']. Leave empty for all languages.",
            "items": {
              "type": "string"
            }
          },
          "date": {
            "title": "Date Range",
            "enum": [
              "",
              "last30days",
              "last3months",
              "last6months",
              "last12months",
              "older"
            ],
            "type": "string",
            "description": "Only return reviews from this time period.",
            "default": ""
          },
          "lookbackDays": {
            "title": "Lookback Days",
            "minimum": 1,
            "maximum": 365,
            "type": "integer",
            "description": "Rolling window: only return reviews published within the last N days. Overrides date range when set. Use with sort=recency for efficient early termination."
          },
          "topics": {
            "title": "Topics",
            "type": "array",
            "description": "Filter by Trustpilot topic categories. Leave empty for all topics. E.g. [\"customer_service\", \"delivery_service\"]",
            "items": {
              "type": "string"
            }
          },
          "verified": {
            "title": "Verified Reviews Only",
            "type": "boolean",
            "description": "Return only verified reviews.",
            "default": false
          },
          "withReplies": {
            "title": "With Company Reply Only",
            "type": "boolean",
            "description": "Return only reviews that have a company reply.",
            "default": false
          },
          "sort": {
            "title": "Sort Order",
            "enum": [
              "recency",
              "relevance"
            ],
            "type": "string",
            "description": "Review sort order.",
            "default": "recency"
          },
          "countryOfReviewer": {
            "title": "Country of Reviewer",
            "type": "string",
            "description": "Only return reviews from reviewers in this country. ISO Alpha-2 code, e.g. 'US', 'GB', 'DE'."
          },
          "search": {
            "title": "Search within Reviews",
            "type": "string",
            "description": "Keyword search within review text."
          },
          "includeCompanyInfo": {
            "title": "Include Company Info",
            "type": "boolean",
            "description": "Include company metadata: trust score, total reviews, star breakdown, categories, website, contact, and AI summary.",
            "default": true
          },
          "includeProductReviews": {
            "title": "Include Product Reviews",
            "type": "boolean",
            "description": "Include associated product review data when available. Adds a productReviews array to each review.",
            "default": false
          },
          "includeTransparency": {
            "title": "Include Transparency Report",
            "type": "boolean",
            "description": "Fetch the Trustpilot transparency report per company (+1 request). Adds a separate record with reply rate, organic share, flagged review counts, monthly distributions, and verification status. Auto-included in companyInfo mode.",
            "default": false
          },
          "descriptionMaxLength": {
            "title": "✂️ Description Max Length",
            "minimum": 0,
            "type": "integer",
            "description": "Truncate review text to N characters. 0 = no truncation.",
            "default": 0
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Return core review fields only: reviewId, reviewUrl, rating, title, text, dates, reviewer, companyTrustScore. Ideal for AI pipelines and MCP integrations. Overridden by 'fields' if set.",
            "default": false
          },
          "fields": {
            "title": "Custom Fields",
            "type": "array",
            "description": "Return only these fields. Overrides compact mode. E.g. [\"reviewId\", \"rating\", \"title\", \"text\", \"publishedDate\"]. Leave empty for all fields (or use compact for the default subset).",
            "items": {
              "type": "string"
            }
          },
          "incrementalMode": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "Only return new and changed reviews compared to the previous run. Uses stateKey when provided, otherwise derives one from the target and filters.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Optional stable identifier for the tracked search universe. Leave empty to auto-derive a stable identifier from your search inputs — different keyword/location/filter combinations get isolated state automatically."
          },
          "skipReposts": {
            "title": "🚫 Skip Reposts",
            "type": "boolean",
            "description": "Exclude reviews detected as reposts of previously seen reviews.",
            "default": false
          },
          "authCookiesJson": {
            "title": "Auth Cookies JSON",
            "type": "string",
            "description": "Optional Trustpilot consumer auth cookies as JSON. Accepts either the exported envelope with all_cookies or a plain cookie object. Current actor transport uses these as plain HTTP cookies and verifies whether page 11 access works; full browser-session pagination is tracked separately."
          },
          "requestDelayMs": {
            "title": "Request Delay (ms)",
            "minimum": 0,
            "maximum": 5000,
            "type": "integer",
            "description": "Delay between HTTP requests in milliseconds. Use to reduce rate-limit risk on large runs. Default: 0.",
            "default": 0
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy Configuration",
            "type": "object",
            "description": "Trustpilot rate-limits ~1 req/s per IP (1580-token bucket, 1 token/s refill). For LARGE companies (10k+ reviews), use Apify Proxy with RESIDENTIAL group + multi-IP pool to scale near-linearly. WITHOUT proxy = single home IP, ~860 reviews/min. RESIDENTIAL pool of 5 = ~4300 reviews/min projected.",
            "default": {
              "useApifyProxy": false
            }
          },
          "concurrencyMode": {
            "title": "Concurrency Mode",
            "enum": [
              "single",
              "pool-2",
              "pool-5",
              "pool-10"
            ],
            "type": "string",
            "description": "Single = 1 IP, ~860 reviews/min, safest. Pool-N = N parallel IPs from Apify Proxy. Pool requires proxyConfiguration with useApifyProxy:true. Pool on RESIDENTIAL = N× throughput. Pool on shared/auto = ~1.5× (IPs are shared with other users). DATACENTER often blocked by Trustpilot WAF.",
            "default": "single"
          },
          "telegramToken": {
            "title": "🤖 Telegram Bot Token",
            "type": "string",
            "description": "Telegram bot token from @BotFather. Required for Telegram notifications."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat ID",
            "type": "string",
            "description": "Telegram chat or channel ID where alerts are sent (e.g. \"-100123456789\" for a private group, or \"@yourchannel\")."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL. Get one from Server Settings → Integrations → Webhooks."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL. Create at api.slack.com/messaging/webhooks."
          },
          "whatsappPhoneNumberId": {
            "title": "📱 WhatsApp Phone Number ID",
            "type": "string",
            "description": "WhatsApp Business phone number ID from Meta Business Manager (NOT the phone number itself — the numeric ID shown next to your business number). Free service-conversation messages within 24 hours of last user-initiated contact."
          },
          "whatsappAccessToken": {
            "title": "🔐 WhatsApp Access Token",
            "type": "string",
            "description": "Meta Cloud API access token with `whatsapp_business_messaging` scope. Get a permanent token from a system user in Meta Business Manager."
          },
          "whatsappTo": {
            "title": "📨 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone in E.164 format (e.g. +919876543210). Recipient must have messaged your business number within the last 24 hours — outside that window, free-form text is rejected by Meta."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Generic webhook URL that receives a JSON POST with the full job payload + run metadata. Universal escape hatch for n8n / Make / Zapier / your own backend."
          },
          "webhookHeaders": {
            "title": "🔑 Webhook Headers",
            "type": "object",
            "description": "Optional headers (e.g. {\"Authorization\": \"Bearer xyz\"}) sent with the webhook POST."
          },
          "notificationLimit": {
            "title": "📊 Max Jobs Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of jobs included in each notification message (1–20). Excess jobs are still in the dataset; notifications get a summary line.",
            "default": 5
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New/Updated",
            "type": "boolean",
            "description": "When Incremental Mode is on, only send notifications for NEW / UPDATED / REAPPEARED jobs. Has no effect outside incremental mode.",
            "default": false
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}