# Facebook listing details

> GET /v1/facebook/item returns one Facebook Marketplace listing with description, condition, posted date, approximate coordinates, delivery and photos.

```text
GET https://api.soldgraph.com/v1/facebook/item
```

Look up one listing by the `id` from [Facebook local listings](https://soldgraph.com/docs/api/facebook-listings.md), or by its `facebook.com/marketplace/item/...` URL. The result adds what search results don't show: description, condition, approximate coordinates, delivery details, category and all photos.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `q` | string | Required | Facebook Marketplace item ID from search results, or a `facebook.com/marketplace/item/...` URL. |
| `country` | `us` | `us` | Only `us` is supported here. eBay, Vinted, Poshmark, Depop and Whatnot endpoints also take other countries. Mercari, OfferUp, Facebook Marketplace and TCGplayer are US only. |
| `marketplace` | `facebook` | `facebook` | Optional; must match the path. |

```bash title="cURL"
curl -G https://api.soldgraph.com/v1/facebook/item \
  -H "Authorization: Bearer $SOLDGRAPH_KEY" \
  -d q=2796090964120499
```

```typescript title="TypeScript"
const params = new URLSearchParams({
  q: "2796090964120499",
});

const res = await fetch(`https://api.soldgraph.com/v1/facebook/item?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SOLDGRAPH_KEY}` },
});
const data = await res.json();
```

```python title="Python"
import os, requests

res = requests.get(
    "https://api.soldgraph.com/v1/facebook/item",
    params={"q": "2796090964120499"},
    headers={"Authorization": f"Bearer {os.environ['SOLDGRAPH_KEY']}"},
)
data = res.json()
```

A cache miss returns **202** with a job to poll. A successful lookup costs one request. A listing that doesn't exist or was deleted fails with `not_found` and costs nothing. Results are cached for 15 minutes.

## What the fields mean

- `status` is the state the seller set: `active`, `pending`, `sold` or `unavailable`. A `sold` status is not a verified sale record, and its price is the last ask, not a sale price.
- `displayed_price` is the current ask. `original_price` is the earlier ask shown struck through when the seller lowered it.
- `location` is the public listing area with approximate coordinates and the Facebook `city_id`. It is not an address.
- Seller details are not public to logged-out visitors, so there is no seller field.
- Photo links are signed by Facebook and expire after some days.

## Example response

This listing was collected on October 1, 2026 (UTC).

```json title="Response"
{
  "request_id": "example-facebook-item",
  "status": "complete",
  "credits": 1,
  "cached": false,
  "result": {
    "provider": "facebook",
    "country": "us",
    "query": "2796090964120499",
    "collected_at": "2026-10-01T20:47:25.830554+00:00",
    "schema_version": 1,
    "count": 1,
    "data": {
      "id": "2796090964120499",
      "title": "Mountain bike",
      "description": "Needs TLC, haven’t rode in a couple years. Tires need air and put back on the rim. ",
      "link": "https://www.facebook.com/marketplace/item/2796090964120499/",
      "status": "active",
      "displayed_price": {
        "amount": 25,
        "currency": "USD"
      },
      "original_price": null,
      "condition": "used_fair",
      "listed_at": "2026-09-27T12:26:17+00:00",
      "location": {
        "name": "Belmont, NC",
        "latitude": 35.241394042969,
        "longitude": -81.051635742188,
        "city_id": "106100896087214"
      },
      "delivery": {
        "local_pickup": true,
        "shipping": false,
        "shipping_offered": false,
        "shipping_price_text": null
      },
      "category": {
        "id": "1658310421102081",
        "slug": "bicycles"
      },
      "photos": [
        "https://scontent-atl3-1.xx.fbcdn.net/v/t39.84726-6/825268359_3678580222299961_2039901778140218879_n.jpg?stp=dst-jpg_p720x720_tt6&_nc_cat=110&ccb=1-7&_nc_sid=92e707&_nc_ohc=joVdZ7b0uZ4Q7kNvwEyWUUA&_nc_oc=AdqPTGtXbSvNGMNgFG96X88jHAsPYDrRArzo8hogkbQatErRWDmcGqzbxtKmRAwDNa0&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=MoiWi6kD-AcCrnTLT40mpA&_nc_ss=7b289&oh=00_AQOP5tubua2p0SbrZfrBUIhNMVDijVdoohG9cgLR1Ldf5w&oe=6AC487BD",
        "https://scontent-atl3-2.xx.fbcdn.net/v/t45.5328-4/825291368_1598891671731725_6510958594325876185_n.jpg?stp=dst-jpg_p720x720_tt6&_nc_cat=102&ccb=1-7&_nc_sid=247b10&_nc_ohc=e-xe9w0EWDAQ7kNvwETgbfn&_nc_oc=Adrd3TaPnGcbb9u95lzdq_XLsNqkqBj9m7s4U25hYpUCpoOpaGzhfzEFzhP7zuI_kmQ&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=MoiWi6kD-AcCrnTLT40mpA&_nc_ss=7b289&oh=00_AQP3KFkt-qHwKBL8PbjPvjnRKgFRgFQX-KQ4Wuy2Gw2BNQ&oe=6AC48A6B",
        "https://scontent-atl3-1.xx.fbcdn.net/v/t45.5328-4/825291720_953292804524687_6403957870263446208_n.jpg?stp=dst-jpg_p720x720_tt6&_nc_cat=108&ccb=1-7&_nc_sid=247b10&_nc_ohc=tOmsjfJtfCoQ7kNvwEB-aUE&_nc_oc=AdpNkB4ZgkWycKMgdweadE6peR3ZnWWpJVe-ukg4SaTw7kzkV4JI_SecXo9vCwErka4&_nc_zt=23&_nc_ht=scontent-atl3-1.xx&_nc_gid=MoiWi6kD-AcCrnTLT40mpA&_nc_ss=7b289&oh=00_AQONjALKRbn8Im3LrQ7Mh_6fRj_u-Af5gYAuBLHBncgMxg&oe=6AC484C6"
      ]
    },
    "field_notes": "One Facebook Marketplace listing as shown publicly to logged-out visitors. Prices are seller asks; a sold status is not a verified sale record and its price is not a transaction price. Coordinates are the approximate public listing location, not an address. Seller details are not public to logged-out visitors. Image links are signed by Facebook and expire."
  }
}
```

| Field | Type | Description |
| --- | --- | --- |
| `request_id` | string | ID of this request. Poll it at `/v1/jobs/{request_id}`. |
| `status` | string | `pending`, `complete` or `failed`. Always check it, even on HTTP 200. |
| `credits` | integer | Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed. |
| `cached` | boolean | 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. |
| `error.code` | string | Only when failed. See [failed job codes](https://soldgraph.com/docs/api/errors.md#failed-job-codes). |
| `error.message` | string | Only when failed. What the code means, in plain words. |
| `result` | object | Only when complete. One source page from the marketplace. |
| `result.provider` | string | Marketplace ID, like `ebay` or `poshmark`. |
| `result.country` | string | The country searched: `us`, or on eBay the country you sent. |
| `result.query` | string | The `q` you sent, with extra spaces removed. |
| `result.page` | integer | The page you asked for. |
| `result.count` | integer | Rows in `result.data` on this page. |
| `result.reported_total` | integer | Total matches the marketplace reports for the search. It may be rounded or capped. |
| `result.next_page` | integer \| null | Send this as `page` to get the next page. Null on the last page, and on page 100, the deepest page served. |
| `result.collected_at` | string | When we collected the page, as an ISO 8601 timestamp. |
| `result.schema_version` | integer | Version of the result's shape for that marketplace: `1` or `2`. It only rises when a field changes meaning. |
| `result.completeness` | string | `provider_page_only`: one page as the marketplace served it, not a full history. TCGplayer recent sales say `recent_sample_only`. |
| `result.field_notes` | string | Plain-text notes on how to read this page's fields. |
| `result.data.id` | string | Facebook Marketplace item ID. |
| `result.data.title` | string \| null | The listing's title. |
| `result.data.link` | string | The listing's page on Facebook Marketplace. |
| `result.data.status` | string | `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. |
| `result.data.description` | string \| null | Seller description, up to 10,000 characters. |
| `result.data.displayed_price` | object | Current USD asking price. |
| `result.data.original_price` | object \| null | Earlier asking price shown struck through, else null. |
| `result.data.condition` | string \| null | `new`, `used_like_new`, `used_good`, `used_fair` or another source value, as the seller chose. |
| `result.data.listed_at` | string \| null | When the listing was posted, in UTC. |
| `result.data.location` | object | `name` (city, state), approximate `latitude` and `longitude`, and `city_id`. Not an address. |
| `result.data.delivery` | object | `local_pickup`, `shipping`, `shipping_offered` and `shipping_price_text` as Facebook shows it. |
| `result.data.category` | object | Category `id` and `slug`, such as `bicycles`. |
| `result.data.photos` | string[] | Photo URLs on Facebook's CDN, in listing order. Signed links that expire. |