> ## Documentation Index
> Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Search Value

> Read the estimated monthly dollar value of a website's presence in AI search answers, as a range grounded in Google keyword economics.

AI Search Value estimates the monthly dollar value of a brand's presence in
AI search answers: what it is worth to show up, and to show up prominently,
when ChatGPT, Claude, Perplexity, and other AI systems answer questions in
your market. The number is always returned as a **range**, never a single
figure, and it is grounded in real Google keyword economics rather than an
opaque score.

<Note>
  AI Search Value is rolling out in phases. Until it is enabled for your
  organization the endpoint returns **403**, the same as any other gated
  resource. Contact your AthenaHQ representative to be added to the rollout.
</Note>

## What you get back

The response separates **channel value** (what the market is worth and how
much of it you capture) from **contribution** (how much measured impact your
content drives). These are never summed or conflated.

* **`market`** — the addressable monthly value of your tracked topics
  (`value_usd_mo`), how many of those topics are priced (`coverage_pct`),
  and your value-weighted AI share of voice (`current_sov_pct`).
* **`captured`** / **`headroom`** — value bands (`conservative`, `expected`,
  `upside`) for the value you already capture and the value still on the
  table.
* **`measured_responses`** — how many AI answers (28 days) back the read. A
  zero here means the market has not been sampled yet, so the site is still
  "gathering".
* **`is_stale_value`** — `true` when the site was priced but has since dropped
  below the refresh threshold and the value is no longer being maintained
  (see [When a value is stale](#when-a-value-is-stale)). The value is still
  returned; treat it as a last-known figure, not a current one.
* **`topics`** — per-topic detail: category, position-weighted share, mention
  rate, sample size, and each topic's own captured / headroom bands. The
  `counted_in_total` flag marks which rows roll up into the headline totals
  (duplicate canonical markets are counted once).
* **`merge_suggestions`** — pairs of near-duplicate topics worth merging.
* **`contribution.modeled_attributed`** — the slice of your captured value
  attributable to content you have shipped, plus `attributed_share` and an
  `attribution_unavailable` flag that distinguishes "no attributed content"
  from "the attribution read failed".
* **`forecast`** — when an active forecast exists, its realized share delta
  versus the do-nothing baseline.

## Quickstart

```bash theme={null}
curl "https://api.athenahq.ai/api/v1/ai-search-value?website_id=$WEBSITE_ID" \
  -H "x-api-key: $ATHENA_API_KEY"
```

```json theme={null}
{
  "assumptions_version": "2026.06",
  "computed_at": "2026-06-20T07:14:02.000Z",
  "has_computed_valuations": true,
  "is_stale_value": false,
  "market": {
    "value_usd_mo": 105100,
    "topics_priced": 18,
    "topics_total": 20,
    "coverage_pct": 90.0,
    "current_sov_pct": 12.4
  },
  "captured": { "conservative": 45000, "expected": 58500, "upside": 90000 },
  "headroom": { "conservative": 60100, "expected": 46600, "upside": 15100 },
  "measured_responses": 2843,
  "topics": [
    {
      "topic_id": "9f1c…",
      "category": "market_segment",
      "local_intent": false,
      "share_basis": "pw_sov",
      "pw_sov_pct": 11.8,
      "mix_adjusted_share_pct": 12.4,
      "mention_rate_pct": 31.2,
      "drift_pp": 0.4,
      "standard_error_pp": 1.1,
      "responses_28d": 412,
      "models_measured": 4,
      "personas_measured": 3,
      "locations_measured": 2,
      "captured": { "conservative": 3200, "expected": 4100, "upside": 6300 },
      "headroom": { "conservative": 4800, "expected": 3900, "upside": 1700 },
      "counted_in_total": true
    }
  ],
  "merge_suggestions": [],
  "contribution": {
    "modeled_attributed": {
      "conservative": 5400,
      "expected": 7000,
      "upside": 10800
    },
    "attributed_share": 0.12,
    "attribution_unavailable": false
  },
  "forecast": null
}
```

## Reading the number

* **It is a range, not a point.** Report the band, not a single dollar
  figure. The spread reflects genuine uncertainty in how AI answer volume
  converts to value.
* **`current_sov_pct` reads lower than your Share of Voice chart, on
  purpose.** The Share of Voice metric counts every brand mention equally
  across all topics, including your own branded queries where you naturally
  dominate. `current_sov_pct` is position-weighted, measured over your
  commercial (non-branded) topics only, and weighted by each topic's market
  value, so the expensive topics where you actually compete drive it. Expect
  it to read lower. That is the metric working as intended, not a
  discrepancy.
* **Channel value and contribution are separate.** `market` / `captured` /
  `headroom` size the opportunity; `contribution` measures the impact your
  shipped content drives. Do not add them together.

## When a value is not available

A few states return `200` with no priced value:

* **Gathering data** — `computed_at` is `null` or `has_computed_valuations`
  is `false`. The market has not accumulated enough AI answers for a reliable
  read yet; this usually fills in within a day or two of scanning.
* **No addressable market** — `has_computed_valuations` is `true` but
  `market.value_usd_mo` is `0`. None of your tracked topics map to priced
  search demand.

Paused websites are treated as deleted across the v1 surface and return
`403`, not a value.

## When a value is stale

`is_stale_value` is `true` when a site that was previously priced has since
dropped below the activity threshold (fewer AI answers in the trailing 28 days
than the sweep requires) and its value is older than the refresh window. The
daily sweep stops re-pricing the site, so the returned `captured` range is
frozen at its last computed figure. The endpoint still returns the value; use
`is_stale_value` and `computed_at` to decide whether to surface it as current
or as a last-known estimate.

## Rate limits

Standard per-organization API rate limits apply. Exceeding them returns `429`
with `Retry-After`. See [Rate limits](/api-reference/rate-limits).

## Authentication

Standard AthenaHQ API key authentication. See [Authentication](/api-reference/authentication).

## Endpoint reference

See [GET /api/v1/ai-search-value](/api-reference/ai-search-value/get-ai-search-value)
for the full query and response schema.