{
  "openapi": "3.0.1",
  "info": {
    "title": "Airbnb Reviews Scraper",
    "description": "Scrape public Airbnb listing reviews with pagination, category ratings, star distribution, host responses, and fail-closed access diagnostics.",
    "version": "1.0",
    "x-build-id": "ge0HKkaGEPiMimPve"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/w3crawler~airbnb-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-w3crawler-airbnb-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/w3crawler~airbnb-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-w3crawler-airbnb-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/w3crawler~airbnb-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-w3crawler-airbnb-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",
        "required": [
          "productUrls"
        ],
        "properties": {
          "productUrls": {
            "title": "Listing URLs",
            "minItems": 1,
            "type": "array",
            "description": "One or more HTTPS Airbnb listing URLs. Region domains and query strings are accepted and normalized to the listing ID.",
            "items": {
              "type": "string",
              "pattern": "^https://(?:[a-z0-9-]+\\.)*airbnb\\.(?:com|co\\.uk|ca|de|fr|it|es|com\\.au|co\\.in|co\\.jp|com\\.sg|com\\.br|com\\.mx|nl|be|ch|at)/rooms/[0-9]+(?:[/?#].*)?$"
            }
          },
          "maxReviewsPerListing": {
            "title": "Max Reviews Per Listing",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum review records emitted for each listing. Set 0 for no per-listing cap.",
            "default": 0
          },
          "maxItems": {
            "title": "Max Total Reviews",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Global maximum number of review records across all listing URLs. Set 0 for no global cap. This is the preferred name for new integrations.",
            "default": 0
          },
          "maxTotalReviews": {
            "title": "Legacy Max Total Reviews",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Backwards-compatible alias for maxItems. When both are greater than zero, maxTotalReviews takes precedence.",
            "default": 0
          },
          "maxPages": {
            "title": "Max Review Pages",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum bounded review-pagination scan windows per listing. Airbnb may require several physical scroll events per window; set 0 to continue until the source is exhausted or the review limit is reached.",
            "default": 0
          },
          "deduplicate": {
            "title": "Deduplicate Reviews",
            "type": "boolean",
            "description": "Remove repeated review IDs across the complete run; when Airbnb does not expose an ID, use normalized author/date/text as a bounded fallback key.",
            "default": true
          },
          "reviewSearch": {
            "title": "Review Keyword",
            "maxLength": 200,
            "type": "string",
            "description": "Optional case-insensitive phrase matched against review text, reviewer details, stay text, and host response text.",
            "default": ""
          },
          "minRating": {
            "title": "Minimum Review Rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "Keep reviews with a rating at or above this value. Reviews without a rating do not pass when this filter is set."
          },
          "maxRating": {
            "title": "Maximum Review Rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "Keep reviews with a rating at or below this value. Must be greater than or equal to minRating when both are set."
          },
          "reviewerLocation": {
            "title": "Reviewer Location Contains",
            "maxLength": 120,
            "type": "string",
            "description": "Optional case-insensitive substring filter for the public reviewer location line.",
            "default": ""
          },
          "stayTypeFilter": {
            "title": "Stay Text Contains",
            "maxLength": 120,
            "type": "string",
            "description": "Optional case-insensitive substring filter for Airbnb's displayed stay text, such as nights, week, or business trip.",
            "default": ""
          },
          "reviewLanguage": {
            "title": "Review Language",
            "pattern": "^$|^[a-zA-Z]{2}(?:-[a-zA-Z]{2})?$",
            "maxLength": 5,
            "type": "string",
            "description": "Optional two-letter language code filter, for example en or fr. It is applied only when Airbnb exposes a language attribute.",
            "default": ""
          },
          "minReviewDate": {
            "title": "Minimum Review Date",
            "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Optional inclusive date in YYYY-MM-DD format. Month/year and relative Airbnb dates are normalized best-effort.",
            "default": ""
          },
          "maxReviewDate": {
            "title": "Maximum Review Date",
            "pattern": "^$|^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Optional inclusive date in YYYY-MM-DD format. Must be on or after minReviewDate when both are set.",
            "default": ""
          },
          "hasHostResponseOnly": {
            "title": "Only Reviews With Host Responses",
            "type": "boolean",
            "description": "Keep only reviews where a public host response was detected.",
            "default": false
          },
          "reviewSort": {
            "title": "Review Sort",
            "enum": [
              "BEST_QUALITY",
              "MOST_RECENT",
              "HIGHEST_RATED",
              "LOWEST_RATED"
            ],
            "type": "string",
            "description": "Order requested from Airbnb and mirrored locally after extraction for deterministic output.",
            "default": "BEST_QUALITY"
          },
          "includeListingMetadata": {
            "title": "Include Listing Metadata",
            "type": "boolean",
            "description": "Include public listing title, type, location, capacity, description, ratings, amenities, and gallery image fields.",
            "default": true
          },
          "includeReviewerDetails": {
            "title": "Include Reviewer Details",
            "type": "boolean",
            "description": "Include public reviewer profile, location/tenure, avatar, language, and profile URL fields when exposed.",
            "default": true
          },
          "includeHostResponses": {
            "title": "Include Host Responses",
            "type": "boolean",
            "description": "Include the public host response text and response-author fields when Airbnb exposes them.",
            "default": true
          },
          "includeReviewMedia": {
            "title": "Include Review Media",
            "type": "boolean",
            "description": "Include public image URLs attached to review cards when exposed. Avatar URLs remain part of reviewer details.",
            "default": true
          },
          "includeReviewTopics": {
            "title": "Include Review Topics",
            "type": "boolean",
            "description": "Include Airbnb's public Guest reviews mention topic labels and counts when displayed in the review dialog.",
            "default": true
          },
          "requestDelayMs": {
            "title": "Request Delay (ms)",
            "minimum": 0,
            "maximum": 15000,
            "type": "integer",
            "description": "Delay before each listing/review-page request and fallback fetch. Use a respectful value for production runs.",
            "default": 1500
          },
          "maxConcurrency": {
            "title": "Max Browser Concurrency",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Maximum number of listing browser pages processed concurrently. Higher values use more memory and can increase access pressure.",
            "default": 2
          },
          "maxRequestRetries": {
            "title": "Max Request Retries",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Maximum Crawlee retries for a failed browser request. HTTP fallback uses its own bounded retry loop.",
            "default": 2
          },
          "requestTimeoutSecs": {
            "title": "Request Timeout (seconds)",
            "minimum": 30,
            "maximum": 300,
            "type": "integer",
            "description": "Bounded navigation and fallback HTTP timeout for each listing request.",
            "default": 90
          },
          "saveDebugHtml": {
            "title": "Save Debug HTML",
            "type": "boolean",
            "description": "Save a bounded debug HTML key-value record when a listing or reviews panel cannot be extracted.",
            "default": true
          },
          "saveDebugScreenshot": {
            "title": "Save Debug Screenshot",
            "type": "boolean",
            "description": "Save a JPEG screenshot alongside debug HTML when browser extraction fails.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration (Compatibility)",
            "type": "object",
            "description": "Accepted for compatibility but intentionally ignored. This Actor makes direct transparent requests and does not rotate IPs or bypass access controls."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}