--- title: "Facebook listing details" method: GET path: "/facebook/item" tags: ["Facebook Marketplace"] --- # Facebook listing details `GET /facebook/item` ## Request - Base URL: `https://api.soldgraph.com/v1` - URL: `https://api.soldgraph.com/v1/facebook/item` - Auth: HTTP bearer Fetch one Facebook Marketplace listing by ID or URL: description, condition, posted date, approximate coordinates, delivery and photos. Status is the seller-set state, not a verified sale. Cached 15 minutes; a cache miss returns 202 to poll. ## Query parameters - `q` string, required - `country` 'us' - `marketplace` 'facebook' ## Headers - `Idempotency-Key` string ## Response `200` Complete, including cache hits. Costs 1 request. - FacebookItemJob - `request_id` string, required: ID of this request. Poll it at /v1/jobs/{request_id}. - `status` 'pending' | 'complete' | 'failed', required: pending, complete or failed. Always check it, even on HTTP 200. - `credits` integer, required: Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed. - `cached` boolean, required: True when the result came from the 15-minute cache. - `poll_url` string: Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL. - `result` FacebookItemPage - `provider` string, required: Marketplace ID, like ebay or poshmark. - `country` string, required: The country searched: us, or on eBay the country you sent. - `query` string, required: The q you sent, with extra spaces removed. - `page` integer, required: The page you asked for. - `count` integer, required: Rows in result.data on this page. - `reported_total` integer, required: Total matches the marketplace reports for the search. It may be rounded or capped. - `next_page` integer, nullable, required: Send this as page to get the next page. Null on the last page, and on page 100, the deepest page served. - `collected_at` string, required: When we collected the page, as an ISO 8601 timestamp. - `schema_version` integer, required: Version of the result's shape for that marketplace: 1 or 2. It only rises when a field changes meaning. - `completeness` string, required: provider_page_only: one page as the marketplace served it, not a full history. TCGplayer recent sales say recent_sample_only. - `field_notes` string, required: Plain-text notes on how to read this page's fields. - `data` FacebookItemRow, required - `id` string, required: Facebook Marketplace item ID. - `title` string, nullable, required: The listing's title. - `link` string, required: The listing's page on Facebook Marketplace. - `status` string, required: active, pending, sold or unavailable. The seller sets it: sold is not a verified sale, and its price is not a sale price. A deleted listing fails with not_found and costs nothing. - `description` string, nullable, required: Seller description, up to 10,000 characters. - `displayed_price` Money, required - `amount` number, required - `currency` string, required: ISO 4217 code, like USD. - `original_price` Money, required - `amount` number, required - `currency` string, required: ISO 4217 code, like USD. - `condition` string, nullable, required: new, used_like_new, used_good, used_fair or another source value, as the seller chose. - `listed_at` string, nullable, required: When the listing was posted, in UTC. - `location` object, required: name (city, state), approximate latitude and longitude, and city_id. Not an address. - `delivery` object, required: local_pickup, shipping, shipping_offered and shipping_price_text as Facebook shows it. - `category` object, required: Category id and slug, such as bicycles. - `photos` string[], required: Photo URLs on Facebook's CDN, in listing order. Signed links that expire. - `error` object - `code` 'page_mismatch' | 'schema' | 'network' | 'upstream' | 'throttled' | 'blocked' | 'rejected' | 'not_found' | 'filter_not_supported' | 'filter_not_applied' | 'location_not_served' | 'auth' | 'daily_limit' | 'deadline_exceeded' | 'credential_storage', required: Failed job code. - `message` string: What the code means, in plain words. ## Other responses - `202`: Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com. - `401`: invalid_api_key: The API key is missing, malformed or revoked. - `403`: account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server. - `404`: not_found: No such path. request_not_found: The job ID is well-formed but unknown, or belongs to another account. An ID that isn't a UUID is no such path: 404 not_found. batch_not_found: No batch with that ID belongs to this account. Or a replay of a search that failed because of the search (the body is then the failed job): not_found. - `405`: method_not_allowed: Wrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST. - `409`: idempotency_conflict: This Idempotency-Key was already used with different search parameters. result_not_ready: CSV was requested before every search settled. Poll as JSON until status is complete, then ask for CSV. - `413`: payload_too_large: The batch body is over 256 KB. - `414`: uri_too_long: The query string is longer than 2,048 characters. - `415`: unsupported_media_type: A batch must be sent as Content-Type: application/json. - `422`: unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. error.param names the input to fix when it is one of the route's inputs. duplicate_parameter: A parameter was sent more than once. sort_not_implemented: sort=best_deal is not available. invalid_idempotency_key: Idempotency-Key must be 1–128 printable ASCII characters, with no spaces. invalid_wait: wait must be a whole number from 0 to 20. invalid_body: The batch body is not JSON, or has no searches list. batch_too_large: The batch holds more searches than your plan allows at once. pages counts as one search per page. invalid_format: format must be json or csv, and include must be results. Or a replay of a search that failed because of the search (the body is then the failed job): rejected, filter_not_supported, filter_not_applied, location_not_served. - `429`: rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more. - `503`: Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support. --- [API](https://skmtc.dev/soldgraph/apis/soldgraph-api.md) · [All operations](https://skmtc.dev/soldgraph/apis/soldgraph-api/llms.txt) · [OpenAPI document](https://skmtc.dev/soldgraph/apis/soldgraph-api/revisions/137f0810f983?raw)