list_ads
List distinct ads (creatives) for an ad account. Use this to drill down from list_campaigns into individual ads.
In Meta, an “ad” carries a creative asset (creative_name is populated); in Google Ads, an “ad” is a keyword-or-responsive-search-ad variant.
Parameters#
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
ad_account_id | string | yes | Ad account id | |
status | string? | no | null | Filter: enabled, paused, or removed |
limit | integer | no | 100 | Max ads to return; clamped to 500 |
offset | integer | no | 0 | Pagination offset |
Returns#
json
{
"ads": [
{
"ad_id": "987654",
"ad_name": "Video hero v2",
"ad_status": "enabled",
"ad_type": "VIDEO",
"platform": "meta_ads",
"creative_name": "Hero Spring 2026",
"ad_group_id": "adset_1",
"ad_group_name": "Retargeting - 30d",
"campaign_id": "c1",
"campaign_name": "Retargeting - Core"
}
],
"count": 1,
"total": 81,
"offset": 0,
"limit": 100,
"has_more": false,
"source": "adlyse.ads_ads@v1"
}| Field | Description |
|---|---|
ads[].ad_id | Platform’s native ad id |
ads[].creative_name | Populated for Meta only |
ads[].ad_group_id | Meta: ad set id. Google: ad group id |
Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
not_found | Ad account doesn’t belong to your org |
Example#
Request:
json
{ "ad_account_id": "ad_acct_abc", "status": "enabled", "limit": 5 }Response: as shown above.
See also#
get_ad_performance— per-ad metric aggregationlist_change_events— creative swaps and ad-level edits