Catalog / Facebook Marketplace Read

Facebook Marketplace Read API

facebook.com

Anonymous, read-only access to public Facebook Marketplace category links, contextual search results, observed filter controls, and listing details. Results are retrieved live through Facebook's public pages; listing identity is scoped to the returned Facebook listing ID and canonical URL.

  • shopping
  • facebook
  • marketplace
  • listings
  • read-only
4 endpointsDocs updated

Endpoint health

Loading verification…

Connect your agent

Connect through MCP so your agent can find this API, read its docs, and call its endpoints.

Setup guide

Add the server from your terminal.

Claude Code · terminal
claude mcp add --transport http agent-data https://agent-data.motie.dev/mcp

In Claude Code, run /mcp, select agent-data, then Authenticate. Sign in to your agent-data account in the browser.

Then ask your agent to use the Facebook Marketplace Read API for your task.

Call it over HTTP

Get an API key

Sign up free, generate an API key, and set it as AGENT_DATA_API_KEY in your environment. Your first 100 calls each month are free.

Fetch the categories currently linked by the public Marketplace home page. Use a returned category_id or pass the unchanged returned url as category_url to listings; numeric search links are directly supported, while no-ID URLs are truthfully marked category-specific/unknown until their caller-invoked source response is read. The list is page-contextual, not a universal taxonomy.

View call pricing
cURL · Marketplace categories
curl --request GET --get 'https://3kpkg0jfvk.execute-api.us-east-2.amazonaws.com/prod/c93db173-463b-4abe-a4f8-2120a4a69899/v1/marketplace/categories' \
  --header "Authorization: Bearer $AGENT_DATA_API_KEY"

Endpoints

Inputs and response fields for every endpoint in this API.

GETMarketplace categories/v1/marketplace/categories

Fetch the categories currently linked by the public Marketplace home page. Use a returned category_id or pass the unchanged returned url as category_url to listings; numeric search links are directly supported, while no-ID URLs are truthfully marked category-specific/unknown until their caller-invoked source response is read. The list is page-contextual, not a universal taxonomy.

Input

No input parameters.

Response

itemsobject[]
items[].urlstring
items[].slug?string | null
items[].labelstring
items[].category_id?string | null
items[].source_pathstring
items[].listing_search_supportedboolean | null
items[].listing_search_limitation?string | null
coveragestring
source_urlstring
returned_countinteger

Fields marked ? are optional.

GETMarketplace filters/v1/marketplace/filters

Inspect structured filter and sort controls rendered for a location/category/query context, including exact source display names, opaque/source values, active state, range metadata, and filter type. This operation reports what Facebook rendered; it does not invent universal options or apply controls whose URL encoding was not exposed by the public page.

Input

locationOptionalQuery · string, default: 103133213059698

Facebook Marketplace location token: a source-recognized location ID or slug returned/used by Marketplace URLs.

Example: 103133213059698

queryOptionalQuery · string | null

Optional Facebook Marketplace search text.

Example: Vehicles

category_idOptionalQuery · string | null

Optional Facebook category ID obtained from the categories operation.

Example: 546583916084032

category_urlOptionalQuery · string | null

Complete category URL copied unchanged from categories[].url. Query/category_id must be omitted when this is supplied; category pages without a numeric ID are retained but may not expose a public listing data surface.

Example: https://www.facebook.com/marketplace/103133213059698/search/?category_id=546583916084032&query=Vehicles

Response

groupsobject[]
groups[].namestring
groups[].range?object | null
groups[].valuesobject[]
groups[].values[].value?string | null
groups[].values[].active?boolean | null
groups[].values[].display_namestring
groups[].values[].source_record?object
groups[].field_key?string | null
groups[].filter_keystring
groups[].filter_type?string | null
groups[].source_record?object
coveragestring
source_urlstring

Fields marked ? are optional.

GETMarketplace listings/v1/marketplace/listings

Retrieve the live Facebook-ranked listing collection for a source-recognized location, optional query, and optional category. Facebook's public HTML currently embeds an opaque Relay cursor but a controlled anonymous HTTP replay of it repeats the first page, so this API does not claim callable pagination. Each item is a listing summary; call the detail operation separately for description, attributes, full photos, and seller details.

Input

locationOptionalQuery · string, default: 103133213059698

Facebook Marketplace location token: a source-recognized location ID or slug.

Example: 103133213059698

queryOptionalQuery · string | null

Optional free-text query passed to Facebook Marketplace.

Example: Vehicles

category_idOptionalQuery · string | null

Optional Facebook category ID returned by categories.

Example: 546583916084032

category_urlOptionalQuery · string | null

Complete category URL copied unchanged from categories[].url. Query/category_id must be omitted when this is supplied. Facebook category URLs without numeric IDs are accepted as a source reference but currently return a typed source-shape error because their anonymous HTML exposed no listing-search data.

Example: https://www.facebook.com/marketplace/103133213059698/search/?category_id=546583916084032&query=Vehicles

Response

itemsobject[]
items[].idstring
items[].url?string | null
items[].price?object
items[].price.amountstring
items[].price.currency?string | null
items[].price.formatted?string | null
items[].price.amount_with_offset_in_currency?string | null
items[].title?string | null
items[].seller?object | null
items[].is_live?boolean | null
items[].is_sold?boolean | null
items[].location?object | null
items[].subtitle?string[]
items[].category_id?string | null
items[].primary_photo?object | null
items[].source_record?object
items[].delivery_types?string[]
items[].created_at_unix?integer | null
items[].source_story_type?string | null
items[].strikethrough_price?object
items[].strikethrough_price.amountstring
items[].strikethrough_price.currency?string | null
items[].strikethrough_price.formatted?string | null
items[].strikethrough_price.amount_with_offset_in_currency?string | null
orderingstring
session_id?string | null
source_urlstring
returned_countinteger
continuation_notestring
source_next_cursorstring | null
continuation_supportedboolean

Fields marked ? are optional.

GETMarketplace listing detail/v1/marketplace/listings/{listing_id}

Fetch one public listing by its Facebook Marketplace listing ID. Pass an id unchanged from marketplace-listings.items[].id. This caller-invoked detail read is intentionally separate from search and does not enrich every search result.

Input

listing_idRequiredPath · string

Facebook Marketplace listing ID returned by the listings operation.

Example: 1810869790221056

Response

idstring
url?string | null
price?object
price.amountstring
price.currency?string | null
price.formatted?string | null
price.amount_with_offset_in_currency?string | null
title?string | null
photos?object[]
seller?object | null
is_live?boolean | null
is_sold?boolean | null
category?string | null
location?object | null
subtitle?string[]
condition?string | null
attributes?object[]
source_urlstring
category_id?string | null
coordinates?object | null
description?string | null
category_slug?string | null
location_text?string | null
primary_photo?object | null
source_record?object
delivery_types?string[]
created_at_unix?integer | null
related_searches?string[]
renderable_status?string | null
source_story_type?string | null
strikethrough_price?object
strikethrough_price.amountstring
strikethrough_price.currency?string | null
strikethrough_price.formatted?string | null
strikethrough_price.amount_with_offset_in_currency?string | null

Fields marked ? are optional.

Don’t see the endpoint you need?

Ask agent-data to add an endpoint or return more fields. Extensions are free and keep existing endpoints working.