# Facebook AI Marketplace Search: Let AI Do the Work (`thedoor/facebook-marketplace-ai-filter`) Actor

🧠⚡ Start a smart AI search with no hard work needed. Tell AI what you want, and it will find the Marketplace listings you are looking for.

- **URL**: https://apify.com/thedoor/facebook-marketplace-ai-filter.md
- **Developed by:** [TheDoor](https://apify.com/thedoor) (community)
- **Categories:** AI, Agents, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.50 / 1,000 marketplace listings

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Facebook Marketplace AI Scraper

Search Facebook Marketplace with a natural-language request and optionally filter listing images with AI.

### 1. Use AI as the main input

Describe what you want to find, including the item and location:

```json
{
  "aiSearchDescription": "Find Toyota cars near New York",
  "maxItems": 100
}
```

The Actor uses the description to identify the search keyword and Facebook Marketplace location.

The AI can also expand a broad geographic request into multiple locations in any supported language or country. For example, `Cerca auto Toyota in tutte le città d'Italia` asks the AI to create an Italian city list, then each city is resolved to a Facebook Marketplace location before searching. The same works for states, provinces, regions, countries, and capitals.

#### How location matching works

Use a specific location when you want one area:

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

The AI reads the location from your sentence, finds the matching Facebook Marketplace location, and searches that area.

The same approach supports requests such as `Tìm sản phẩm ở tất cả tỉnh thành Việt Nam`, `Cerca auto in tutte le città d'Italia`, or `Rechercher des produits dans toutes les régions de France`. The AI understands the language of the request, creates a concrete location list, and the Actor resolves each location independently. Locations that Facebook cannot resolve are reported as unresolved and do not stop locations that were resolved successfully.

For large lists, set `locationExpansionLimit` (default `10`, maximum `500`). This controls how many locations the AI expands from a broad request; `maxItems` is the maximum number of listings returned for each location. For example, two locations with `maxItems: 100` can return up to 200 listings.

For a single location, use a clear city, state, or country name. For guaranteed control over a large location list, provide the Marketplace URLs directly in `marketplaceUrls` or `startUrls`.

You can also list specific locations in one sentence. For example, `Find Toyota in New York, California, and Florida` creates three independent location searches. The same works with comma-separated locations and equivalent words in other languages.

To filter the listing images too, add `aiImageFilterDescription`:

```json
{
  "aiSearchDescription": "Find Toyota cars near New York",
  "aiImageFilterDescription": "keep black Toyota cars",
  "maxItems": 100
}
```

Short image descriptions are accepted. For example, `keep black toyota` is expanded into a clearer visual rule before images are checked.

### 2. Search several locations

For multiple locations, provide one Marketplace search URL per location in `marketplaceUrls`:

```json
{
  "marketplaceUrls": [
    "https://www.facebook.com/marketplace/LOCATION_ID_1/search/?query=Toyota",
    "https://www.facebook.com/marketplace/LOCATION_ID_2/search/?query=Toyota",
    "https://www.facebook.com/marketplace/LOCATION_ID_3/search/?query=Toyota"
  ],
  "aiImageFilterDescription": "keep black Toyota cars",
  "maxItems": 100
}
```

Replace each `LOCATION_ID` with the Facebook Marketplace location ID for the city or area you want. You can add as many location URLs as needed. The same format is available through `startUrls`:

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

When URLs are provided, they take priority over `aiSearchDescription`, `searchQuery`, and country settings.

### Main input fields

| Field | Description |
|---|---|
| `aiSearchDescription` | Natural-language request with the item and location scope, in any language. It can describe one location or a group such as all cities in a country. |
| `aiImageFilterDescription` | Optional description of what the listing image must show. |
| `marketplaceUrls` | Array of Marketplace search or item URLs, useful for multiple locations. |
| `startUrls` | Same URL approach using `{ "url": "..." }`. |
| `searchQuery` | Search keyword when not using AI search. |
| `countryCode` | Two-letter country code such as `us`, `gb`, or `vn`. |
| `marketplaceLocation` | Marketplace location ID or slug. |
| `maxItems` | Maximum listings to inspect per location. Default: `100`. |
| `locationExpansionLimit` | Maximum locations created from a broad AI location request. Default: `10`, maximum: `500`. |

### How image AI works

1. The image description is refined if needed.
2. Each listing image is checked in its own AI request.
3. Matching listings are written to the Dataset immediately.

The primary image model is `thuonghongthai97/gemini-3.6-flash-high`. If it fails, the Actor uses `gpt-5.4` as fallback. Listings whose images do not match are not included when AI filtering is enabled.

### Output

Each Dataset item is a Marketplace listing. Common fields are:

- `id`: Marketplace listing ID.
- `itemUrl`: Direct listing URL.
- `listingTitle`: Listing title.
- `description`: Listing description, when available.
- `locationName`: Facebook Marketplace location used for this search.
- `locationText`: Listing location.
- `listingPhotos`: Listing image URLs and IDs.
- `seller`: Seller information, when available.
- `isSold`: Whether the listing is sold.

With AI filtering enabled, matching items also contain:

```json
{
  "aiImageFilter": {
    "matches": true,
    "originalCriteria": "keep black Toyota cars",
    "criteria": "The image must show a real Toyota vehicle with a clearly black exterior color. Reject unclear or ambiguous images.",
    "verificationModel": "sypham98/gpt-5.4",
    "confidence": 0.95
  }
}
```

Important AI fields:

| Field | Description |
|---|---|
| `aiImageFilter.matches` | Whether the image matched the request. |
| `aiImageFilter.originalCriteria` | Original client image description. |
| `aiImageFilter.criteria` | Refined description used by AI. |
| `aiImageFilter.verificationModel` | Model used for the image check. |
| `aiImageFilter.confidence` | Confidence score from `0` to `1`. |
| `aiImageFilter.reason` | Short reason explaining why the image was selected, limited to 20 words. |

### Billing events

When monetization is enabled, `listing` is charged once for every unique Marketplace listing fetched, whether or not it matches the AI filter. `ai-image-filter` is charged once for every listing sent to the AI image preflight. The second verification step is internal and does not create a second AI charge for the same listing.

If `aiImageFilterDescription` is not provided, all collected listings are returned without AI fields.

The Dataset display shows the product image, title, location, item URL, and search URL. Price is not shown as a display column, although `listingPrice` remains available in the raw Dataset item when Facebook provides it.

# Actor input Schema

## `marketplaceUrls` (type: `array`):

Optional fixed Facebook Marketplace search or item URLs. Use this mode when you already know the URLs to scrape.

## `aiSearchDescription` (type: `string`):

Try to tell us the place and item you want. Example: Find all Toyota cars in all states of the US. You can write in any language.

## `aiImageFilterDescription` (type: `string`):

Describe the images to keep. Example: Keep all white Toyota cars. Leave empty to disable the image filter.

## `startUrls` (type: `array`):

Optional Marketplace search, category, or item URLs. When provided, these take precedence over generated search input.

## `searchQuery` (type: `string`):

Marketplace keyword, for example Toyota or sofa.

## `marketplaceLocation` (type: `string`):

Facebook Marketplace location ID or slug.

## `countryCode` (type: `string`):

Optional country preset such as us, gb, vn, or jp. Uses the country's capital and a 65 km radius when marketplaceLocation and coordinates are not provided.

## `maxItems` (type: `integer`):

Maximum number of listings to inspect for each location before AI filtering.

## `locationExpansionLimit` (type: `integer`):

Maximum number of concrete locations created from a broad AI request such as all cities in Italy. Default 10; maximum 500.

## Actor input object example

```json
{
  "aiSearchDescription": "Find all Toyota cars in all states of the US",
  "aiImageFilterDescription": "Keep all white Toyota cars",
  "maxItems": 100,
  "locationExpansionLimit": 10
}
```

# Actor output Schema

## `listings` (type: `string`):

Listings collected from Facebook Marketplace, including the resolved search location and optional AI image filter metadata.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("thedoor/facebook-marketplace-ai-filter").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("thedoor/facebook-marketplace-ai-filter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call thedoor/facebook-marketplace-ai-filter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,thedoor/facebook-marketplace-ai-filter"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/oWVyR1U94CcBUIwrP/builds/DZCbHVYNYWe8mbcfh/openapi.json