{
  "openapi": "3.0.1",
  "info": {
    "title": "Airbnb Scraper - Market Signals, Pricing Position & Monitor",
    "description": "Stateful Airbnb market monitoring engine. Each run returns a ranked attention queue - what changed, what matters, what to review - with comp-set pricing position, revenue estimates, and supply-surge detection. Drop-in compatible with tri_angle/airbnb-scraper.",
    "version": "1.0",
    "x-build-id": "aitdTCSdhvsyb7kRH"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/ryanclinton~airbnb-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-ryanclinton-airbnb-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/ryanclinton~airbnb-scraper/runs": {
      "post": {
        "operationId": "runs-sync-ryanclinton-airbnb-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/ryanclinton~airbnb-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-ryanclinton-airbnb-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": [
              "market",
              "monitor",
              "listings",
              "host",
              "compare"
            ],
            "type": "string",
            "description": "Entry point. 'market' (default) ranks listings in a city by pricing/revenue opportunity. 'monitor' tracks a market over time and returns only what changed (the killer mode). 'listings' explains where specific room URLs sit vs their comp set. 'host' surfaces host-portfolio momentum. 'compare' ranks 2+ markets side by side. Leave fields below empty to use the market demo (Austin, TX).",
            "default": "market"
          },
          "market": {
            "title": "Market (city / destination)",
            "type": "string",
            "description": "Market mode / monitor mode: a city or destination, e.g. 'Austin, TX'. The actor ranks the listings by where they sit in their comp set and how the market is moving.",
            "default": ""
          },
          "markets": {
            "title": "Markets (compare mode)",
            "type": "array",
            "description": "Compare mode: 2+ cities to rank side by side on revenue / occupancy / supply / ADR axes. Example: [\"Austin, TX\", \"Nashville, TN\", \"Savannah, GA\"].",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "listings": {
            "title": "Listing URLs",
            "type": "array",
            "description": "Listings mode: Airbnb /rooms/<id> URLs to analyse. Each result carries its pricing position vs its market plus a fenced revenue estimate.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "hosts": {
            "title": "Host URLs",
            "type": "array",
            "description": "Host mode: Airbnb /users/show/<id> URLs. Each result carries hostMomentum (listing-count trend + superhost positioning).",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "roomType": {
            "title": "Room type",
            "enum": [
              "any",
              "entire_home",
              "private_room",
              "shared_room",
              "hotel_room"
            ],
            "type": "string",
            "description": "Filter listings by room type. 'any' includes all.",
            "default": "any"
          },
          "minBedrooms": {
            "title": "Minimum bedrooms",
            "minimum": 0,
            "type": "integer",
            "description": "Only include listings with at least this many bedrooms.",
            "default": 0
          },
          "minPrice": {
            "title": "Minimum nightly price (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Lower bound on nightly price.",
            "default": 0
          },
          "maxPrice": {
            "title": "Maximum nightly price (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Upper bound on nightly price.",
            "default": 0
          },
          "adults": {
            "title": "Guests (adults)",
            "minimum": 1,
            "maximum": 16,
            "type": "integer",
            "description": "Number of guests used to size the search.",
            "default": 2
          },
          "rankBy": {
            "title": "Rank by",
            "enum": [
              "attention",
              "pricingOpportunity",
              "revenue",
              "occupancy",
              "rating",
              "relevance"
            ],
            "type": "string",
            "description": "How to order the attention queue. 'attention' uses the composite attentionIndex. 'pricingOpportunity' surfaces comp outliers. 'revenue' surfaces estimated revenue leaders. 'occupancy' surfaces tightest-demand listings.",
            "default": "attention"
          },
          "maxResults": {
            "title": "Max results per market",
            "minimum": 1,
            "maximum": 240,
            "type": "integer",
            "description": "Maximum listings to scrape per market (Airbnb caps a market at ~240; coverage.marketRepresentativeness reports the sample fraction honestly).",
            "default": 100
          },
          "estimateRevenue": {
            "title": "Estimate revenue & occupancy",
            "type": "boolean",
            "description": "When on, each listing carries a fenced revenue/occupancy estimate from the public availability calendar (metricClass: estimated, measuredByAirbnb: false, with a range band + limitations). This is an estimate, never a measured booking figure.",
            "default": true
          },
          "enableMarketMemory": {
            "title": "Enable market memory",
            "type": "boolean",
            "description": "When on (default for market/monitor modes), the actor accrues a per-market interpretation history across runs - the moat. Run it daily: run 1 finds comp outliers, run 3 unlocks trajectory, run ~10 unlocks structural reads. The memory clock cannot be backfilled.",
            "default": true
          },
          "watchlistName": {
            "title": "Watchlist name (monitor mode)",
            "type": "string",
            "description": "Monitor mode: a stable name for this watchlist. State (price/supply/occupancy history, signal recurrence) persists in a named store keyed on this name across runs. Rename = a fresh memory clock (memoryResetReason: watchlist-renamed).",
            "default": ""
          },
          "trackListings": {
            "title": "Tracked listing IDs (monitor mode)",
            "type": "array",
            "description": "Monitor mode: specific listing IDs to track over time alongside the market.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "deltaWindowDays": {
            "title": "Delta window (days)",
            "minimum": 1,
            "maximum": 90,
            "type": "integer",
            "description": "The comparison window for delta intelligence (what changed since the prior run).",
            "default": 7
          },
          "lastReviewedAt": {
            "title": "Last reviewed at (ISO timestamp)",
            "type": "string",
            "description": "Optional. The timestamp your dashboard/automation last surfaced this market to a human. Drives sinceLastReview ('what changed since YOU last looked'). If omitted, the actor falls back to since-last-run - it never fabricates knowledge of when a human looked.",
            "default": ""
          },
          "persona": {
            "title": "Persona",
            "enum": [
              "generic",
              "host",
              "investor",
              "analyst"
            ],
            "type": "string",
            "description": "Reshapes materiality weights and which signals escalate. 'host' weights pricing position + price moves; 'investor' weights revenue + occupancy; 'analyst' weights supply/saturation. Orthogonal to mode and rankBy.",
            "default": "generic"
          },
          "outputProfile": {
            "title": "Output profile",
            "enum": [
              "signals",
              "compat",
              "agent",
              "minimal",
              "debug"
            ],
            "type": "string",
            "description": "'signals' (default) = full envelope: pricing position + revenue estimate + signals + attention routing + market profile + delta. 'compat' = exact tri_angle field set with validated URLs/IDs, no signal fields (migration parity). 'agent' = decision surface for MCP / pricing tools. 'minimal' = IDs + URL + price only. 'debug' = full diagnostics.",
            "default": "signals"
          },
          "analysisDepth": {
            "title": "Analysis depth",
            "enum": [
              "fast",
              "standard",
              "deep"
            ],
            "type": "string",
            "description": "'fast' = substrate + pricing position. 'standard' (default) = + signals. 'deep' = + full revenue suite and trajectory.",
            "default": "standard"
          },
          "explainability": {
            "title": "Explainability",
            "enum": [
              "standard",
              "full"
            ],
            "type": "string",
            "description": "'standard' trims the heaviest diagnostic blocks (signalLineage, materialityDrivers). 'full' keeps everything.",
            "default": "standard"
          },
          "calendarDepthDays": {
            "title": "Calendar depth (days forward)",
            "minimum": 7,
            "maximum": 365,
            "type": "integer",
            "description": "How many forward days of the availability calendar to use for the occupancy/revenue proxy.",
            "default": 90
          },
          "maxRuntimeSeconds": {
            "title": "Max runtime (seconds)",
            "minimum": 60,
            "maximum": 7200,
            "type": "integer",
            "description": "Soft runtime budget. The actor auto-clamps against the Apify timeout and emits partial output before a hard kill (partialOutputPolicy).",
            "default": 3600
          },
          "locationQueries": {
            "title": "Location queries (compat alias)",
            "type": "array",
            "description": "Drop-in migration: the tri_angle/airbnb-scraper input field. City/destination names; mapped to market mode automatically. Use 'market' / 'markets' for new runs.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify proxy. Defaults to RESIDENTIAL (required for Airbnb's anti-bot layer). Leave as default unless you have a reason to change it.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}