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
orc research meta-ads advertisers ads list --page-id 123456789 --country JP --status ACTIVE --workspace YOUR_WORKSPACE_ID --format jsonRetrieve an advertiser’s active ads in Japan
Subcommands
ads get
Get Meta ad
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.
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.
orc research meta-ads ads get --max-age <value>advertisers ads list
List Meta advertiser ads
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.
orc research meta-ads advertisers ads list --page-id <value>--advertiser-name
Advertiser name, alternative to page_id.; max 500 chars
Type: string. Optional.
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.
orc research meta-ads advertisers ads list --country <value>--status
Ad delivery status filter. Default ACTIVE.; enum: ALL|ACTIVE|INACTIVE
Type: string. Optional.
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.
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.
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.
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.
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.
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.
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.
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.
orc research meta-ads advertisers ads list --max-age <value>ads search
Search Meta ads
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.
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.
orc research meta-ads ads search --country <value>--status
Ad delivery status filter. Default ACTIVE.; enum: ALL|ACTIVE|INACTIVE
Type: string. Optional.
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.
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.
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.
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.
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.
orc research meta-ads ads search --end-date <value>--search-type
Keyword matching mode.; enum: keyword_unordered|keyword_exact_phrase
Type: string. Optional.
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.
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.
orc research meta-ads ads search --max-age <value>advertisers search
Search Meta advertisers
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.
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.
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.
orc research meta-ads advertisers search --max-age <value>advertisers landing-pages list
List Meta advertiser landing pages
orc research meta-ads advertisers landing-pages list [options]Unique options
--page-id
Meta advertiser page ID.
Type: string. Optional.
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.
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.
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.
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.
orc research meta-ads advertisers landing-pages list --max-age <value>advertisers partners list
List Meta advertiser partners
orc research meta-ads advertisers partners list [options]Unique options
--page-id
Brand Facebook page ID.
Type: string. Required.
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.
orc research meta-ads advertisers partners list --advertiser-name <value>--status
Ad delivery status filter. Default ALL.; enum: ALL|ACTIVE|INACTIVE
Type: string. Optional.
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.
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.
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.
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.