# Facebook Marketplace API (ScrapeIO)

3 endpoints for public Facebook Marketplace data. Same response format and field names as every other platform.

## Basics

- Base URL: `https://scrapeio.com`
- Auth: send your key in the `x-api-key` header. Get a key at https://scrapeio.com/login (100 free credits, no card).
- Every endpoint is a GET with query parameters and returns JSON:
  `{ "success": true, "cached": false, "credits_used": 1, "credits_remaining": 99, "data": { ... } }`
- Field names are the same on every platform (`handle`, `followers`, `plays`, `likes`, `comments`, `created_at`).
- Lists return `data.items`, `data.cursor` and `data.has_more`. Pass `cursor` back to get the next page.
- Each endpoint has one listed price. Cached repeats, failed calls, private and not-found answers cost 0.
- Limit: 300 requests a minute per key.

## Errors

| Status | Meaning | Charged |
| --- | --- | --- |
| 200 | Success | Yes, unless cached |
| 400 | A parameter is missing or wrong | No |
| 401 | The key is missing or invalid | No |
| 402 | Not enough credits | No |
| 403 | The account or post is private | No |
| 404 | Not found on the platform | No |
| 429 | More than 300 requests a minute | No |
| 502 | Every source is down; retry shortly | No |

### GET /v1/facebook/marketplace/item

Marketplace Item Price: 1 credit. MCP tool: `facebook_marketplace_item`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | Facebook Marketplace item id |
| `url` | string | no | Facebook Marketplace item URL |

```bash
curl "https://scrapeio.com/v1/facebook/marketplace/item" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/marketplace/location/search

Marketplace Location Search Price: 1 credit. MCP tool: `facebook_marketplace_location_search`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Location search query |

```bash
curl "https://scrapeio.com/v1/facebook/marketplace/location/search?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/marketplace/search

Marketplace Search Price: 1 credit. MCP tool: `facebook_marketplace_search`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | no | Search keyword. |
| `lat` | string | yes | Latitude for the search location |
| `lng` | string | yes | Longitude for the search location |
| `category_id` | string | no | Category ID from listing results. |
| `radius_km` | string | no | Search radius in kilometers |
| `min_price` | string | no | Minimum listing price |
| `max_price` | string | no | Maximum listing price |
| `sort_by` | string (suggested, distance_ascend, creation_time_descend, price_ascend, price_descend) | no | Facebook Marketplace sort option. |
| `delivery_method` | string (all, local_pickup, shipping) | no | Delivery filter |
| `condition` | string (new, used_like_new, used_good, used_fair) | no | Condition filter |
| `date_listed` | string (all, 1, 7, 30, last_24_hours, last_7_days, last_30_days) | no | Facebook Marketplace date filter. |
| `availability` | string (available, sold, all) | no | Availability filter |
| `cursor` | string | no | Opaque pagination cursor returned from the previous response. |

```bash
curl "https://scrapeio.com/v1/facebook/marketplace/search?lat=...&lng=..." -H "x-api-key: $SCRAPEIO_API_KEY"
```