`chatgpt_ads_list_ads`

List ChatGPT Ads Ads

Chatgpt

Description

List ads in an ad group, including creative and review status. Either ad_group_id or ad_ids is required — the API has no account-wide or campaign-wide ad listing, so drill down via chatgpt_ads_list_ad_groups. An ad only delivers when it is approved AND its ad group and campaign are both active, so check review_status when an ad is not spending — filter on it with review_status: ["rejected"]. Pass ad_ids to resolve specific ads by ID without knowing their ad group. That is the way back from an insights row, which carries ad_id but no other context. Each returned ad carries the ad_group_id you requested; the API does not return it on the ad object.

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "chatgpt_ads_list_ads",
    "arguments": {
      "ad_group_id": "adgrp_abc123",
      "reason": "Review creatives and review status"
    }
  }
}

hopkin chatgpt ads list

Flag	Type	Required	Description
`--limit`	`integer`	Optional	Maximum number of results to return (1–100). Default: 20.
`--cursor`	`string`	Optional	Opaque pagination cursor from a previous response.
`--refresh`	`boolean`	Optional	Force a fresh fetch bypassing the cache.
`--ad-group-id`	`string`	Optional	Ad group to list ads for (e.g. "adgrp_abc123"). Required unless ad_ids is given — the API has no account-wide or campaign-wide ad listing. Get one from chatgpt_ads_list_ad_groups.
`--ad-ids`	`array`	Optional	Fetch specific ads by ID instead of listing, e.g. ["ad_abc123"]. Works without ad_group_id, and other filters are ignored when set.
`--status`	`array`	Optional	Filter by status: active, paused or archived. Case-insensitive. Applied client-side — the API has no status filter.
`--review-status`	`array`	Optional	Filter by review status: approved, in_review or rejected. Case-insensitive. An ad only delivers once approved. Applied client-side.
`--search`	`string`	Optional	Filter by name (case-insensitive substring match).
`--connection-id`	`string`	Optional	Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs.

{
  "mcpServers": {
    "chatgpt-ads": {
      "url": "https://chatgpt.mcp.hopkin.ai",
      "transport": "sse"
    }
  }
}

Parameters

Name	Type	Required	Description
`reason`	`string`	Required	Why this tool call is neededminLength: 1, maxLength: 500

Optional parameters (9)

Name	Type	Required	Description
`limit`	`integer`	Optional	Maximum number of results to return (1–100). Default: 20.min: 1, max: 100
`cursor`	`string`	Optional	Opaque pagination cursor from a previous response.
`refresh`	`boolean`	Optional	Force a fresh fetch bypassing the cache.
`ad_group_id`	`string`	Optional	Ad group to list ads for (e.g. "adgrp_abc123"). Required unless ad_ids is given — the API has no account-wide or campaign-wide ad listing. Get one from chatgpt_ads_list_ad_groups.minLength: 1, maxLength: 64, pattern: ^[A-Za-z0-9_-]+$
`ad_ids`	`array`	Optional	Fetch specific ads by ID instead of listing, e.g. ["ad_abc123"]. Works without ad_group_id, and other filters are ignored when set.
`status`	`array`	Optional	Filter by status: active, paused or archived. Case-insensitive. Applied client-side — the API has no status filter.
`review_status`	`array`	Optional	Filter by review status: approved, in_review or rejected. Case-insensitive. An ad only delivers once approved. Applied client-side.
`search`	`string`	Optional	Filter by name (case-insensitive substring match).minLength: 1, maxLength: 200
`connection_id`	`string`	Optional	Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs.

Examples

For an ad group

{
  "ad_group_id": "adgrp_abc123",
  "reason": "Review creatives and review status"
}

hopkin chatgpt ads list --ad-group-id adgrp_abc123

By ID

{
  "ad_ids": [
    "ad_abc123"
  ],
  "reason": "Resolve an ad id from an insights row"
}

hopkin chatgpt ads list --ad-ids ad_abc123

Not approved

{
  "ad_group_id": "adgrp_abc123",
  "review_status": [
    "rejected",
    "in_review"
  ],
  "reason": "Find ads blocked from delivering"
}

hopkin chatgpt ads list --ad-group-id adgrp_abc123 --review-status rejected,in_review