Facebook Marketplace AI Search

Find Facebook Marketplace listings with a simple natural-language request. Add an optional AI image filter to keep only listings whose images match what you want.

Quick start: let AI do the search

Tell the Actor what item you want and where to search:

{
  "aiSearchDescription": "Find Toyota cars in New York",
  "maxItems": 100
}

You can write the request in English or another language. Include both the item and the place for the best result.

Search many locations

Use a broad location request when you want the Actor to create several location searches:

{
  "aiSearchDescription": "Find Toyota cars in all 50 US states",
  "locationExpansionLimit": 50,
  "maxItems": 100
}

The Actor expands the request into concrete locations and searches each one. maxItems applies to each location, so 50 locations with maxItems: 100 can return up to 5,000 listings.

You can also list locations yourself:

{
  "aiSearchDescription": "Find Ford cars in New York, California, and Florida",
  "maxItems": 100
}

For example, this searches Toyota cars in three specific US states. With maxItems: 100, the run can inspect up to 300 listings:

{
  "aiSearchDescription": "Find Toyota cars in California, Texas, and Florida",
  "aiImageFilterDescription": "Keep only clearly white Toyota cars",
  "maxItems": 100
}

The Actor processes up to 3 locations at the same time. If you request more than 3 locations, the remaining locations start as the first ones finish.

For complete control, provide one Facebook Marketplace search URL per location:

{
  "marketplaceUrls": [
    "https://www.facebook.com/marketplace/LOCATION_ID_1/search/?query=Toyota",
    "https://www.facebook.com/marketplace/LOCATION_ID_2/search/?query=Toyota"
  ],
  "maxItems": 100
}

When URLs are provided, they take priority over the AI search description. Each URL is treated as a separate location, and maxItems applies to each URL.

Use AI to filter listing images

Add aiImageFilterDescription to keep only images that match your request:

{
  "aiSearchDescription": "Find Toyota cars in Hanoi",
  "aiImageFilterDescription": "Keep only clearly white Toyota cars",
  "maxItems": 100
}

The AI first makes the short description more precise, then checks the listing images. Likely matches receive a stricter image confirmation. Images that are unclear, unrelated, or do not match are left out of the Dataset.

The primary image model is gpt-5.4. If it cannot process a request, a supported fallback model is used. The AI reason is included in each matched item and is limited to 20 words.

Leave aiImageFilterDescription empty to return all collected listings without image filtering.

Input fields

Field	Type	Default	Description
aiSearchDescription	string	Example request	Item and location written in natural language.
aiImageFilterDescription	string	Optional	Image requirements, such as Keep white Toyota cars.
marketplaceUrls	string array	Optional	Facebook Marketplace search or item URLs. One URL can represent one location.
maxItems	integer	100	Maximum listings to inspect for each location or URL. Range: 1–500.
locationExpansionLimit	integer	10	Maximum concrete locations created from a broad AI request. Range: 1–500.
startUrls	URL objects	Optional	Alternative URL input using { "url": "..." }.

Advanced fields such as searchQuery, marketplaceLocation, and countryCode are also supported when you already know the Facebook search location.

Output

The default Dataset contains one item for each listing that passes the selected filters. Common fields include:

• id: Facebook Marketplace listing ID.
• itemUrl: Direct listing URL.
• listingTitle: Listing title.
• description: Listing description, when available.
• listingPrice: Price information, when available.
• listingPhotos: Listing image URLs and IDs.
• locationName: Search location used by the Actor.
• locationText: Location shown on the listing.
• seller: Seller information, when available.
• isSold: Sold status, when available.

With image AI enabled, matched items also include:

{
  "id": "1234567890",
  "itemUrl": "https://www.facebook.com/marketplace/item/1234567890/",
  "listingTitle": "Toyota Corolla",
  "locationName": "New York, New York",
  "aiImageFilter": {
    "matches": true,
    "originalCriteria": "Keep white Toyota cars",
    "criteria": "Keep only clearly white Toyota cars and reject unclear images.",
    "verificationModel": "gpt-5.4",
    "confidence": 0.98,
    "reason": "Clearly shows a white Toyota car."
  }
}

aiImageFilter.matches is true for returned AI-filtered items. confidence is between 0 and 1. reason briefly explains why the image was selected.

Countries and languages

Location expansion is not limited to the United States. You can write the request in the local language and name the country or geographic group clearly:

{
  "aiSearchDescription": "Cerca tutte le città d'Italia per auto Toyota",
  "locationExpansionLimit": 10,
  "maxItems": 100
}

Other examples include Tìm ô tô Toyota ở tất cả tỉnh thành Việt Nam, Find cars in all provinces of Canada, or Rechercher des produits dans toutes les régions de France. The Actor creates concrete locations from the request and searches the locations that Facebook can resolve.

Important details

• maxItems is per location, not the total for the whole run.
• A broad request such as “all 50 US states” only expands as many locations as allowed by locationExpansionLimit.
• If Facebook cannot resolve a requested location, the other resolved locations can still be searched.
• Up to 3 locations are processed at the same time. Larger location lists are handled in groups as locations become available.
• When AI filtering is enabled, non-matching listings are not included in the Dataset.
• AI image usage is counted per image inspected. The stricter confirmation step does not count the same image twice.

FAQ

How do I search all US states?

Use:

{
  "aiSearchDescription": "Find Toyota cars in all 50 US states",
  "locationExpansionLimit": 50,
  "maxItems": 100
}

How do I search several named locations?

Write them in the AI description, for example: Find Ford cars in New York, California, and Florida, or provide one Marketplace URL for each location.

Can I use another language?

Yes. Describe the item and location in your preferred language. For broad requests, include the country or region clearly, such as “tất cả tỉnh thành Việt Nam” or “tutte le città d'Italia”.

Why are fewer items returned than maxItems?

Facebook may provide fewer listings for a location. With AI filtering enabled, listings that do not clearly match the image description are also excluded.