> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/mcp-server/tools-and-support/tools/citations-and-ads.md).

# Citations & Ads

Inspect citations, domains, observed ads, and advertisers for tracked prompts.

Inspect citations, domains, observed ads, and advertisers for tracked prompts.

See [plan access](broken://pages/GlhqboJgu5fTfPseY3y1#plan-access) and [query options](broken://pages/GlhqboJgu5fTfPseY3y1#query-options) for shared requirements.

## Citations & Domains

For citation and domain lists, use `prompt_type` with operator `EQUALS` and value `brand` or `category` to filter by whether the prompt names your brand. Use `brand_mentioned` with operator `EQ` and value `true` or `false` to filter by whether the citing page mentions your brand.

The older `brand_mentioned EQUALS brand/category` and `brand_referenced EQ true/false` filters remain accepted as compatibility aliases. Prefer the explicit names above; they take precedence when both old and new filters are supplied. The `brand_mentioned` filter on `list_aeo_prompts` still refers to the prompt text.

For citation and domain lists, `citation_rate` is the percentage of distinct answers in scope that cite the URL or domain. Answer filters, such as platform, country, topic, and prompt type, set that scope. Source filters, such as domain, page type, or whether the citing page mentions your brand, narrow the returned rows without changing the rate denominator. `citation_rate_trend` is the current rate minus the comparison-period rate, in percentage points.

### `list_aeo_citations`

List citations (URLs) with metrics for a Brand Kit. Shows individual URLs being cited in AI answers.

**Requires:** `brand_kit_id`

**Returns:** URL, domain name, domain category, citation count, citation share, citation rate, influence score, page type, brand sentiment, trends, and social metadata when available.

The `social` object identifies the platform and contains `content` and `account` envelopes with metadata, metrics, and sync status. It is `null` when no supported social record exists. The account can be `null` when content exists without an associated account. Pending or failed collection can leave metadata incomplete.

YouTube content metadata includes `duration_seconds`, `format`, and `sponsorship_status`. Duration can be `null`; format and sponsorship status use `unknown` when unavailable.

| Parameter        | Values                                                                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Filters**      | domain\_category, domain\_id, topic\_id, prompt\_type, brand\_mentioned, page\_type, brand\_sentiment, mentioned\_competitor\_domains |
| **Sort**         | citation\_count, citation\_share, citation\_rate, influence\_score                                                                    |
| **Date filters** | start\_date, end\_date, providers, countries, personas                                                                                |

Use `url EQUALS` for an exact normalized URL match. URL matching is case-sensitive. `CONTAINS` treats percent signs, underscores, and backslashes as literal text. Unknown fields, unsupported operators, invalid values, and invalid or reversed dates return errors.

#### Optional citation lifecycle fields

Request lifecycle metrics through `fields`. They are omitted from the default response and use the selected dates and scope, with Monday-based weeks.

| Field                              | Meaning                                                                             |
| ---------------------------------- | ----------------------------------------------------------------------------------- |
| `first_cited`, `last_cited`        | First and last observed citation dates within the selected period.                  |
| `peak_week`                        | Monday of the earliest week with the highest citation count.                        |
| `rise_days`, `rise_weeks`          | Time from the first citation to the peak week; weeks can be fractional.             |
| `decline_absolute`, `decline_pct`  | Decline from the peak count to the latest full-week count. The percentage is 0–100. |
| `decline_week`                     | Monday of the full week used for the decline comparison.                            |
| `half_life_week`, `half_life_days` | The confirmed half-life week and elapsed days from the peak.                        |

Decline fields can be `null` without a full comparison week. Half-life fields can be `null` when no sustained halving has been observed. These are selected-period metrics, not lifetime values. See [citation lifecycle definitions](broken://pages/ZzcAxBzhAA7jUd47FejL#how-lifecycle-metrics-are-calculated).

For example, find citations with at least a 50% decline and sort the largest declines first. Replace `123` with your Brand Kit ID:

```json
{
  "brand_kit_id": 123,
  "start_date": "2026-09-01",
  "end_date": "2026-10-18",
  "fields": ["url", "decline_pct", "half_life_days"],
  "filters": [{"field": "decline_pct", "operator": "GEQ", "value": 50}],
  "sort": "-decline_pct"
}
```

Use a nullable field's supported `IS_NULL` or `IS_NOT_NULL` operator with `value: null` to inspect unavailable values.

**Domain categories:** Owned, Competitors, Social, Communities, Reviews, Media, Educational, Marketplaces, Products, Affiliates, Other

***

### `get_aeo_citation`

Get details and prompts citing a specific URL.

**Requires:** `brand_kit_id`, `id` (the URL to look up)

**Returns:** `url`, citing `prompts`, `social`, and `brand_sentiment`. Request the lifecycle fields listed above or `weekly_series` through `fields` to include them.

`weekly_series` contains `[Monday date, citation count]` pairs from the first cited week in the selected scope, including zero-count weeks. It is available only on this detail tool. An unknown URL returns an empty series and null lifecycle values.

```json
{
  "brand_kit_id": 123,
  "id": "https://example.com/guide",
  "start_date": "2026-09-01",
  "end_date": "2026-10-18",
  "fields": ["decline_pct", "half_life_days", "weekly_series"]
}
```

The detail tool accepts `topic_id EQ/IN` and `prompt_type EQUALS` filters for citing prompts. It does not accept every list filter, including page-level `brand_mentioned EQ`. Use the list tool to narrow pages before inspecting a URL.

***

### `list_aeo_domains`

List domains cited in AI answers for a Brand Kit. Aggregated by domain with citation metrics.

**Requires:** `brand_kit_id`

**Returns:** Domain ID, name, category, logo URL, citation count, URL count, citation share, citation rate, and trends.

| Parameter        | Values                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------- |
| **Filters**      | domain\_category, topic\_id, prompt\_type, brand\_mentioned, page\_type, brand\_sentiment |
| **Sort**         | citation\_count, citation\_share, citation\_rate                                          |
| **Date filters** | start\_date, end\_date, providers, countries, personas                                    |

Use `domain_name EQUALS` to match a full domain without case sensitivity. Use the fields and operators declared by the tool; invalid filters return an error.

***

## AEO Observed Ads & Advertisers

Ads AirOps observes in ChatGPT and Google AI Mode answers for your tracked prompts. These tools query observed ad data used by [Ads](broken://pages/Lc9T8hsyYHL32rxzhRop), including **Ad Library**, so they need no ChatGPT Ads account connection.

{% hint style="info" %}
Coverage is limited to ads AirOps has seen in its own answer collection. These numbers do not describe full market coverage, targeting intent, impression delivery, or advertiser spend.
{% endhint %}

### `list_aeo_ads`

List ads observed in ChatGPT and Google AI Mode answers for a Brand Kit. Each row represents a platform and observed creative pair. The same creative on two platforms produces two rows, each with its own activity counts.

**Requires:** `brand_kit_id`

**Returns:** Provider, observed creative ID, observed family ID, advertiser name, domain, type and logo, ad title and body, appearances, answers, prompts, frequency, first\_seen, last\_seen, and days\_active.

| Parameter        | Values                                                       |
| ---------------- | ------------------------------------------------------------ |
| **Filters**      | topic\_id, prompt\_id, prompt\_type                          |
| **Date filters** | start\_date, end\_date, providers, countries, personas, tags |

**Advertiser types:** owned, competitor, other

`list_aeo_ads` includes both supported providers by default. Pass `providers: ["chat_gpt"]` or `providers: ["google_ai_mode"]` to narrow the scope. Use `prompt_type EQUALS brand/category` for prompt classification; the former `brand_mentioned` prompt-type filter remains a compatibility alias.

***

### `get_aeo_ad`

Get one observed ad, including its creative image and destination URL.

**Requires:** `brand_kit_id`, `id` (the `observed_creative_id` returned by `list_aeo_ads`)

**Returns:** Provider, observed creative ID, observed family ID, advertiser name, domain, type and logo, ad title, body, image\_url, target\_url, first\_seen, last\_seen, and days\_active.

Pass the row's provider as a single-element `providers` array along with its creative ID, for example `providers: ["google_ai_mode"]`. Detail requests default to ChatGPT when no provider is specified and require a single provider when one is supplied.

The windowed metrics reported by `list_aeo_ads` (appearances, answers, prompts, frequency) are not returned here.

***

### `list_aeo_advertisers`

List advertisers observed in ChatGPT and Google AI Mode answers for a Brand Kit. Every observed ad rolls up to the advertiser that ran it, identified by canonical domain.

**Requires:** `brand_kit_id`

**Returns:** Advertiser ID, name, domain, type, logo URL, unique ad count, appearances, answers, prompts, first\_seen, and last\_seen.

| Parameter        | Values                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| **Filters**      | topic\_id, prompt\_id, prompt\_type                                                               |
| **Sort**         | advertiser\_name, advertiser\_domain, ads, appearances, answers, prompts, first\_seen, last\_seen |
| **Date filters** | start\_date, end\_date, providers, countries, personas, tags                                      |

Results are sorted by unique ad count, most prolific first, unless you pass **Sort**. Use `list_aeo_ads` for the individual ads behind each advertiser's counts.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/mcp-server/tools-and-support/tools/citations-and-ads.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.