CaptapiCaptapi
Facebook Marketplace · Guide

How to run a Facebook Marketplace marketplace search

TL;DR
To run a Facebook Marketplace marketplace search, sign up for a free Captapi key, then send one GET request to /v1/facebook/marketplace-search with your input. You get clean JSON back in seconds for 2 credits per call — no OAuth, scraping or platform SDKs. Search Marketplace by keyword + city — filters, isLocal/shipsOutsideRadius, opaque cursor (2 credits).
Get your free API keyAPI reference

How to run a Facebook Marketplace marketplace search (step by step)

  1. 1

    Get a free API key

    Create a free Captapi account (100 credits, no card) and generate an API key from the dashboard.

  2. 2

    Call the Facebook Marketplace Search API

    Send an authenticated GET request to /v1/facebook/marketplace-search with your input. No OAuth, no scraping setup.

  3. 3

    Read the JSON response

    Parse the clean JSON response. Pass cache=true for a free 24h cache hit; default is always fresh.

Code example

curl "https://api.captapi.com/v1/facebook/marketplace-search?q=desk%20chair&searchLocation=Austin%2C%20TX" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

What the response looks like

{
  "success": true,
  "data": {
    "query": "desk chair",
    "searchLocation": "Austin, TX",
    "filters": {
      "minPrice": "50",
      "maxPrice": "200",
      "sortBy": "price_ascend",
      "daysSinceListed": "30",
      "searchLocation": "Austin, TX"
    },
    "totalReturned": 2,
    "hasMore": true,
    "cached": false,
    "nextCursor": "eyJ2IjoxLCJxIjoiZGVzayBjaGFpciIsImxvYyI6IkF1c3RpbiwgVFgiLCJmIjp7Im1pblByaWNlIjoiNTAiLCJtYXhQcmljZSI6IjIwMCIsInNvcnRCeSI6InByaWNlX2FzY2VuZCIsImRheXNTaW5jZUxpc3RlZCI6IjMwIn0sInNraXAiOjUsImVjIjoie1wicGdcIjowLFwiYjJjXCI6e1wiYnJcIjpcIlwiLFwiaXRcIjowLFwiaG1zclwiOmZhbHNlLFwidGJpXCI6MH0sXCJjMmNcIjp7XCJiclwiOlwiQWJwaXVWdElpSVhFajlWV0ZVZEl4czFJUi13SldycGx1NWlNTGNYOURiMTBTQzhFQk93YzFXZi1RcmpOcDM3elBFWlg5ZGJNdlNDa0ZUay1sclBucTlCTnJGWURUdHg5bFZlMFhGd2FGdEQ0RG03T3RkemJBMU5MVWdkLUFrclRhc3hPZHVmWldmVkJTZlJTTG1SYmZydWVBVW85QTRNZXBqc1I0cm0zV09FejNSYlhIVnRrcm9SV21JZ1liUUZYN0Y0WnpfNnlhQTRkdThSY1BRbzJJeUwtcC1Ca3hlTVhHblFLSHZ1ZXJyZ2J2alN0M2hXNEFNdDZlclE1UkpGOUhSdFk3b1RLbGI2bTVfTUZEd2FqcXdMbUJhSzBKWlVKN3ZsUnczVFlQMm9SSjVoMDFxSndUU2Z6enduMkFodEFlcVFaUEs0eWV5OEc0WGZ0bm81cERJYzZDUWNzTWtRdEJjZDE2R3FNanQwQXhybkNJM1A0OFZINmZqcG9vM3hGTnJqU3ZvRDhOOGNxbVFMaVJzVy1SRlF2am9CNTdGWkkzVkpMLXhLN204cUVNaUczcnZKUlRJd2ZLS2VHdTlBckJXbi1SODJuNkVPUU9MU2loUkppTlY4Q0Rxamw0WnIyUVJmcXFMN3hmNzZPSnBzaEVxWi05Z1JWRWlzaFdJcUx1eWY0YzF6NE1zMUZ5YTNDeUZxamgtdDBtei1nR3dTZGhEOEhxelloQXhYWGZsU0NkdGUxVWIwaVBiRVctSUhqQmVjXCIsXCJpdFwiOjI0LFwicnBi …",
    "listings": [
      {
        "platform": "facebook",
        "id": "4482233215369733",
        "title": "Vintage 1980s Postmodern \"American Lighting\" Gooseneck Desk Lamp",
        "url": "https://www.facebook.com/marketplace/item/4482233215369733/",
        "price": 50,
        "priceFormatted": "$50",
        "priceAmount": 5000,
        "currency": "USD",
        "categoryId": "1569171756675761",
        "location": {
          "name": "Benson, AZ",
          "city": "Benson",
          "state": "AZ",
          "countryCode": "US",
          "latitude": null,
          "longitude": null
        },
        "cityPageId": "109791499039942",
        "isSold": false,
        "isPending": false,
        "isHidden": false,
        "deliveryTypes": [
          "IN_PERSON",
          "SHIPPING_ONSITE"
        ],
        "image": "https://scontent-atl3-3.xx.fbcdn.net/v/t39.84726-6/748718464_1472100928021023_7004614235492134530_n.jpg?stp=c0.87.526.526a_dst-jpg_p526x395_tt6&_nc_cat=109&ccb=1-7&_nc_sid=92e707&_nc_ohc=Osco_iBPSHsQ7kNvwE88Z2B&_nc_oc=AdrnNrq4GxtoKGWCDi_qxKj2BfO-OcysnTpk7mDO5d-84zPauj6YWLhxJPZuiRErURoSW7OUci-LjqdvjivdYc4u&_nc_zt=14&_nc_ht=scontent-atl3-3.xx&_nc_gid=48UkL5OoevcKmJAZmxtYnw&_nc_ss=7b289&oh=00_AQFTCh3FFtSTB-AA28V6Jr1NtrTs9PSVie1b1KW_xUkkNw&oe=6A753B85",
        "createdAt": "2026-07-16T06:02:16+00:00",
        "status": "available",
        "isPublished": true,
        "isLocal": false,
        "shipsOutsideRadius": true
      },
      {
        "platform": "facebook",
        "id": "2467979733629080",
        "title": "Gaiam Classic Balance Ball Chair - Ergonomic Office/Desk Chair",
        "url": "https://www.facebook.com/marketplace/item/2467979733629080/",
        "price": 50,
        "priceFormatted": "$50",
        "priceAmount": 5000,
        "currency": "USD",
        "categoryId": "1383948661922113",
        "location": {
          "name": "Fresno, CA",
          "city": "Fresno",
          "state": "CA",
          "countryCode": "US",
          "latitude": null,
          "longitude": null
        },
        "cityPageId": "107983435897193",
        "isSold": false,
        "isPending": false,
        "isHidden": false,
        "deliveryTypes": [
          "IN_PERSON",
          "SHIPPING_ONSITE"
        ],
        "image": "https://scontent-atl3-3.xx.fbcdn.net/v/t39.84726-6/749286700_1116782047845292_1788708914246608626_n.jpg?stp=c0.81.526.526a_dst-jpg_p526x395_tt6&_nc_cat=110&ccb=1-7&_nc_sid=92e707&_nc_ohc=gbzkYGqnXmYQ7kNvwGzH1qf&_nc_oc=AdqLUHLAdzpxyU4TF9F6Xf5v9Tib9M6UCrmYThgY8kMR7j8y-uMyvFm3zwMzYYMwX1rcrfF1-yMiBdhJbknk-W2-&_nc_zt=14&_nc_ht=scontent-atl3-3.xx&_nc_gid=48UkL5OoevcKmJAZmxtYnw&_nc_ss=7b289&oh=00_AQHJWOlgp25sCHb9Xzuo5yQVzSCjOZpSF6EaQpKDCudKZA&oe=6A751DFD",
        "createdAt": "2026-07-18T17:45:28+00:00",
        "status": "available",
        "isPublished": true,
        "isLocal": false,
        "shipsOutsideRadius": true
      }
    ]
  }
}

Billing metadata (credits charged, cache hit/miss) is returned in the X-Captapi-Credits and X-Captapi-Cache response headers.

Request parameters

NameTypeRequiredDescription
qstring YesProduct or keyword to search Facebook Marketplace for.
searchLocationstring YesSearch-origin city or place name, e.g. 'Austin, TX'. Required — there is no default city. Echoed on the envelope and inside filters. Not listings[].location.
locationstringNoAlias of searchLocation. Prefer searchLocation. Either one is required.
limitnumberNoHow many listings to return (1–200). Flat 2 credits when details=false; details=true billed as 2 + 2 per listing.
minPricenumberNoMinimum price in local currency units.
maxPricenumberNoMaximum price in local currency units.
sortBystringNosuggested | distance | creation_time | price_ascend | price_descend.
daysSinceListedstringNoFacebook calendar-day recency: 1 = since the start of yesterday (not a rolling 24 hours), 7, or 30.
conditionstringNonew, like_new, good, fair (comma-separated ok).
deliveryMethodstringNolocal_pickup | shipping | all. Shipped listings can appear nationwide outside radiusMiles — use local_pickup for nearby-only; rows expose isLocal / shipsOutsideRadius.
availabilitystringNoavailable | sold | all.
radiusMilesnumberNoRadius in miles: 1,2,5,10,20,40,60,80,100,250,500. Does not exclude nationwide shipped inventory.
categorystringNoTop-level category slug, e.g. electronics.
cursorstringNoOpaque pagination cursor from a previous nextCursor.
detailsbooleanNoWhen true, adds description/condition/coordinates/full photo gallery/seller/distanceMiles — billed as 2 + 2 credits per listing. Default false → flat 2 credits; cover photo is still in image.
cachebooleanNoSet true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh.

Frequently asked questions

What does the Facebook Marketplace Search API do?

The Facebook Marketplace Search API lets you search and return matching results from a public Facebook Marketplace query using one GET request to /v1/facebook/marketplace-search. It returns clean JSON — no OAuth or infrastructure setup required.

How many credits does the Facebook Marketplace Search API cost?

Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.

Do I need a Facebook Marketplace API key or OAuth?

No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle proxies, rate limits, retries, and authentication for you.

Why did I get a 504 after 100 or 210 seconds?

Decodo headless is 55s scrape + 20s body drain (~75s on an empty miss). A second scroll hop after a live first-paint used to hang until the 90s wall and throw away the cards we already had. Search is first-paint only now. A 6h last-good page for the same query+city (any limit) is a labelled stale 200 at 0 credits; otherwise 504 UPSTREAM_TIMEOUT at 0 credits with timings.

Why is searchLocation Frisco, TX when I did not set a city?

The backend has no default city — Marketplace search is geographic and requires searchLocation (or the location alias). Playground examples use Austin, TX. The origin is echoed as searchLocation on the envelope and inside filters so it is visibly an input, not a fact about each listing. listings[].location is where the item is.

Does daysSinceListed=1 mean the last 24 hours?

No. That is Facebook's own calendar-day filter: 1 means listed on or after the start of yesterday, so a row can be up to ~39 hours old at the UTC day boundary. We pass it through — we do not re-window it to rolling 24 hours.

Why did a brand keyword return other products?

Facebook broadens Marketplace search. sortBy=creation_time_descend is recency, not relevance. Pass-through — not our matcher.

Why is hasMore false with no nextCursor?

nextCursor is always keyed (null when exhausted). hasMore is true only when nextCursor is present. Same catalogue rule as tiktok/trending-feed and truth-social/user-posts — those two may set hasMore true with a null cursor only when truncatedReason is single_page_only (more exist, unreachable). Marketplace first-paint leftover cards get a real skip cursor; a short filtered page is hasMore false, nextCursor null.

Why did three identical calls each cost 2 credits, and why was the first ~53s?

cache defaults to false, so each live call bills. cached is always keyed — false on those live hops, true on a cache=true hit or labelled last-good. The 53s first call vs ~28s later is Decodo cold-path variance; timings.fetchMs is the upstream hop (parse/resolve stay ~0–1 ms).

Is the Facebook Marketplace Search API suitable for production use?

Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.

Ready to run a Facebook Marketplace marketplace search?

Start free with 100 credits — no credit card required.

Get your free API key