--- title: research meta-ads description: Research public ads and advertisers in the Meta Ad Library. canonical_url: https://orchestor.io/docs/en/cli/research/meta-ads markdown_url: https://orchestor.io/docs/en/cli/research/meta-ads.md contentType: reference --- # 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 ```bash title="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 ```bash title="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. ```bash title="terminal" orc research meta-ads ads get --ad-id ``` ### `advertisers ads list` List Meta advertiser ads ```bash title="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. ```bash title="terminal" orc research meta-ads advertisers ads list --page-id ``` ##### `--advertiser-name` Advertiser name, alternative to page_id.; max 500 chars Type: `string`. Optional. ```bash title="terminal" orc research meta-ads advertisers ads list --advertiser-name ``` ##### `--country` One two-letter country code or ALL. Default ALL. Type: `string`. Optional. ```bash title="terminal" orc research meta-ads advertisers ads list --country ``` ##### `--status` Ad delivery status filter. Default ACTIVE.; enum: ALL|ACTIVE|INACTIVE Type: `string`. Optional. ```bash title="terminal" orc research meta-ads advertisers ads list --status ``` ##### `--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. ```bash title="terminal" orc research meta-ads advertisers ads list --media-type ``` ##### `--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. ```bash title="terminal" orc research meta-ads advertisers ads list --sort-by ``` ##### `--start-date` Calendar date in YYYY-MM-DD. Date range refers to source advertising delivery/impression filters, not an exhaustive archive. Type: `string`. Optional. ```bash title="terminal" orc research meta-ads advertisers ads list --start-date ``` ##### `--end-date` Calendar date in YYYY-MM-DD. Date range refers to source advertising delivery/impression filters, not an exhaustive archive. Type: `string`. Optional. ```bash title="terminal" orc research meta-ads advertisers ads list --end-date ``` ##### `--language` Two-letter uppercase ad language filter, for example EN. Type: `string`. Optional. ```bash title="terminal" orc research meta-ads advertisers ads list --language ``` ### `ads search` Search Meta ads ```bash title="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. ```bash title="terminal" orc research meta-ads ads search --query ``` ##### `--country` One two-letter country code or ALL. Default ALL. Type: `string`. Optional. ```bash title="terminal" orc research meta-ads ads search --country ``` ##### `--status` Ad delivery status filter. Default ACTIVE.; enum: ALL|ACTIVE|INACTIVE Type: `string`. Optional. ```bash title="terminal" orc research meta-ads ads search --status ``` ##### `--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. ```bash title="terminal" orc research meta-ads ads search --media-type ``` ##### `--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. ```bash title="terminal" orc research meta-ads ads search --sort-by ``` ##### `--start-date` Calendar date in YYYY-MM-DD. Date range refers to source advertising delivery/impression filters, not an exhaustive archive. Type: `string`. Optional. ```bash title="terminal" orc research meta-ads ads search --start-date ``` ##### `--end-date` Calendar date in YYYY-MM-DD. Date range refers to source advertising delivery/impression filters, not an exhaustive archive. Type: `string`. Optional. ```bash title="terminal" orc research meta-ads ads search --end-date ``` ##### `--search-type` Keyword matching mode.; enum: keyword_unordered|keyword_exact_phrase Type: `string`. Optional. ```bash title="terminal" orc research meta-ads ads search --search-type ``` ##### `--ad-type` Public library category; defaults to all at the provider.; enum: all|political_and_issue_ads Type: `string`. Optional. ```bash title="terminal" orc research meta-ads ads search --ad-type ``` ### `advertisers search` Search Meta advertisers ```bash title="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. ```bash title="terminal" orc research meta-ads advertisers search --query ``` ## 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](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc research meta-ads`: - [`--help`](https://orchestor.io/docs/cli/global-flags.md#help) - [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace) - [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output) - [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format) - [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection) - [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output) - [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output) - [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager) - [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run) - [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) - [`--cursor`](https://orchestor.io/docs/cli/global-flags.md) - [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input) - [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing) For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md). --- [Documentation index](https://orchestor.io/docs/llms.txt)