Insights

Updated: Apr 29, 2026

This guide covers how to query ad performance data with Ads CLI, including date ranges, breakdowns, custom metrics, and sorting.

Query options

Basic usage

# Account-level metrics for the last 30 days (default)
meta ads insights get

# Specific metrics
meta ads insights get --adset-id <AD_SET_ID> --fields spend,impressions,ctr,cpc

Date ranges

Preset ranges

meta ads insights get --date-preset last_30d
meta ads insights get --date-preset yesterday

Available presets: today, yesterday, last_3d, last_7d, last_14d, last_30d, last_90d, this_month, last_month (same as the Marketing API)

Custom date range

meta ads insights get --since 2024-01-01 --until 2024-01-31

Note:--since and --until must be used together and override --date-preset.

Time granularity

Control how results are broken down over time with --time-increment:

Value	Description
`all_days` (default)	Aggregate across the entire date range
`daily`	One row per day
`weekly`	One row per week
`monthly`	One row per month

# Daily spend for the last 30 days
meta ads insights get --date-preset last_30d --time-increment daily --fields spend

# Weekly campaign performance
meta ads insights get --campaign-id <CAMPAIGN_ID> --time-increment weekly

Breakdowns

Add demographic or placement dimensions with --breakdown (repeatable):

Breakdown	Description
`age`	Age ranges
`gender`	Gender
`country`	Country
`publisher_platform`	Facebook, Instagram, Audience Network (see Breakdowns for others)
`device_platform`	Mobile, desktop
`platform_position`	Feed, Stories, Reels
`impression_device`	Device type

# Performance by age and gender
meta ads insights get --breakdown age --breakdown gender

# Platform comparison
meta ads insights get --breakdown publisher_platform --fields spend,impressions,ctr

Filtering

Filter results to a specific ad campaign, ad set, or ad:

meta ads insights get --campaign-id <CAMPAIGN_ID>
meta ads insights get --adset-id <AD_SET_ID>
meta ads insights get --ad-id <AD_ID>

Sorting

Sort results by a metric:

meta ads insights get --adset-id <AD_SET_ID> --sort spend_descending
meta ads insights get --adset-id <AD_SET_ID> --sort impressions_ascending

# Last 30 days, ad campaign level, sorted by spend
meta ads insights get --campaign-id <CAMPAIGN_ID> --date-preset last_30d --sort spend_descending

The format is <metric>_ascending or <metric>_descending.

Custom fields

Specify which metrics to include with --fields (comma-separated):

meta ads insights get --fields spend,impressions,clicks,ctr,cpc,reach
meta ads insights get --fields spend,conversions,cost_per_conversion,purchase_roas

Default fields: spend, impressions, clicks, ctr, cpc, reach

Any valid Meta Insights API field can be used. Common fields include:

Field	Description
`spend`	Total amount spent
`impressions`	Number of times ads were shown
`reach`	Number of unique users who saw the ad
`clicks`	Total clicks
`ctr`	Click-through rate
`cpc`	Cost per click
`cpm`	Cost per 1,000 impressions
`frequency`	Average number of times each person saw the ad
`conversions`	Number of conversions
`cost_per_conversion`	Cost per conversion
`purchase_roas`	Return on ad spend

Result limit

meta ads insights get --campaign-id <CAMPAIGN_ID> --limit 100    # Default: 50

Full options reference

Option	Default	Description
`--date-preset`	`last_30d`	Predefined date range
`--since`		Start date (YYYY-MM-DD). Requires `--until`
`--until`		End date (YYYY-MM-DD). Requires `--since`
`--time-increment`	`all_days`	Time granularity: `all_days`, `daily`, `weekly`, `monthly`
`--breakdown`		Breakdown dimension (repeatable)
`--fields`	`spend,impressions,...`	Comma-separated list of metrics
`--campaign-id`		Filter to an ad campaign
`--adset-id`		Filter to an ad set
`--ad-id`		Filter to an ad
`--sort`		Sort order (for example, `spend_descending`)
`--limit` / `-l`	50	Maximum rows to return