Research

research meta-ads

Research public ads and advertisers in the Meta Ad Library. Find an ad or advertiser, then retrieve details by ad ID or page ID.

Usage

terminal
orc research meta-ads advertisers ads list --page-id 123456789 --country JP --status ACTIVE --workspace YOUR_WORKSPACE_ID --format json

Retrieve an advertiser’s active ads in Japan

Subcommands

ads get

Get Meta ad

terminal
orc research meta-ads ads get [options]

Unique options

--ad-id

ad_archive_id from an ad search or advertiser listing; not page_id.

Type: string. Required.

terminal
orc research meta-ads ads get --ad-id <value>
--max-age

Maximum age in seconds of a stored acquisition to return instead of acquiring again. Default 172800 (2 days); 0 always acquires fresh. Stored results are shared public observations; source.observed_at is the original acquisition time.; (use "null" or "reset" to clear)

Type: number. Optional.

terminal
orc research meta-ads ads get --max-age <value>

advertisers ads list

List Meta advertiser ads

terminal
orc research meta-ads advertisers ads list [options]

Unique options

--page-id

Source numeric identifier, sent as a string to preserve precision.

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --page-id <value>
--advertiser-name

Advertiser name, alternative to page_id.; max 500 chars

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --advertiser-name <value>
--country

Two-letter country code, up to ten comma-separated (Ad Library reader only), or ALL. Default ALL.

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --country <value>
--status

Ad delivery status filter. Default ACTIVE.; enum: ALL|ACTIVE|INACTIVE

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --status <value>
--media-type

Source media category; MEME means text with an image. Omitted means provider default ALL.; enum: ALL|IMAGE|VIDEO|MEME|IMAGE_AND_MEME|NONE

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --media-type <value>
--sort-by

Source ordering: impressions or recent monthly relevance. With total_impressions the Ad Library reader reports each ad's impressions_rank and its change over time. Does not imply exact impression counts are available.; enum: total_impressions|relevancy_monthly_grouped

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --sort-by <value>
--publisher-platform

Placement filter. Served by the Ad Library itself; vendors without this filter are not used for it.; enum: FACEBOOK|INSTAGRAM|AUDIENCE_NETWORK|MESSENGER|WHATSAPP|THREADS

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --publisher-platform <value>
--start-date

Calendar date in YYYY-MM-DD. Date range refers to source advertising delivery/impression filters, not an exhaustive archive.

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --start-date <value>
--end-date

Calendar date in YYYY-MM-DD. Date range refers to source advertising delivery/impression filters, not an exhaustive archive.

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --end-date <value>
--include-transparency

true adds EU reach, targeted gender/age/locations and payer for EU-delivered ads (one extra detail lookup per page). Only the Ad Library reader supplies it; a vendor fallback returns the ads without it.; enum: true|false

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --include-transparency <value>
--language

Two-letter uppercase ad language filter, for example EN; up to ten comma-separated with the Ad Library reader.

Type: string. Optional.

terminal
orc research meta-ads advertisers ads list --language <value>
--max-age

Maximum age in seconds of a stored acquisition to return instead of acquiring again. Default 172800 (2 days); 0 always acquires fresh. Stored results are shared public observations; source.observed_at is the original acquisition time.; (use "null" or "reset" to clear)

Type: number. Optional.

terminal
orc research meta-ads advertisers ads list --max-age <value>

Search Meta ads

terminal
orc research meta-ads ads search [options]

Unique options

--query

Search text. Search indexes do not guarantee exhaustive coverage.; max 500 chars

Type: string. Required.

terminal
orc research meta-ads ads search --query <value>
--country

Two-letter country code, up to ten comma-separated (Ad Library reader only), or ALL. Default ALL.

Type: string. Optional.

terminal
orc research meta-ads ads search --country <value>
--status

Ad delivery status filter. Default ACTIVE.; enum: ALL|ACTIVE|INACTIVE

Type: string. Optional.

terminal
orc research meta-ads ads search --status <value>
--media-type

Source media category; MEME means text with an image. Omitted means provider default ALL.; enum: ALL|IMAGE|VIDEO|MEME|IMAGE_AND_MEME|NONE

Type: string. Optional.

terminal
orc research meta-ads ads search --media-type <value>
--sort-by

Source ordering: impressions or recent monthly relevance. With total_impressions the Ad Library reader reports each ad's impressions_rank and its change over time. Does not imply exact impression counts are available.; enum: total_impressions|relevancy_monthly_grouped

Type: string. Optional.

terminal
orc research meta-ads ads search --sort-by <value>
--publisher-platform

Placement filter. Served by the Ad Library itself; vendors without this filter are not used for it.; enum: FACEBOOK|INSTAGRAM|AUDIENCE_NETWORK|MESSENGER|WHATSAPP|THREADS

Type: string. Optional.

terminal
orc research meta-ads ads search --publisher-platform <value>
--start-date

Calendar date in YYYY-MM-DD. Date range refers to source advertising delivery/impression filters, not an exhaustive archive.

Type: string. Optional.

terminal
orc research meta-ads ads search --start-date <value>
--end-date

Calendar date in YYYY-MM-DD. Date range refers to source advertising delivery/impression filters, not an exhaustive archive.

Type: string. Optional.

terminal
orc research meta-ads ads search --end-date <value>
--search-type

Keyword matching mode.; enum: keyword_unordered|keyword_exact_phrase

Type: string. Optional.

terminal
orc research meta-ads ads search --search-type <value>
--ad-type

Public library category; defaults to all at the provider.; enum: all|political_and_issue_ads

Type: string. Optional.

terminal
orc research meta-ads ads search --ad-type <value>
--max-age

Maximum age in seconds of a stored acquisition to return instead of acquiring again. Default 172800 (2 days); 0 always acquires fresh. Stored results are shared public observations; source.observed_at is the original acquisition time.; (use "null" or "reset" to clear)

Type: number. Optional.

terminal
orc research meta-ads ads search --max-age <value>

Search Meta advertisers

terminal
orc research meta-ads advertisers search [options]

Unique options

--query

Search text. Search indexes do not guarantee exhaustive coverage.; max 500 chars

Type: string. Required.

terminal
orc research meta-ads advertisers search --query <value>
--sort

source keeps provider order; trust ranks Facebook-verified pages, then Instagram-verified accounts, then the larger of page likes and Instagram followers. Applied by Orchestor to the returned page only.; enum: source|trust

Type: string. Optional.

terminal
orc research meta-ads advertisers search --sort <value>
--max-age

Maximum age in seconds of a stored acquisition to return instead of acquiring again. Default 172800 (2 days); 0 always acquires fresh. Stored results are shared public observations; source.observed_at is the original acquisition time.; (use "null" or "reset" to clear)

Type: number. Optional.

terminal
orc research meta-ads advertisers search --max-age <value>

advertisers landing-pages list

List Meta advertiser landing pages

terminal
orc research meta-ads advertisers landing-pages list [options]

Unique options

--page-id

Meta advertiser page ID.

Type: string. Optional.

terminal
orc research meta-ads advertisers landing-pages list --page-id <value>
--company-domain

Advertiser website in example.com form, alternative to page_id. The provider finds the Facebook page linked from the site.; max 253 chars

Type: string. Optional.

terminal
orc research meta-ads advertisers landing-pages list --company-domain <value>
--country

Two-letter country code, up to ten comma-separated (Ad Library reader only), or ALL. Default ALL.

Type: string. Optional.

terminal
orc research meta-ads advertisers landing-pages list --country <value>
--status

Ad delivery status filter. Default ALL, so inactive pages are counted.; enum: ALL|ACTIVE|INACTIVE

Type: string. Optional.

terminal
orc research meta-ads advertisers landing-pages list --status <value>
--max-age

Maximum age in seconds of a stored acquisition to return instead of acquiring again. Default 172800 (2 days); 0 always acquires fresh. Stored results are shared public observations; source.observed_at is the original acquisition time.; (use "null" or "reset" to clear)

Type: number. Optional.

terminal
orc research meta-ads advertisers landing-pages list --max-age <value>

advertisers partners list

List Meta advertiser partners

terminal
orc research meta-ads advertisers partners list [options]

Unique options

--page-id

Brand Facebook page ID.

Type: string. Required.

terminal
orc research meta-ads advertisers partners list --page-id <value>
--advertiser-name

Brand name searched for partnership ads filed under creator pages; defaults to the page name.; max 500 chars

Type: string. Optional.

terminal
orc research meta-ads advertisers partners list --advertiser-name <value>
--status

Ad delivery status filter. Default ALL.; enum: ALL|ACTIVE|INACTIVE

Type: string. Optional.

terminal
orc research meta-ads advertisers partners list --status <value>
--country

Two-letter country code, up to ten comma-separated (Ad Library reader only), or ALL. Default ALL.

Type: string. Optional.

terminal
orc research meta-ads advertisers partners list --country <value>
--cpm

CPM in USD for estimated_spend_usd. Default 9.; (use "null" or "reset" to clear)

Type: number. Optional.

terminal
orc research meta-ads advertisers partners list --cpm <value>
--max-age

Maximum age in seconds of a stored acquisition to return instead of acquiring again. Default 172800 (2 days); 0 always acquires fresh. Stored results are shared public observations; source.observed_at is the original acquisition time.; (use "null" or "reset" to clear)

Type: number. Optional.

terminal
orc research meta-ads advertisers partners list --max-age <value>

Output and continuation

Each call returns one page. When continuation is available, pass the top-level pagination.next_cursor as --cursor with unchanged filters. Never replay data.next_cursor. has_more: null means unknown, not complete. --page-all is unavailable.

JSON retains records in data.data, continuation in data.pagination and provenance in data.source. --raw removes the CLI envelope; --field data selects the API data. Missing and null values do not mean zero.

data.usage.provider_credits uses the provider’s units, not Orchestor billing units. See each API reference for coverage and provider-specific constraints.

Permissions

Sign in with orc auth login using a beta-approved account, or use an API key with the read scope. Select an accessible workspace with --workspace. No research-specific workspace allowlist is required.

Global Options

The following global options can be used with orc research meta-ads:

For details and examples, see global options.