{
  "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": "K7tNZGXSvSU3fv20A"
  },
  "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": "Review Text Max Length",
            "minimum": 0,
            "type": "integer",
            "description": "Truncate review text to N characters. 0 = no truncation.",
            "default": 0
          },
          "compact": {
            "title": "Compact Output (MCP/AI-agent mode)",
            "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. Requires stateKey.",
            "default": false
          },
          "stateKey": {
            "title": "State Key",
            "type": "string",
            "description": "Unique identifier for this tracking job, e.g. 'booking-com-monitor'. Required when incrementalMode is enabled."
          },
          "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. When provided, the actor verifies page 11 access and switches to full linear pagination. Leave empty for cookieless mode."
          },
          "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 jobs. Default: 0.",
            "default": 0
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}