Submit Facebook Marketplace Search task

curl --request POST \
  --url https://api.socq.ai/v1/facebook-marketplace/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "bike",
  "latitude": 30.2677,
  "longitude": -97.7475,
  "results_limit": 100,
  "radius_km": 65,
  "sort_by": "creation_time_descend"
}
'

import requests

url = "https://api.socq.ai/v1/facebook-marketplace/search"

payload = {
    "query": "bike",
    "latitude": 30.2677,
    "longitude": -97.7475,
    "results_limit": 100,
    "radius_km": 65,
    "sort_by": "creation_time_descend"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: 'bike',
    latitude: 30.2677,
    longitude: -97.7475,
    results_limit: 100,
    radius_km: 65,
    sort_by: 'creation_time_descend'
  })
};

fetch('https://api.socq.ai/v1/facebook-marketplace/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.socq.ai/v1/facebook-marketplace/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => 'bike',
    'latitude' => 30.2677,
    'longitude' => -97.7475,
    'results_limit' => 100,
    'radius_km' => 65,
    'sort_by' => 'creation_time_descend'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.socq.ai/v1/facebook-marketplace/search"

	payload := strings.NewReader("{\n  \"query\": \"bike\",\n  \"latitude\": 30.2677,\n  \"longitude\": -97.7475,\n  \"results_limit\": 100,\n  \"radius_km\": 65,\n  \"sort_by\": \"creation_time_descend\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.socq.ai/v1/facebook-marketplace/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"bike\",\n  \"latitude\": 30.2677,\n  \"longitude\": -97.7475,\n  \"results_limit\": 100,\n  \"radius_km\": 65,\n  \"sort_by\": \"creation_time_descend\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.socq.ai/v1/facebook-marketplace/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"bike\",\n  \"latitude\": 30.2677,\n  \"longitude\": -97.7475,\n  \"results_limit\": 100,\n  \"radius_km\": 65,\n  \"sort_by\": \"creation_time_descend\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "data": {
    "task_id": "A1B2C3D4E5F6G7H8",
    "status": "queued",
    "created_time": "2026-07-17T10:29:30"
  }
}

{
  "code": 123,
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "code": 123,
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "code": 123,
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

POST

facebook-marketplace

Submit Facebook Marketplace Search task

curl --request POST \
  --url https://api.socq.ai/v1/facebook-marketplace/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "bike",
  "latitude": 30.2677,
  "longitude": -97.7475,
  "results_limit": 100,
  "radius_km": 65,
  "sort_by": "creation_time_descend"
}
'

import requests

url = "https://api.socq.ai/v1/facebook-marketplace/search"

payload = {
    "query": "bike",
    "latitude": 30.2677,
    "longitude": -97.7475,
    "results_limit": 100,
    "radius_km": 65,
    "sort_by": "creation_time_descend"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: 'bike',
    latitude: 30.2677,
    longitude: -97.7475,
    results_limit: 100,
    radius_km: 65,
    sort_by: 'creation_time_descend'
  })
};

fetch('https://api.socq.ai/v1/facebook-marketplace/search', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.socq.ai/v1/facebook-marketplace/search",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => 'bike',
    'latitude' => 30.2677,
    'longitude' => -97.7475,
    'results_limit' => 100,
    'radius_km' => 65,
    'sort_by' => 'creation_time_descend'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.socq.ai/v1/facebook-marketplace/search"

	payload := strings.NewReader("{\n  \"query\": \"bike\",\n  \"latitude\": 30.2677,\n  \"longitude\": -97.7475,\n  \"results_limit\": 100,\n  \"radius_km\": 65,\n  \"sort_by\": \"creation_time_descend\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.socq.ai/v1/facebook-marketplace/search")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"bike\",\n  \"latitude\": 30.2677,\n  \"longitude\": -97.7475,\n  \"results_limit\": 100,\n  \"radius_km\": 65,\n  \"sort_by\": \"creation_time_descend\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.socq.ai/v1/facebook-marketplace/search")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"bike\",\n  \"latitude\": 30.2677,\n  \"longitude\": -97.7475,\n  \"results_limit\": 100,\n  \"radius_km\": 65,\n  \"sort_by\": \"creation_time_descend\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "data": {
    "task_id": "A1B2C3D4E5F6G7H8",
    "status": "queued",
    "created_time": "2026-07-17T10:29:30"
  }
}

{
  "code": 123,
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "code": 123,
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "code": 123,
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

Marketplace Search

Search public listings around a geographic coordinate. Use Marketplace Location Search to find coordinates when needed.

Request Example

{
  "query": "bike",
  "latitude": 30.2677,
  "longitude": -97.7475,
  "results_limit": 100,
  "radius_km": 65,
  "min_price": 100,
  "max_price": 500,
  "sort_by": "creation_time_descend",
  "delivery_method": "local_pickup",
  "condition": "used_good",
  "date_listed": "last_7_days",
  "availability": "available"
}

SocQ follows result pagination until results_limit is reached or no additional page is available. Duplicate listing IDs are saved once, so the final result_count can be lower than the requested limit.

Completed Task Response

{
  "code": 200,
  "data": {
    "task_id": "A1B2C3D4E5F6G7H8",
    "status": "succeeded",
    "public_id": "facebook-marketplace/search",
    "result_count": 1,
    "credits_amount": 0.7,
    "results": {
      "limit": 50,
      "next_cursor": null,
      "has_more": false,
      "items": [{
        "id": "1880804689276480",
        "platform": "facebook-marketplace",
        "resource": "search",
        "type": "listing",
        "url": "https://www.facebook.com/marketplace/item/1880804689276480/",
        "name": "Electric bike",
        "text": null,
        "author": {"id": null, "username": null, "name": null, "url": null},
        "metrics": {},
        "media": [{"type": "image", "url": "https://example.com/bike.jpg", "width": 960, "height": 720}],
        "created_at": null,
        "collected_at": "2026-07-18T10:30:00",
        "extra": {
          "search_query": "bike",
          "price": {"amount": 300, "currency": "USD", "formatted": "$300"},
          "location": {"text": "Austin, Texas", "city": "Austin", "state": "TX"},
          "category_id": "1658310421102081",
          "is_live": true,
          "is_sold": false
        }
      }]
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

query

string

required

Listing keyword. The value cannot be empty.

Minimum string length: 1

latitude

number

required

Search center latitude from -90 through 90.

Required range: -90 <= x <= 90

longitude

number

required

Search center longitude from -180 through 180.

Required range: -180 <= x <= 180

results_limit

integer

default:100

Maximum listings to save across result pages.

Required range: 1 <= x <= 2000

radius_km

number

Search radius in kilometers. Must be greater than 0.

Required range: x > 0

min_price

number

Minimum listing price.

Required range: x >= 0

max_price

number

Maximum listing price. Cannot be less than min_price.

Required range: x >= 0

sort_by

enum<string>

Listing sort order.

Available options:

suggested,

distance_ascend,

creation_time_descend,

price_ascend,

price_descend

delivery_method

enum<string>

Delivery option filter.

Available options:

all,

local_pickup,

shipping

condition

enum<string>

Item condition filter.

Available options:

new,

used_like_new,

used_good,

used_fair

date_listed

enum<string>

Listing age filter.

Available options:

all,

1,

7,

30,

last_24_hours,

last_7_days,

last_30_days

availability

enum<string>

Listing availability filter.

Available options:

available,

sold,

all

callback_url

string<uri>

Optional URL that receives the task completion callback.

Response

Task submitted

code

integer

Example:

200

data

object

Show child attributes

Marketplace Location Search Marketplace Item

⌘I

Overview

Instagram

Facebook

Facebook Marketplace

Facebook Ad Library

YouTube

TikTok

TikTok Shop

X

LinkedIn

Reddit

Pinterest

Threads

Common

Marketplace Search

Marketplace Search

Request Example

Completed Task Response

Authorizations

Body

Response

​Marketplace Search

​Request Example

​Completed Task Response

Authorizations

Body

Response

Marketplace Search

Request Example

Completed Task Response