Skip to main content
POST
Facebook Ad Library Company Ads API

Company Ads

Collect public ads associated with one page ID returned by Company Search.

Request Example

Use with MCP

Use the JSON request body above as the nested input object for socq_execute, or pass the same fields directly to the typed tool. Typed tools also accept _wait_seconds, _result_limit, and _idempotency_key.
A successful collection returns a task_id. Continue with socq_get_task until the task succeeds, then read normalized records from results.items.
See MCP quickstart for the complete submission and polling flow. The final result can contain fewer records than results_limit when no additional page is available or duplicate ad IDs are removed.

Result Fields

Task results use the stable SocQ fields below. Source-specific field names and formats are normalized without inferring or enriching values that the source did not provide. To request a smaller field set, use fields for MCP queries, _result_fields for typed tools, or --result-fields in the CLI. Declared fields remain present when their value is null.

Completed Task Response

Authorizations

Authorization
string
header
required

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

Body

application/json
page_id
string
required

A public page identifier.

Minimum string length: 1
country
string
Minimum string length: 1
end_date
string
Minimum string length: 1
language
string
Minimum string length: 1
media_type
string
Minimum string length: 1
results_limit
integer
Required range: 1 <= x <= 2000
sort_by
string
Minimum string length: 1
start_date
string
Minimum string length: 1
status
string
Minimum string length: 1

Response

Task accepted

code
integer
data
object