{
  "openapi": "3.0.1",
  "info": {
    "title": "Facebook Marketplace Scraper with New-Listing Alerts",
    "description": "Search Facebook Marketplace by keyword, city, price band, condition and age, and get listings back as rows with price, town, coordinates, photos and the seller's description. Monitoring mode returns only what is new since the last run.",
    "version": "0.1",
    "x-build-id": "KM9pWeX6ocjjQNoHD"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/s-r~facebook-marketplace-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-s-r-facebook-marketplace-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/s-r~facebook-marketplace-scraper/runs": {
      "post": {
        "operationId": "runs-sync-s-r-facebook-marketplace-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/s-r~facebook-marketplace-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-s-r-facebook-marketplace-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": {
          "searchKeyword": {
            "title": "Search keyword",
            "type": "string",
            "description": "What to search Marketplace for, exactly as you would type it into the site's own search box. Leave empty if you are using a category or pasting your own Marketplace URLs instead."
          },
          "keywords": {
            "title": "Extra keywords",
            "type": "array",
            "description": "Additional search terms. Every keyword is crossed with every location, so three keywords across two cities is six searches. Use this instead of running the Actor six times.",
            "items": {
              "type": "string"
            }
          },
          "location": {
            "title": "Location",
            "type": "string",
            "description": "The Marketplace city to search, as the slug Facebook puts in the URL (amsterdam, london, nyc) or the numeric city id from that same URL. Marketplace is city-scoped: there is no country-wide or worldwide search."
          },
          "locations": {
            "title": "Extra locations",
            "type": "array",
            "description": "Additional city slugs or city ids. Every location is crossed with every keyword, so two cities and three keywords is six searches, each of which is paged independently.",
            "items": {
              "type": "string"
            }
          },
          "country": {
            "title": "Market country",
            "type": "string",
            "description": "ISO country code of the market the cities belong to, lowercase. Marketplace localizes what it serves to where the request comes from, so setting this is what makes an Amsterdam search return the Dutch feed with Dutch towns and euro prices."
          },
          "startUrls": {
            "title": "Marketplace URLs",
            "type": "array",
            "description": "Paste Marketplace search or category URLs straight from your browser after clicking the filters you want. When this is set every other search field is ignored, because your URL already says what you want better than the builder can.",
            "items": {
              "type": "string"
            }
          },
          "category": {
            "title": "Category",
            "type": "string",
            "description": "A Marketplace category slug to browse instead of searching, taken from the URL of the category page (propertyrentals, vehicles, apparel). Ignored when Marketplace URLs are supplied."
          },
          "sort": {
            "title": "Sort order",
            "enum": [
              "best_match",
              "newest",
              "price_asc",
              "price_desc",
              "distance_asc"
            ],
            "type": "string",
            "description": "How Facebook should order the results. Newest first is what you want for monitoring; price ascending and descending walk the same market from opposite ends and reach different listings.",
            "default": "best_match"
          },
          "minPrice": {
            "title": "Minimum price",
            "minimum": 0,
            "type": "integer",
            "description": "Lower price bound in the market's own currency. Verified to apply: a search with a 400 floor came back with 400 as its cheapest row."
          },
          "maxPrice": {
            "title": "Maximum price",
            "minimum": 0,
            "type": "integer",
            "description": "Upper price bound in the market's own currency. Combine with the minimum to slice a busy category into bands."
          },
          "condition": {
            "title": "Condition",
            "type": "array",
            "description": "Restrict to the condition bands sellers pick when they post. Choosing more than one widens the search rather than narrowing it.",
            "items": {
              "type": "string",
              "enum": [
                "new",
                "used_like_new",
                "used_good",
                "used_fair"
              ],
              "enumTitles": [
                "New",
                "Used, like new",
                "Used, good",
                "Used, fair"
              ]
            }
          },
          "daysSinceListed": {
            "title": "Listed within",
            "type": "integer",
            "description": "Only listings posted within this many days. Facebook supports exactly three windows, 1, 7 and 30, and rejects anything else."
          },
          "availability": {
            "title": "Availability",
            "enum": [
              "in_stock",
              "sold"
            ],
            "type": "string",
            "description": "Whether to read the live listings or the ones already marked sold. Sold listings are what you want for a price history; live ones are what you want for what is on the market now.",
            "default": "in_stock"
          },
          "deliveryMethod": {
            "title": "Delivery method",
            "enum": [
              "all",
              "local_pickup",
              "shipping"
            ],
            "type": "string",
            "description": "Restrict to listings the seller will ship, or to ones that are collection only. Shipping is rare in some markets, so this filter can legitimately return nothing.",
            "default": "all"
          },
          "radiusKm": {
            "title": "Search radius in kilometres",
            "minimum": 1,
            "type": "integer",
            "description": "Passed to Facebook as the distance ring around the chosen city. Facebook did not honour it in testing: a 2 km ring and a 250 km ring returned the same towns, some of them 100 km away, because the query Facebook actually runs carries its own fixed radius. It is sent because you asked for it. Filter on the city field in the output if distance really matters."
          },
          "exactMatch": {
            "title": "Exact keyword match",
            "type": "boolean",
            "description": "Ask Facebook to treat the keyword as an exact phrase rather than loosely. It reordered our results without obviously narrowing them, so treat it as a hint rather than a guarantee.",
            "default": false
          },
          "listingDetails": {
            "title": "Fetch listing details",
            "type": "boolean",
            "description": "Open each listing's own page to add the seller's description, the full category path, map coordinates and whether shipping is offered. It costs one extra request per listing and is billed separately, so leave it off when the search row is enough.",
            "default": false
          },
          "allPhotos": {
            "title": "All photos",
            "type": "boolean",
            "description": "Collect every photo on the listing instead of just the cover image. Requires listing details to be on, because the extra photos only exist on the listing's own page.",
            "default": false
          },
          "maxPagesPerUrl": {
            "title": "Pages per search",
            "minimum": 1,
            "maximum": 40,
            "type": "integer",
            "description": "How deep to follow each search. Page one is the 24 listings the search page itself carries; every page after that adds about 24 more. Twenty-six requests against one Amsterdam search returned 573 distinct listings and Facebook was still offering more, so depth is a budget decision rather than a hard ceiling. Each page is one request, so this is the main thing that decides how long a run takes.",
            "default": 5
          },
          "maxListings": {
            "title": "Maximum listings",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Hard cap on rows written to the dataset, applied after every search has been paged. Leave room above the page size: one search page carries 24 listings and each extra page adds about 24 more.",
            "default": 100
          },
          "maxDetails": {
            "title": "Maximum detail fetches",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Cap on how many listings get their own page opened, so a wide search cannot turn into an unexpectedly large bill. Ignored when listing details are off."
          },
          "onlyNewListings": {
            "title": "Only new listings (monitoring mode)",
            "type": "boolean",
            "description": "Return only the listings that have appeared since the last run of this same monitor. Schedule the Actor and every run gives you the new arrivals and nothing else. A run that finds nothing new succeeds with an empty dataset.",
            "default": false
          },
          "cacheKey": {
            "title": "Monitor name",
            "type": "string",
            "description": "Names the memory that monitoring mode reads and writes, so two different saved searches do not share one list of already-seen listings. Pick any short label and keep using it for that search."
          },
          "cacheStorageName": {
            "title": "Monitor storage name",
            "type": "string",
            "description": "The named key-value store that holds monitoring memory across runs. Leave it alone unless you want several monitors kept in separate stores; the run summary reports which store was actually used.",
            "default": "facebook-marketplace-seen"
          },
          "retries": {
            "title": "Retries per page",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "How many times to re-request a page that came back without listings on it. Facebook serves a signed-out visitor an empty shell for roughly one request in six, and that shell is indistinguishable from a search with no results unless you ask again.",
            "default": 4
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}