# Facebook Marketplace Search (`facebook.marketplace`)

Search Facebook Marketplace listings by keyword near a latitude/longitude with price, condition, delivery, recency and availability filters.

Docs: https://primaryapi.com/docs/api-reference/facebook/marketplace

- Endpoint: `POST https://api.primaryapi.com/v1/run/facebook.marketplace`
- Category: E-commerce · Platform: `facebook` · Kind: search · Status: live
- Price: 2 credits per call; up to 16 credits if a call is retried elsewhere. A quote’s `maxCredits` is the most a given call can cost.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=facebook.marketplace`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `query` | string | yes |  | max 500 chars | Search keyword (e.g. "bike"). |
| `lat` | number \| string | yes |  |  | Latitude of the search centre (e.g. 30.2677 or "30.2677"). |
| `lng` | number \| string | yes |  |  | Longitude of the search centre (e.g. -97.7475 or "-97.7475"). |
| `priceMin` | integer | no |  | ≥ 0 | Minimum price in whole units of the local currency (e.g. 100). |
| `priceMax` | integer | no |  | ≥ 0 | Maximum price in whole units of the local currency (e.g. 500). |
| `condition` | enum | no |  | one of: new, used_like_new, used_good, used_fair | Only listings in this condition. |
| `dateListed` | enum | no |  | one of: all, last_24_hours, last_7_days, last_30_days | Only listings posted in this window (calendar-day buckets, not rolling). |
| `deliveryMethod` | enum | no |  | one of: all, local_pickup, shipping | Only listings offering this delivery method. |
| `availability` | enum | no |  | one of: available, sold, all | available (default), sold or all. |
| `sort` | enum | no |  | one of: suggested, distance_ascend, creation_time_descend, price_ascend, price_descend | Sort order (default suggested). |
| `limit` | integer | no | 30 | 1–50 | Maximum number of results to return (1-50, default 30). |
| `cursor` | string | no |  |  | Opaque pagination cursor: pass the previous response's nextCursor. |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `listings` | object[] |  |
| `listings[].id` | string |  |
| `listings[].title` | string \| null |  |
| `listings[].url` | string |  |
| `listings[].priceAmount` | number \| null | Numeric price in the listing currency |
| `listings[].priceFormatted` | string \| null | e.g. "$380" |
| `listings[].city` | string \| null |  |
| `listings[].state` | string \| null |  |
| `listings[].locationName` | string \| null |  |
| `listings[].cityPageId` | string \| null |  |
| `listings[].photoUrl` | string \| null |  |
| `listings[].photoId` | string \| null |  |
| `listings[].categoryId` | string \| null |  |
| `listings[].createdUtc` | integer \| null | Listing time, Unix seconds (often null in search results) |
| `listings[].listingDateText` | string \| null | e.g. "Listed 2 days ago" |
| `listings[].deliveryTypes` | string[] | IN_PERSON, SHIPPING, … |
| `listings[].isSold` | boolean \| null |  |
| `listings[].isPending` | boolean \| null |  |
| `listings[].isLive` | boolean \| null |  |
| `listings[].isHidden` | boolean \| null |  |
| `hasNextPage` | boolean |  |
| `nextCursor` | string \| null |  |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

Pagination: pass the previous response’s `nextCursor` as `cursor` to get the next page; `nextCursor: null` means there are no more results.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/facebook.marketplace" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"bike","lat":"30.2677","lng":"-97.7475","priceMin":100,"priceMax":500,"sort":"creation_time_descend"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "listings": [
        {
          "id": "string",
          "title": "string",
          "url": "https://example.com",
          "priceAmount": 0,
          "priceFormatted": "string",
          "city": "string",
          "state": "string",
          "locationName": "string",
          "cityPageId": "string",
          "photoUrl": "https://example.com",
          "photoId": "string",
          "categoryId": "string",
          "createdUtc": 0,
          "listingDateText": "string",
          "deliveryTypes": [
            "string"
          ],
          "isSold": true,
          "isPending": true,
          "isLive": true,
          "isHidden": true
        }
      ],
      "hasNextPage": true,
      "nextCursor": null
    }
  },
  "provider": "PrimaryAPI",
  "credits": 2,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z",
  "nextCursor": null
}
```

## Pricing and reliability

- Usual price: 2 credits per call
- Price ceiling: up to 16 credits if a call is retried elsewhere. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=facebook.marketplace`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Keep other inputs unchanged when following a cursor. Listings can expose private sellers' locations.

