{
  "openapi": "3.0.1",
  "info": {
    "title": "Agoda Reviews Scraper — Hotel Guest Reviews",
    "description": "Scrape guest reviews for any Agoda hotel — star ratings, full review text in the original language and translated, traveler and stay details, reviewer photos, and the hotel's official management responses. Pull one hotel or many, with an optional rating summary per hotel.",
    "version": "0.1",
    "x-build-id": "MtUtdC3YiqfLqNzQA"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~agoda-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-agoda-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~agoda-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-agoda-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~agoda-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-agoda-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": {
          "startUrls": {
            "title": "🔗 Start URLs",
            "type": "array",
            "description": "Agoda hotel page URLs to scrape, in the standard Apify Start URLs format. Equivalent to Hotel URLs — use whichever you prefer. You can bulk-paste or upload a list here.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "hotelUrls": {
            "title": "🏨 Hotel URLs",
            "type": "array",
            "description": "One or more Agoda hotel page URLs. Paste the link to a hotel and its reviews will be collected.",
            "items": {
              "type": "string"
            }
          },
          "hotelIds": {
            "title": "🆔 Hotel IDs",
            "type": "array",
            "description": "One or more hotel ids, if you already have them. You can use this instead of, or together with, hotel URLs.",
            "items": {
              "type": "string"
            }
          },
          "maxReviews": {
            "title": "💯 Max Reviews",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Maximum total reviews to return across all hotels.",
            "default": 100
          },
          "maxReviewsPerHotel": {
            "title": "🏷️ Max Reviews Per Hotel",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Optional cap on the number of reviews returned for each individual hotel. Leave empty for no per-hotel limit."
          },
          "sortBy": {
            "title": "↕️ Sort Reviews By",
            "enum": [
              "mostHelpful",
              "mostRecent",
              "ratingHighToLow",
              "ratingLowToHigh"
            ],
            "type": "string",
            "description": "Order in which reviews are collected.",
            "default": "mostHelpful"
          },
          "reviewProviders": {
            "title": "🌐 Review Sources",
            "type": "array",
            "description": "Limit results to specific review sources. Leave empty to include all available sources.",
            "items": {
              "type": "string",
              "enum": [
                "Agoda",
                "Booking.com",
                "Priceline"
              ],
              "enumTitles": [
                "Agoda",
                "Booking.com",
                "Priceline"
              ]
            }
          },
          "travelerType": {
            "title": "🧳 Traveler Type",
            "enum": [
              "Solo",
              "Couple",
              "Family",
              "Group",
              "Business"
            ],
            "type": "string",
            "description": "Optional. Only return reviews from a specific kind of traveler."
          },
          "minRating": {
            "title": "⭐ Minimum Rating",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Optional. Only return reviews with a rating at or above this value (0–10)."
          },
          "maxRating": {
            "title": "⭐ Maximum Rating",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Optional. Only return reviews with a rating at or below this value (0–10)."
          },
          "reviewsFromDate": {
            "title": "📅 Reviews From Date",
            "type": "string",
            "description": "Optional. Only return reviews written on or after this date (e.g. \"2025-01-01\")."
          },
          "language": {
            "title": "🗣️ Language",
            "type": "string",
            "description": "Language locale for review content where translations are available (e.g. \"en-us\").",
            "default": "en-us"
          },
          "currency": {
            "title": "💱 Currency",
            "type": "string",
            "description": "Currency context for the request (e.g. \"USD\").",
            "default": "USD"
          },
          "includeHotelResponse": {
            "title": "💬 Include Management Responses",
            "type": "boolean",
            "description": "Include the hotel's official response to each review when available.",
            "default": true
          },
          "includeReviewerDemographics": {
            "title": "👤 Include Reviewer Details",
            "type": "boolean",
            "description": "Include reviewer details such as country, traveler type, room type, and length of stay.",
            "default": true
          },
          "includeUgcImages": {
            "title": "🖼️ Include Review Photos",
            "type": "boolean",
            "description": "Include photo URLs uploaded by reviewers when available.",
            "default": true
          },
          "includeHotelSummary": {
            "title": "📈 Include Hotel Summary Row",
            "type": "boolean",
            "description": "Add one extra summary record per hotel with the overall score, sub-scores, and review counts.",
            "default": false
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Output only core fields (ideal for AI-agent / MCP workflows).",
            "default": false
          },
          "excludeEmptyFields": {
            "title": "🧹 Exclude Empty Fields",
            "type": "boolean",
            "description": "Drop null / empty-string / empty-array fields from each output record. Off by default to preserve dataset schema compatibility; turn on to slim output for LLM / agent consumption.",
            "default": false
          },
          "incremental": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "On repeat runs, only return reviews that are new since the previous run with the same state key.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Optional. Stable identifier that links runs together for incremental mode. Leave empty to use a per-hotel default."
          },
          "emitUnchanged": {
            "title": "📋 Include Unchanged & Removed",
            "type": "boolean",
            "description": "When Incremental Mode is on, also output reviews that are unchanged since the last run, plus a tombstone record for each review that has since been removed. Off by default — only new, updated, and reappeared reviews are returned. Note: every output record is billed, so turning this on returns (and bills for) more records per run.",
            "default": false
          },
          "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 (e.g. \"-100123456789\"). Required when telegramToken is set."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL. Server Settings → Integrations → Webhooks → New Webhook."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL. api.slack.com/messaging/webhooks."
          },
          "notificationLimit": {
            "title": "📊 Max Reviews Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of reviews included in each notification message (1–20).",
            "default": 5
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New Reviews",
            "type": "boolean",
            "description": "When Incremental Mode is on, only send notifications for new reviews. Has no effect outside incremental mode.",
            "default": false
          },
          "whatsappAccessToken": {
            "title": "📱 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API permanent access token (System User token from Meta Business). Recipient must have messaged the business number within the last 24h (service-conversation window — free since Nov 2024)."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "Your WhatsApp Business phone-number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set."
          },
          "whatsappTo": {
            "title": "📲 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone in E.164 format without + (e.g. \"436641234567\"). Recipient must have messaged your business number within last 24h."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Receives a JSON POST with {metadata, items} after each run. Universal escape hatch for n8n / Make / Zapier / custom backends."
          },
          "webhookHeaders": {
            "title": "📋 Webhook Headers",
            "type": "object",
            "description": "Optional JSON object of custom headers (e.g. {\"Authorization\":\"Bearer ...\"})."
          },
          "appConnector": {
            "title": "Send results to a connected app",
            "type": "string",
            "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results. Best-effort across MCP connectors as Apify expands its catalog."
          },
          "mcpIssueTeam": {
            "title": "Issue tracker team",
            "type": "string",
            "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}