Getting started

​
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>

​
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

One two-letter country code 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. 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>
​
--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>
​
--language

Two-letter uppercase ad language filter, for example EN.

Type: string. Optional.

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

​
ads search

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

One two-letter country code 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. 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>
​
--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>

​
advertisers search

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>

​
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.