# AI Access
Source: https://docs.athenahq.ai/api-reference/ai-access
Programmatically check whether major AI answer engines can crawl a public domain.
The AI Access API lets you probe a public domain and find out whether the
major AI answer engines (ChatGPT, Claude, Perplexity, Gemini, Copilot,
Grok, DeepSeek, Rufus) can actually reach it. Useful when triaging why a
brand isn't being cited, or when filing a host or CDN ticket because a
specific bot is being blocked.
## What you get back
Every check returns three pieces:
* **`result`** — the per-model verdict. Two parallel maps under `http`
and `robots` (see [`AIAccessUIBotAccess`](#ai-access-ui-bot-access))
plus an overall `status` (`accessible`, `partial`, or `blocked`).
* **`diagnostics`** — the request fingerprint for every probe: HTTP
status code, CDN headers (`cf-ray`, `x-vercel-id`, `x-amz-cf-id`,
`x-fastly-request-id`, `x-akamai-request-id`, `server`, `via`,
`x-served-by`, `x-cache`), error codes, duration, and UTC timestamp.
Pasted into a host or CDN ticket, this is enough for support to
correlate the request on their side.
* **`log`** — a plain-text rendering of `result + diagnostics` shaped
for a host/CDN ticket. Identical to the string the AthenaHQ web app's
"Copy log" button produces.
## Quickstart
```bash theme={null}
curl -X POST https://api.athenahq.ai/api/v1/ai-access/check \
-H "x-api-key: $ATHENA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "example.com"}'
```
```json theme={null}
{
"result": {
"domain": "example.com",
"status": "partial",
"checkedAt": "2026-05-10T14:32:11.221Z",
"http": {
"chatgpt": { "conversational": true, "training": true },
"claude": { "conversational": true, "training": false },
"perplexity": { "conversational": true, "training": true },
"gemini": { "conversational": true, "training": true },
"copilot": { "conversational": true, "training": true },
"grok": { "conversational": false, "training": false },
"deepseek": { "conversational": true, "training": true },
"rufus": { "conversational": true, "training": true }
},
"robots": { "...": "same shape as http" },
"hasSitemap": true
},
"diagnostics": {
"robotsCheck": { "...": "robots.txt fetch fingerprint" },
"userAgentChecks": {
"chatgpt.GPTBot": { "...": "per-agent fingerprint" }
}
},
"log": "AI Accessibility diagnostic log\nDomain: example.com\nOverall status: partial\n..."
}
```
## Status values
| Value | Meaning |
| ------------ | --------------------------------------------------------------------- |
| `accessible` | Every model's primary user-agent received a successful HTTP response. |
| `partial` | At least one model is allowed and at least one is blocked. |
| `blocked` | No model received a successful HTTP response. |
The `status` field reflects **live HTTP behaviour**, not robots.txt. A
permissive `robots.txt` paired with a CDN that blocks `GPTBot` returns
`blocked` for ChatGPT, because robots.txt is a policy hint and not all
crawlers honour it.
## Rate limits
The endpoint is rate-limited to **30 requests per minute per
organization**. Exceeding the limit returns `429` with `Retry-After`.
## Authentication
Standard AthenaHQ API key authentication. See [Authentication](/api-reference/authentication).
## Endpoint reference
See [POST /api/v1/ai-access/check](/api-reference/ai-access/check-ai-accessibility-for-a-domain)
for the full request and response schema.
# Check AI accessibility for a domain
Source: https://docs.athenahq.ai/api-reference/ai-access/check-ai-accessibility-for-a-domain
/api-reference/openapi.json post /api/v1/ai-access/check
Probe a public domain to determine whether the major AI answer engines (ChatGPT, Claude, Perplexity, Gemini, Copilot, Grok, DeepSeek, Rufus) can crawl it. Returns the same per-model HTTP / robots.txt verdicts the AthenaHQ web app surfaces in its AI accessibility dialog, plus a plain-text diagnostic log shaped for filing host or CDN support tickets.
Rate limited to 30 requests per minute per organization.
# AI Search Value
Source: https://docs.athenahq.ai/api-reference/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.
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.
## 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.
# Get AI Search Value
Source: https://docs.athenahq.ai/api-reference/ai-search-value/get-ai-search-value
/api-reference/openapi.json get /api/v1/ai-search-value
AI Search Value for a website: topic-market value, captured value range, headroom, coverage, value-weighted AI share of voice, per-topic detail, and modeled attributed contribution.
# Query Looker Studio report data
Source: https://docs.athenahq.ai/api-reference/analytics/query-looker-studio-report-data
/api-reference/openapi.json post /api/v1/looker-studio/data
Return report rows for one website and streaming schedule. filters.schedule_id accepts default or a custom schedule UUID; omission selects Default. The retired manual token is accepted as an alias of default. Schedule selection applies to every metric and dimension and is part of the report cache key. Archived schedules retain history. Response-grain reports are bounded before response text hydration; narrow the filters if the row limit is exceeded.
# Attribute Time Series
Source: https://docs.athenahq.ai/api-reference/attributes/attribute-time-series
/api-reference/openapi.json post /api/v1/attributes/time-series
Returns the daily directional trend for one attribute, brand and competitors side by side. Requires an attribute_id. The optional top-level `positive` request field selects positive or negative observations and defaults to true. Days with no data are returned as zeros. Denominators are per-side sampled, successfully analyzed responses that mention the entity. Competitor figures aggregate all tracked competitors unless filters.competitor_ids narrows them.
# Competitor Attribute Metrics
Source: https://docs.athenahq.ai/api-reference/attributes/competitor-attribute-metrics
/api-reference/openapi.json post /api/v1/attributes/competitors
Returns directional attribute prevalence per tracked competitor. The optional top-level `positive` request field selects positive or negative observations and defaults to true. `total_responses` is per-competitor: sampled, successfully analyzed responses in the date range that mention that competitor. Returns one row per competitor per attribute; narrow with filters.competitor_ids. Competitors with no responses in the date range are omitted.
# Cumulative Attribute Metrics
Source: https://docs.athenahq.ai/api-reference/attributes/cumulative-attribute-metrics
/api-reference/openapi.json post /api/v1/attributes/cumulative
Returns directional prevalence for each direction-neutral brand-perception attribute. The optional top-level `positive` request field selects positive or negative observations and defaults to true. `total_responses` is the denominator: sampled, successfully analyzed responses in the date range that mention the brand. An analyzed response with no supported attribute claim remains in the denominator. Attributes nobody mentioned are returned with response_count 0 rather than omitted.
# List Attributes
Source: https://docs.athenahq.ai/api-reference/attributes/list-attributes
/api-reference/openapi.json get /api/v1/attributes
Returns the direction-neutral brand-perception attributes tracked for a website. Use positive to select the positive or negative observation series; it defaults to true. Use this to discover attribute ids, then POST /api/v1/attributes/cumulative for prevalence, or POST /api/v1/attributes/time-series for one attribute's trend. Attributes the customer has removed are not returned.
# Authentication
Source: https://docs.athenahq.ai/api-reference/authentication
Authenticate API requests using API keys
## API Key Authentication
All API requests must include an API key in the request headers. API keys are passed using the `x-api-key` header.
```bash theme={null}
curl https://api.athenahq.ai/api/v1/websites \
-H "x-api-key: your_api_key_here"
```
## Creating API Keys
API keys can be created and managed through your organization's dashboard.
Create, view, and manage API keys in your organization settings
## API Key Scoping
API keys belong to an organization and can be scoped to specific websites within that organization. This allows for granular access control when managing multiple websites under a single organization.
* Each API key is associated with an organization
* Organizations can contain multiple websites
* API keys can be scoped to one or more specific websites
* Scoped API keys only have access to data from their assigned websites
### Global vs. scoped keys
A **global** key covers the whole organization; a **scoped** key is limited to its assigned websites. Some organization-wide endpoints require a global key and reject a scoped one with `403 Forbidden: global API key required`:
* **Role management** — all `/api/v1/roles` endpoints
* **Organization members** — `/api/v1/organizations/members/{user_id}` (update/remove)
* **Groups** — `/api/v1/groups` management and group members
* **Organization and group invites** — `POST /api/v1/invites` with `type: "organization"` or `type: "group"` (website invites also work with a scoped key that includes the target website)
Global keys are admin-equivalent — only an organization admin or owner can create one — so these endpoints enforce the same admin-level access as the dashboard.
Only organization admins can create, edit, or delete API keys. Ensure you have the appropriate permissions before attempting to manage API keys.
# Create Location
Source: https://docs.athenahq.ai/api-reference/basics/create-location
/api-reference/openapi.json post /api/v1/locations
Creates a location for a website. `country` is case-insensitive and stored as its canonical label. Any attached `prompt_ids` must allow the location's country.
# Create Prompts
Source: https://docs.athenahq.ai/api-reference/basics/create-prompts
/api-reference/openapi.json post /api/v1/prompts
Creates one or more prompts on a website. Returns the created prompt ids. Each prompt's geography (`countries` / `primary_country`) and any attached `location_ids` are validated for compatibility before insert.
# Create Topic
Source: https://docs.athenahq.ai/api-reference/basics/create-topic
/api-reference/openapi.json post /api/v1/topics
Creates a topic on a website. Topics group prompts for aggregate reporting; pass the returned `id` as `prompts[].topic_id` when creating prompts. Get-or-create by name: if an active topic with the same name already exists, the existing topic is returned with `created: false` instead of failing, so retries and re-imports are idempotent.
# Create Website
Source: https://docs.athenahq.ai/api-reference/basics/create-website
/api-reference/openapi.json post /api/v1/websites
Creates a new website in your organization. The website will be created with onboarding step 1, ready for further configuration. **Partner integrations** may include an `external_id` to map their own identifier onto the new Athena website.
# Delete Location
Source: https://docs.athenahq.ai/api-reference/basics/delete-location
/api-reference/openapi.json delete /api/v1/locations/{location_id}
Soft-deletes a location.
# Delete Prompt
Source: https://docs.athenahq.ai/api-reference/basics/delete-prompt
/api-reference/openapi.json delete /api/v1/prompts/{prompt_id}
Deletes a prompt. Soft-deletes when the prompt already has responses, otherwise hard-deletes.
# Delete Topic
Source: https://docs.athenahq.ai/api-reference/basics/delete-topic
/api-reference/openapi.json delete /api/v1/topics/{topic_id}
Soft-deletes a topic. By default its prompts are kept: they stay active, keep their history, remain grouped under the deleted topic in the app, and can be re-categorized later. Pass `delete_prompts=true` to also soft-delete every active prompt in the topic (they stop generating responses). Reversible: creating a topic with the same name restores it and its prompt grouping.
# Delete Website
Source: https://docs.athenahq.ai/api-reference/basics/delete-website
/api-reference/openapi.json post /api/v1/websites/{website_id}/delete
Deletes a website. Removes it from your organization and stops all associated processing. Requires a global API key. Idempotent: re-calling on an already deleted website returns 200. This action is reversible — call `POST /api/v1/websites/{website_id}/restore` to reactivate a deleted website.
# Get Competitors
Source: https://docs.athenahq.ai/api-reference/basics/get-competitors
/api-reference/openapi.json get /api/v1/competitors
Returns all competitors for a specific website.
# Get Date Range
Source: https://docs.athenahq.ai/api-reference/basics/get-date-range
/api-reference/openapi.json get /api/v1/date-range
Returns the date range with available data for one streaming schedule's prompts. Omitting schedule_id selects Default, including all pre-cutover history.
# Get Group Saved Views
Source: https://docs.athenahq.ai/api-reference/basics/get-group-saved-views
/api-reference/openapi.json get /api/v1/group-saved-views
Returns all group-level saved views (filter presets) for the websites in a group. Group saved views capture filter state shared across the group rather than scoped to a single website.
# Get Locations
Source: https://docs.athenahq.ai/api-reference/basics/get-locations
/api-reference/openapi.json get /api/v1/locations
Returns all locations for a specific website.
# Get Personas
Source: https://docs.athenahq.ai/api-reference/basics/get-personas
/api-reference/openapi.json get /api/v1/personas
Returns all personas for a specific website, sorted by name, with the number of non-deleted prompts each persona is assigned to. Use the returned IDs to resolve `persona_id` values returned by other endpoints and tools to persona names and descriptions.
# Get Prompt Tags
Source: https://docs.athenahq.ai/api-reference/basics/get-prompt-tags
/api-reference/openapi.json get /api/v1/prompt-tags
Returns all prompt tags for a specific website, sorted by tag name, with the number of non-deleted prompts carrying each tag. Use the returned IDs with the `prompt_tags` filter on GET /api/v1/prompts or the `tag_ids` field on POST /api/v1/prompts.
# Get Prompts
Source: https://docs.athenahq.ai/api-reference/basics/get-prompts
/api-reference/openapi.json get /api/v1/prompts
Returns all prompts for a specific website. You can optionally filter by status (active or paused). The prompts returned include metadata such as monthly search volume and total value.
# Get Response Streaming Status
Source: https://docs.athenahq.ai/api-reference/basics/get-response-streaming-status
/api-reference/openapi.json get /api/v1/response-streaming/status
Returns the whole-run state and response-queue progress of a website's response-streaming run. By default reports the latest run; pass `workflow_id` to read a specific one. Progress measures response collection only, so `state` can remain `running` when `progress.percentage` is 100 while downstream analysis finishes. Only `state: "completed"` means the whole run, including downstream analysis, has finished. When no run has ever been started, `state` is `idle` and the config/progress fields are zeroed or null.
# Get Saved Views
Source: https://docs.athenahq.ai/api-reference/basics/get-saved-views
/api-reference/openapi.json get /api/v1/saved-views
Returns all saved views (filter presets) for a specific website. Each saved view captures a named set of filters that can be reused across the dashboard.
# Get Topics
Source: https://docs.athenahq.ai/api-reference/basics/get-topics
/api-reference/openapi.json get /api/v1/topics
Returns the active topics for a website, with the count of active prompts in each. Use it to resolve a topic name to its `id` before creating prompts or filtering.
# Get Websites
Source: https://docs.athenahq.ai/api-reference/basics/get-websites
/api-reference/openapi.json get /api/v1/websites
Returns all active websites associated with your API key. **Partner integrations** may pass `external_id` as a query parameter to find the Athena website mapped to a partner-supplied identifier.
# List prompt schedules
Source: https://docs.athenahq.ai/api-reference/basics/list-prompt-schedules
/api-reference/openapi.json get /api/v1/prompt-schedules
List Default, custom and archived streaming schedules for a website. Use each row's selection value when filtering analytics or responses. Default includes all pre-cutover history and ad hoc runs. Select one schedule at a time; archived schedules retain results. No combined All schedules view.
# Pause or Unpause Prompts
Source: https://docs.athenahq.ai/api-reference/basics/pause-or-unpause-prompts
/api-reference/openapi.json patch /api/v1/prompts/status
Pauses or unpauses multiple prompts in one transaction.
# Provision Website
Source: https://docs.athenahq.ai/api-reference/basics/provision-website
/api-reference/openapi.json post /api/v1/websites/provision
Creates a fully configured website in a single call, skipping the onboarding wizard. Optionally configures competitors, prompts, and a processing schedule. Requires a global API key. **Partner integrations** may include an `external_id` to map their own identifier onto the new Athena website.
> **Beta**: This endpoint is in beta. The request and response schemas may change.
# Query Responses
Source: https://docs.athenahq.ai/api-reference/basics/query-responses
/api-reference/openapi.json post /api/v1/responses
Returns paginated AI model responses for a website with optional filtering by date range, models, prompts, competitors, and the search queries used to produce each response.
# Restore Website
Source: https://docs.athenahq.ai/api-reference/basics/restore-website
/api-reference/openapi.json post /api/v1/websites/{website_id}/restore
Restores a previously deleted website, reactivating processing and making it available again. All historical data is preserved. Requires a global API key. Idempotent: re-calling on an already active website returns 200.
# Start Response Streaming
Source: https://docs.athenahq.ai/api-reference/basics/start-response-streaming
/api-reference/openapi.json post /api/v1/response-streaming/start
Kicks off a response-streaming run for a website: Athena queries the selected AI models for the website's prompts and ingests the responses. Omit `prompt_ids` to run every active prompt, or pass a selection (up to 1,000). Returns immediately with the `workflow_id` of the run and `status: "running"`; poll **GET /api/v1/response-streaming/status** for progress. Requires a website-admin API key.
# Update Location
Source: https://docs.athenahq.ai/api-reference/basics/update-location
/api-reference/openapi.json patch /api/v1/locations/{location_id}
Updates a location's name, country, and/or prompt associations. Only supplied fields change; omitting `prompt_ids` preserves existing associations. Returns a before/after snapshot.
# Update Prompt
Source: https://docs.athenahq.ai/api-reference/basics/update-prompt
/api-reference/openapi.json patch /api/v1/prompts/{prompt_id}
Updates a prompt's metadata (text, type, volume, topic, geography, locations). Only the supplied fields change. Returns a before/after snapshot.
A prompt's **text** (`prompt`) can only be changed while the prompt has not streamed any responses yet. Once it has responses, sending a changed `prompt` returns `400` — delete the prompt and create a new one instead. All other fields (type, volume, topic, geography, locations) remain editable at any time, and re-sending the existing text unchanged is always allowed.
# Update Topic
Source: https://docs.athenahq.ai/api-reference/basics/update-topic
/api-reference/openapi.json patch /api/v1/topics/{topic_id}
Updates a topic's name and/or description. Only the supplied fields change. Renaming to a name already used by another active topic on the website returns `400`. Renames don't affect metrics or prompt grouping — everything joins on the topic's `id`, not its name. Returns a before/after snapshot.
# Update Website
Source: https://docs.athenahq.ai/api-reference/basics/update-website
/api-reference/openapi.json patch /api/v1/websites/{website_id}
Sets, replaces, or clears the partner `external_id` mapped to a website. **Partner integrations only:** pass `external_id` as a non-empty string to set or replace the mapping, or as `null` to clear it. Requires a global API key. Works on deleted websites too, because deleting a website does not release its `external_id`. An `external_id` already mapped to another website in your organization returns `409` naming the current holder; to move an id from one website to another, clear it on the current holder first, then set it on the new one.
# Validate API Key
Source: https://docs.athenahq.ai/api-reference/basics/validate-api-key
/api-reference/openapi.json get /api/validate-api-key
Validates an API key.
# Cancel Subscription
Source: https://docs.athenahq.ai/api-reference/billing/cancel-subscription
/api-reference/openapi.json post /api/v1/subscriptions/cancel
Cancels a subscription for a specific website. The subscription will remain active until the end of the current billing period.
# Get Group Credits
Source: https://docs.athenahq.ai/api-reference/billing/get-group-credits
/api-reference/openapi.json get /api/v1/credits/group
Returns the current credit balance for a specific group. Requires a global API key.
# Get Organization Credits
Source: https://docs.athenahq.ai/api-reference/billing/get-organization-credits
/api-reference/openapi.json get /api/v1/credits/organization
Returns the current credit balance for your organization.
# Get Website Credits
Source: https://docs.athenahq.ai/api-reference/billing/get-website-credits
/api-reference/openapi.json get /api/v1/credits/website
Returns the current credit balance for a specific website.
# Get Website Subscription
Source: https://docs.athenahq.ai/api-reference/billing/get-website-subscription
/api-reference/openapi.json get /api/v1/subscriptions/website
Returns the subscription products for a specific website, including their status and billing dates.
# Changelog
Source: https://docs.athenahq.ai/api-reference/changelog
Latest updates and changes to the AthenaHQ API
This page documents all notable changes to the AthenaHQ API, including new features, improvements, and bug fixes. We recommend reviewing this changelog regularly to stay informed about updates that may affect your integration.
## September 2026
### Improved: tracked URLs include their Content Hub destination
`POST /api/v1/content/track` (MCP: `track_content_urls`) now includes `destination_name` and `content_hub_url` on each created and skipped result. The destination names the tab displaying the row, and the link opens that item with its website and tab selected. Shared-pool rows use the default view's name when available, or “Shared pool” when no view exists.
Omitting `sheet_id` still tracks URLs in the shared pool, regardless of the tab currently open in your browser. When a URL is already tracked, its result links to its existing location; retrying with another `sheet_id` does not move it. Use the created and skipped counts separately when reporting results, and include the destination and item links.
### New: custom Content Hub column values when tracking URLs
`POST /api/v1/content/track` (MCP: `track_content_urls`) accepts an optional `fields` list per URL. Each entry names one of the customer-created columns on the destination tab, as shown in Content Hub (`column`, matched case-insensitively), and its `value`: a string for text columns, an http(s) URL for link columns, a number for number columns, an ISO 8601 date string for date columns (a date-only value is stored as UTC midnight, the same instant the Content Hub date picker records for that day), a boolean for checkbox columns, and an array of up to 50 option labels for multi-select columns. Multi-select options that do not exist yet are created; existing ones match case-insensitively.
Values are written together with the created row, so a link tracked by an automation no longer needs its columns filled by hand. Skipped URLs (already tracked) keep their existing values. An unknown column name, a generated column (Ask Athena, approval, OG image), or a value that does not fit the column type returns `400` naming the field, and nothing is tracked. Requests without `fields` behave exactly as before.
### New: `POST /api/v1/metrics/shopping` returns the Shopping Insights dashboard
The in-app Shopping page reports how a brand's products show up in AI shopping answers (product carousels), but none of it was reachable over the API, which only covered share of voice, mention rate, citation rate and position. **POST /api/v1/metrics/shopping** returns that page in one call: a `summary` (shopping answers, own and competitor product appearances, appearance rate, average positions), an `offer_summary` (tracked offers and average price), `top_own_products` and `top_competitor_products`, the `competitor_breakdown` leaderboard, the `merchant_breakdown` of retailers, the `position_distribution` rank ladder, a `price_comparison` of own versus competitor offers, and a daily `trend`. It runs the same queries as the page, so the numbers match what a user sees in the app.
The body follows the other metrics endpoints (`website_id` plus `filters`), with `start_date` and `end_date` as inclusive `YYYY-MM-DD` dates in UTC. Only the filters the page applies are accepted: `schedule_id`, `models` (`chatgpt` and `ai_mode`, the two models that answer with carousels), `competitor_ids`, `prompt_tags` with `prompt_tags_operator`, and `target_identifiers`. Any other filter key returns 400 rather than being ignored. `top_products_limit` (1 to 50, default 10) sizes both product lists. Rates are percentages from 0 to 100 and positions are 1-based. The endpoint requires a paid plan, matching the page. The same read is available over MCP as `get_shopping_metrics`.
The endpoint is additive: every existing endpoint is unchanged.
### Fixed: ad hoc response runs appear under Default
Runs started without a schedule now belong to Default, including runs started through the API or MCP. Previously Manual-tagged history is moved to Default during the data migration. The schedule catalog and response provenance emit only `default` or custom schedule selections. Existing `schedule_id: "manual"` filters remain accepted as an alias of `default`.
`POST /api/v1/response-streaming/start` also accepts an optional `schedule_id` UUID. An explicit schedule supplies provenance and prompt selectors; supplied model, fan-out, persona and location options apply to that run. An ad hoc run can coexist with a scheduled run of the same schedule.
### Changed: website provisioning skips competitors on the website's own URL
`POST /api/v1/websites/provision` now ignores a competitor whose URL is the website's own URL or a path under it, since such a record would attribute the website's own citations to the competitor. The skip is logged and reflected in the returned `competitorCount`. Request and response shapes are unchanged.
### New: credit usage and charge history over MCP
`get_credit_usage` returns organization credit totals, time buckets, and charged-pool breakdowns. `get_credit_usage_events` returns paginated charges, refunds, recorded actions, and originating-website attribution. Both support explicit UTC windows so calendar-month investigations and follow-up pages use the same interval.
Signed-in callers need organization billing access. API-key callers need a global organization key; website-restricted keys cannot read these organization-wide details. Existing balance tools and REST endpoints are unchanged.
### Changed: partner recommendation access uses Autumn entitlements
`POST /api/v1/seo/recommendations` now requires the organization's `seo_recommendations` entitlement in Autumn. Access is configured through the organization's plan or customer subscription. Deployment variables and a separate website activation allowlist are no longer required. Existing API-key scope and website content permissions still apply.
The entitlement is checked before accepting a job and again before queued analysis starts. Missing access returns `403`; an unavailable admission check returns `500` without creating work. Unstarted work stays pending when access cannot be verified, releasing its worker slot so other organizations can proceed. Grant and revocation propagation follows the shared entitlement cache: 15 minutes while healthy, with previously verified snapshots usable for up to one hour during an Autumn outage. Queue limits, request and response shapes, and authorized saved-result polling are unchanged.
### New: asynchronous SEO recommendations for activated partners
`POST /api/v1/seo/recommendations` accepts a draft or public HTTPS page and returns a saved job to poll with `GET /api/v1/seo/recommendations/{job_id}?website_id=...`. Results contain source-grounded SEO and AI-search recommendations, evidence and token usage. Reusing a request ID with identical input returns the same job; changed input returns `409`.
Each website can queue up to 1,000 outstanding jobs. Analysis is limited to four workers per website and 16 across websites, with fair dispatch and recovery for interrupted starts. Submissions and polling share the existing organization API request budget (default 60 requests/minute); submissions also have a 120 requests/minute website ceiling. Honor `Retry-After` on `429` and back off when polling pending jobs. Submitting requires the organization's `seo_recommendations` entitlement in Autumn and website content administration access. Polling requires website content view access.
Both operations are included in the public `/api/v1/openapi.json` specification for client generation, with the same request and response schemas shown in this reference.
### New: select one streaming schedule in response analytics
Response-derived metrics, responses, sources, and content attribution accept
`filters.schedule_id`: `default` or a custom schedule's UUID. Omitting
it selects Default, not a combined view. Default includes all pre-cutover history,
including ad hoc runs. The retired `manual` selection is a Default alias. Archived
schedules remain queryable, and there is no All schedules selection.
`POST /api/v1/looker-studio/data` applies the same `filters.schedule_id`
selection to report metrics and dimensions, with separate cached results per
schedule. Existing requests without the field continue to select Default.
Use `GET /api/v1/prompt-schedules?website_id=...` (MCP: `get_prompt_schedules`)
to discover names and selection values for your website. Pass the returned
`selection`, not a stock schedule's UUID. `GET /api/v1/date-range` accepts the
same selection as the `schedule_id` query parameter. Response rows now include
an additive `schedule` provenance field with that selection value, including
`default` for legacy history. The generic `query_metrics` and `query_rows` tools
also accept a top-level `schedule` selection. Existing fields are unchanged.
Website-level information, such as billing and AI crawler visits,
is not filtered by streaming schedule.
If your MCP client cached tool definitions or approvals, refresh the tool list
and re-approve the updated analytics tools when prompted.
### Changed: editing a brand fact's text creates a new fact and archives the current one
`PATCH /api/v1/knowledge-base/facts/{fact_id}` (and the MCP tool `update_brand_fact`) no longer rewrites a fact's text in place. A request that changes `text` inserts a new fact carrying the new text, the fact's pillar and provenance, and its current review status, and archives the fact you addressed. The response shape is unchanged, but `fact.id` is the new fact's id; `before` still describes the fact you addressed. Requests that change only `source_url` or `confidence` keep updating the same fact in place. Archived facts are not returned by `GET /api/v1/knowledge-base/facts` and a `PATCH` against one returns `404`. Facts captured from AI responses, facts hidden as duplicates, and rejected facts can no longer have their text changed through this endpoint and return `409`.
### New: Set, replace, or clear a website's partner `external_id` with `PATCH /api/v1/websites/{website_id}`
Partner integrations can now change the identifier mapped to a website after it was created, instead of only at `POST /api/v1/websites` or `POST /api/v1/websites/provision` time:
* Pass `external_id` as a non-empty string to set or replace the mapping.
* Pass `external_id: null` to clear it.
* An id already mapped to another website in your organization returns `409` with the current holder in `existing`, so moving an id between two websites is a clear on the old one followed by a set on the new one.
The endpoint requires a global partner API key and also works on deleted websites, since deleting a website does not release its `external_id`.
### Changed: Optimize drafts can be marked published before their review runs
`POST /api/v1/content/{content_id}/publish` (and the MCP tool `publish_content`) no longer returns `409` for an Optimize draft that is waiting at stage `pending` with no Athena review in flight. An Optimize draft is created from a page that is already live on your site, so its live URL can be recorded, and citation tracking started, without running the review first. The same rule now drives the Track control in the Content Hub editor. A `pending` stage on any other content type still means the article is generating and is still rejected, as is an Optimize draft whose review is currently running. Response shapes are unchanged.
### New: Filter responses by their search queries
`POST /api/v1/responses` and the MCP tool `get_responses` now support three response-only filters for inspecting the web and map searches an AI model used:
* `filters.has_search_queries` selects responses based on whether they used at least one non-empty search query.
* `filters.search_query_text` performs a case-insensitive text match across the queries used for each response.
* `filters.search_query_text_operator` accepts `contains` (the default) or `does_not_contain`.
The filters compose with the existing date, model, prompt, competitor, location, and prompt metadata filters. Omitting them preserves the previous behavior and response shape.
### Changed: group membership writes tolerate duplicates and large batches
Some group requests that previously failed with `500` now succeed. The notable cases:
* **POST /api/v1/groups** with the same website ID listed more than once in `website_ids` now creates the group with a single membership per distinct ID and returns `201`. The response's `websiteIds` lists each ID once.
* **PATCH /api/v1/groups/** no longer returns `500` when two concurrent requests add the same website to a group; both return `200`, matching the documented behavior that websites already in the group are silently ignored.
* **PATCH** requests carrying very large `add_website_ids` or `remove_website_ids` arrays that previously failed against an internal statement limit are now processed in batches and succeed.
Every request that previously succeeded returns the same response as before; no endpoint paths, response shapes, or error strings changed.
## September 2026
### New: `GET /api/v1/content/items` lists every Content Hub item, unpublished drafts included
`POST /api/v1/content` lists content with citation and impression metrics only once its generation pipeline is finished, so a Content Hub sheet of freshly generated drafts came back empty over the REST API even though `GET /api/v1/content/sheets` listed the sheet. The MCP tool `list_content` already enumerated those rows, but it had no REST counterpart. **GET /api/v1/content/items** is that counterpart: it returns every content item a website has, published or not (in-flight drafts, briefs, snipes, optimize and slice runs, scheduled and failed items, plus tracked pages), with identity fields only (`content_id`, `title`, `type`, `stage`, `sheet_id`, `sheet_name`, `topic_name`, `url`, `prompt_ids`, `prompt_count`, timestamps) and no metrics.
Filter by `sheet_id`, `content_type`, `stage`, or `prompt_id`, and page with the usual `page_num` / `page_size`. `stage` is the raw pipeline workflow state, not a publication flag: `null` for pages with no pipeline record, `generated` for text that is ready but unpublished (manual editor items too), `done` once published or marked done. An item counts as published when its stage is `done` (or it is an external or imported page) and it has a `url`. The listing reads from the primary store and is uncached, so an item is listable the moment `POST /api/v1/content/generate` returns its `content_id`. Read a row's text with `GET /api/v1/content/{content_id}`.
The endpoint is additive: `POST /api/v1/content` and every other endpoint are unchanged.
## August 2026
### New: `mistral` model filter value
Every endpoint that accepts a `models` filter now also accepts `mistral`, covering Mistral responses. The value is additive: existing filter values, response shapes and status codes are unchanged, and omitting the filter behaves exactly as before.
**If you start runs without `selected_models`, this costs you more.** `POST /api/v1/response-streaming/start` treats an omitted `selected_models` as "every currently active model", and Mistral is now one of them. An integration that has always omitted the field will start producing Mistral responses it never asked for, billed at 5 credits each like Claude, DeepSeek and Meta AI. Pass an explicit `selected_models` map to keep the previous set.
Two things worth knowing before you filter on it. Mistral responses only exist for websites that have opted the model into their tracking, so an unfamiliar website will simply return no rows rather than an error. And Mistral is reached through Mistral's own API using its built-in web search, which accepts no country parameter, so its country attribution reflects the country stated in the prompt rather than a request originating there. The same is true of `claude`, `deepseek` and `meta_ai`.
### New: `meta_ai` model filter value
Every endpoint that accepts a `models` filter now also accepts `meta_ai`, covering Meta AI (Muse Spark) responses. The value is additive: existing filter values, response shapes and status codes are unchanged, and omitting the filter behaves exactly as before.
**If you start runs without `selected_models`, this costs you more.** `POST /api/v1/response-streaming/start` treats an omitted `selected_models` as "every currently active model", and Meta AI is now one of them. An integration that has always omitted the field will start producing Meta AI responses it never asked for, billed at 5 credits each like Claude and DeepSeek. Pass an explicit `selected_models` map to keep the previous set.
Two things worth knowing before you filter on it. Meta AI responses only exist for websites that have opted the model into their tracking, so an unfamiliar website will simply return no rows rather than an error. And Meta AI is reached through Meta's Model API rather than scraped from a country-local session, so its country attribution reflects the country stated in the prompt, not a request originating there. The same is true of `claude` and `deepseek`.
### New: `baseCountry` on website listings
**GET /api/v1/websites** (and the MCP tool `list_websites`) now includes each website's `baseCountry`: the country market the website targets, e.g. `"United States"`. Organizations that track one brand across several countries model each market as its own website, and until now nothing in the listing distinguished them, so same-name websites were impossible to tell apart without out-of-band knowledge. The value is editable in the website's brand profile (the "Base location" setting). Websites that never chose a country carry the default `"United States"`, so treat that value as unconfirmed for sites that do not look US-based.
The field is additive: no existing fields or status codes changed. The external-id lookup paths (the legacy `?external_id=` filter on this endpoint and `GET /api/v1/websites/by-external-id/{external_id}`) do not include the new field. If you generate a typed client from this spec, regenerating will pick up the new optional field.
### New: Knowledge Base pillar curation
Pillars stop being create-only and facts stop being stuck where they landed: four new endpoints close the Knowledge Base curation loop. All four require a website-admin API key and the Knowledge Base to be enabled for the organization.
* **PATCH /api/v1/knowledge-base/pillars/** updates a pillar's `name`, `description`, or `status` (at least one required; only provided fields change). Renaming returns a `409` when another pillar already uses the name. Status accepts `published` or `archived`: archiving hides the pillar from listings and stops its facts feeding content generation while keeping them stored, so it is the safe alternative to deletion. Also available as the MCP tool `update_pillar`.
* **POST /api/v1/knowledge-base/facts/move** files 1-50 facts under a published pillar (also the MCP tool `move_brand_facts`). This works for unfiled facts, which until now were readable over the API but not fixable, and re-files facts from other pillars. Review status never changes, and only approved facts under a published pillar feed content generation, so moving is what puts approved facts to work. Missing ids are reported in `not_found_ids` rather than failing the call, so retries are idempotent.
* **POST /api/v1/knowledge-base/pillars/merge** folds 1-20 source pillars into a published target: every fact on the sources re-files onto the target, page links carry over keeping the stronger signal, and the source pillars are then deleted (also the MCP tool `merge_pillars`). Unlike the other Knowledge Base writes, retries are strict: missing source ids are rejected rather than skipped, so re-read the pillars before retrying a failed merge.
* **POST /api/v1/knowledge-base/pillars/delete** permanently deletes 1-20 pillars and every fact filed under them; facts are deleted, not unfiled, and there is no undo (also the MCP tool `delete_pillars`). The response reports each deleted pillar's name and fact count, since a deleted pillar cannot be re-fetched. Like `delete_brand_facts`, OAuth MCP connections gate on the signed-in user's admin role rather than the brand-knowledge write permission.
### New: Remove group member access with `DELETE /api/v1/groups/{group_id}/members/{user_id}`
The new endpoint deprovisions a user from a group in one request. It removes the direct group membership and explicit website memberships for websites currently in that group.
* The response reports whether the group membership was removed and how many website memberships were removed. Retries and well-formed missing targets are idempotent and return zero removal counts.
* Organization membership, membership in other groups, and website membership outside the group are preserved. Access to a shared website remains when another group still grants it.
* Organization members return `409` because their organization-derived access would remain. The endpoint requires a global API key and prohibits removing the API key's own user.
### Changed: Attribute direction now selects response-level perception
The four attribute endpoints keep their existing paths and response shapes, but attributes are now direction-neutral topics. The `positive` value in a response identifies the selected positive or negative observation series instead of permanently classifying the attribute name.
* `GET /api/v1/attributes`, `POST /api/v1/attributes/cumulative`, `POST /api/v1/attributes/competitors`, and `POST /api/v1/attributes/time-series` accept an optional top-level `positive` boolean.
* Omitting `positive` defaults to `true`, preserving existing requests. Pass `positive: false` for negative observations of the same attribute ID.
* Percentages remain directional prevalence among sampled, successfully analyzed responses that mention the entity. A response with both directions can count once in each series, and an analyzed response with no attribute claim remains in the denominator.
No response fields, endpoint paths, or envelopes changed.
### Changed: request bodies now enforce explicit size bounds
Website, provisioning, and prompt write endpoints previously accepted unbounded strings and arrays. They now validate size limits and return `400` when a field exceeds them. Every limit sits well above real production usage (the largest identifier set ever stored is 166 entries; the longest prompt is under 1,000 characters), so requests that were working before continue to work unchanged. The OpenAPI spec now declares the corresponding `maxLength` / `maxItems` values.
* `POST /api/v1/websites`: `url` up to 2,048 characters.
* `POST /api/v1/websites/provision`: `url` up to 2,048 characters and `name` up to 255; `identifiers` up to 200 entries of 500 characters each (also per competitor); `competitors` up to 500 entries, each with the same name/URL bounds; `prompts` up to 10,000 entries with `text` up to 2,000 characters. 500 is also the ceiling on live competitors per website across the whole API: create requests past it return `400`.
* `POST /api/v1/prompts` and `PATCH /api/v1/prompts/{prompt_id}`: prompt text up to 2,000 characters. The existing batch bound of 1,000 prompts per create call is unchanged.
* `POST /api/v1/prompts` is now also rate limited to 60 requests per minute per website, independent of your organization-level API rate limit. Each call accepts up to 1,000 prompts, so batching keeps effective throughput at roughly 60,000 prompts per minute per website; exceeding the window returns `429`.
If you generate a typed client from this spec, regenerating will pick up the new bounds as validation annotations. No field shapes or names changed; the only status-code additions are the `400` on oversized payloads described above and the `429` on `POST /api/v1/prompts` when the per-website rate limit is exceeded.
### Clarified: Response progress can reach 100% before analysis finishes
`GET /api/v1/response-streaming/status` keeps the same response shape and state values. Its documentation now makes the readiness boundary explicit: `progress` measures response collection, while `state` covers the whole run. A run can report `state: "running"` with `progress.percentage: 100` while downstream sentiment and attribute analysis finishes. Treat only `state: "completed"` as the signal that downstream analysis is ready. No client migration is required.
### New: Update a group member's role with `PATCH /api/v1/groups/{group_id}/members/{user_id}`
Group membership was write-once over the API: `POST /api/v1/invites/bulk` could add a user to a group at a given role, and `GET /api/v1/groups/{group_id}/members` could read it back, but there was no way to change that role afterwards. The only options were removing and re-inviting the user, or editing the role in the dashboard. The new endpoint closes that gap, mirroring the existing Update Website Member Role and Update Organization Member Role endpoints:
* Accepts either the coarse `role` (`admin` / `viewer`) or a `role_id`, which can be a system role or one of your organization's custom roles from `GET /api/v1/roles`. Provide exactly one. The response echoes both the assigned `role_id` and its slug, the same `role` value the member listing returns.
* It targets explicit group members only, the `access_type: "group"` entries in the member listing. Organization members have no group-level role to change, because their access to every group comes from their organization role; targeting one returns `409`. Note that changing that organization role would take effect across every group and website in the organization, not only the group you were working on.
* Requires a global API key, and cannot modify the key's own user. Unlike the organization endpoint there is no last-admin restriction: a group's only admin can be demoted, since organization admins keep admin access to every group in the organization.
* **Roles outside `admin` and `viewer` are honored for access but are not yet rendered in the dashboard.** Assigning a group member a `role_id` such as Editor or Billing Manager grants that role's real permissions on every website in the group, but the dashboard's group member list currently displays any non-admin role as "Viewer". Until that is addressed, prefer `admin` / `viewer` at group scope when a customer administrator also needs to see the role.
### New: `GET /api/v1/content/{content_id}` returns the prompts a page targets
The response carries two new fields, `prompts` and `prompts_total`. `prompts` lists the prompts the content was written to target, the same ids `POST /api/v1/content/generate` accepts as `prompt_ids`, each with its text, topic, and status. Until now that association was write-only over the API: you could set it when generating content and never read it back.
* Ordered oldest association first and capped at 100 entries, with the untruncated size in `prompts_total`. Bulk imports can attach thousands of prompts to one page, so check `prompts_total` before assuming the list is complete. Associations past the 100th are not currently retrievable.
* `status` is `active`, `paused`, or `deleted`. Deleted prompts are included because the page was written for them and the Content Hub still displays them. `GET /api/v1/prompts` does not list deleted prompts, so an id from here may not resolve there; the text is returned inline for that reason.
* An empty array means the page has no prompt targeting recorded. That is normal for imported and externally tracked pages.
This is a different question from `POST /api/v1/content/prompts`, which lists the prompts whose AI responses **cited** the page over a date range. Targeting comes from the content record and does not depend on any citation having happened, so a page with no citations yet still returns its prompts here. Both fields are additive; existing clients are unaffected.
### New: Lighter response payloads with `include_response` and `compact_sources`
`POST /api/v1/responses` (and the MCP tool `get_responses`) accepts two optional booleans that let you drop the two fields that dominate a row's size. Both default to today's behavior, so a call that omits them returns exactly the same body as before, and `page_size` is unchanged at a maximum of 100.
* **`include_response: false`** omits the `response` field. The answer text averages around 2.2 KB per row and is usually the single heaviest thing you page through.
* **`compact_sources: true`** replaces the `sources` array of per-URL objects with `source_domains`, a deduped and alphabetically sorted list of cited root domains, averaging around 3.1 KB less per row. Hosts are lower-cased with any leading `www.` removed, and subdomains are preserved, so `shop.example.com` stays distinct from `example.com`.
Together these are the intended way to export prompt fan-out variations at volume. Pair them with `filters.variation_filter: ["variation"]` and each row still carries the base prompt, the generated variation, the model, the `mentioned` and `cited` flags for your domain, and the cited domains, at roughly a tenth of the previous size.
**If you generate a typed client from this spec, read this before upgrading.** `response` and `sources` are no longer listed as `required` on the response row, because they are genuinely absent from the payload when you opt out. Regenerating your client will make both fields optional and may surface as a compile error even if you never set either flag. The runtime shape of a call that omits both flags has not changed. Opted-out fields are absent from the row rather than empty, since an empty `response` would read as "the model answered nothing". `GET /api/v1/responses/{response_id}` is unchanged and always returns the full row.
## July 2026
### New: Track existing URLs as content with `POST /api/v1/content/track`
Publishing closed one half of the attribution loop; this closes the other. Until now the API could only attach a URL to content Athena generated (`publish`), so pages that already existed, guest posts, partner placements, or any page written outside Athena, could not be tracked at all. The new track endpoint (also the MCP tool `track_content_urls`) registers a list of up to 500 URLs as tracked Content Hub pages in one call:
* Each URL becomes an external content row whose normalized URL is the citation/metric join key, so citations and mentions in your monitored AI responses start attributing immediately. There is no publish step, no generation, and no credit cost. Third-party domains work; tracking is not limited to your own site.
* The call is idempotent per URL: a URL already present on the website (any content type) is never duplicated. The response splits `created` and `skipped`, and each skipped entry carries the existing row's `content_id` and `type`, so you can tell an already-tracked page apart from a collision with first-party generated content before chaining other calls onto the id. Tracking-param variants of the same page collapse to one row.
* Rows are created without page text, which citation tracking does not need. The page body can be pulled on demand from the Content Hub (Fetch content, on external pages without a body).
* Optional `sheet_id` files the new rows under a Content Hub tab; optional per-URL `title` overrides the slug-derived default.
### Changed: `get_tracked_content` no longer hides external and imported pages once their body is fetched
Tracked external and imported pages disappeared from `POST /api/v1/content` (and the MCP tool `get_tracked_content`) as soon as their page text was scraped, because the fill stamped an internal pipeline status that the listing's published filter excluded. The pages were still tracked, their citations still attributed, and the Content Hub still showed them; only this listing dropped them. External and imported pages are now always listed. Expect row counts to increase on websites with imported content: pages that were silently hidden reappear with their metrics intact. Generated content is unchanged and still appears only once published.
### New: Edit and delete brand facts
The Knowledge Base write surface is no longer append-only: an integration that adds facts can now also fix or remove them. Both endpoints require a website-admin API key and the Knowledge Base to be enabled for the organization.
* **PATCH /api/v1/knowledge-base/facts/** updates a fact's `text`, `source_url`, or `confidence`. Only provided fields change, and `source_url: ""` clears the stored source. Editing text re-embeds the fact for semantic search; a `409` is returned when the new text collides with a sibling fact captured from the same AI response (duplicates across other facts are left to Knowledge Base dedup). Review status never changes through this endpoint. Also available as the MCP tool `update_brand_fact` on API-key connections and org-bound OAuth sessions with brand-knowledge write permission.
* **POST /api/v1/knowledge-base/facts/delete** permanently deletes 1-50 facts in one call (a single delete is a one-element array). There is no undo. Ids with no fact on the website are reported in `not_found_ids` instead of failing the call, so retries are idempotent. Deleted facts drop out of semantic search and the owning pillar's document regenerates without them. Also available as the MCP tool `delete_brand_facts`; on OAuth sessions it requires the signed-in user to hold the admin role, matching the dashboard's delete gate.
### New: website objects carry the partner `external_id` everywhere
For partner integrations, every endpoint that returns website objects now includes the partner-supplied identifier mapped to that website, so you can match sites by your own id instead of by URL (a site's `websiteUrl` changes when its primary URL is edited in Athena):
* `GET /api/v1/groups` and `GET /api/v1/groups/{group_id}`: each website object inside `websites` carries `externalId` (`null` when no mapping exists), alongside the group-level `externalId`. The `PATCH /api/v1/groups/{group_id}` response has the same shape. These per-website fields have been returned since early July and are now documented.
* `GET /api/v1/users/{user_id}/websites`: each item now includes `external_id` (snake\_case, matching that endpoint's field naming).
The field appears only on responses to partner API keys; direct-customer responses omit it entirely. Mappings are created by passing `external_id` to `POST /api/v1/websites` or `POST /api/v1/websites/provision`; `GET /api/v1/websites` and `GET /api/v1/websites/by-external-id/{external_id}` already exposed them.
### Changed: fact listings exclude Oracle-generated facts by default (new `include_oracle` parameter)
`GET /api/v1/knowledge-base/facts` (and the MCP tool `get_brand_facts`) now excludes facts produced by Oracle's automated analysis from every listing, including the default one. Those facts are never routed to pillars and on most websites dominated the corpus (often millions of rows, inserted continuously), burying the user-curated facts the endpoint exists to surface. The response shape is unchanged; only which rows match changed. To include Oracle-generated facts, pass the new `include_oracle=true` parameter; it composes with every other filter, so `include_oracle=true&unfiled=true` reproduces the previous unfiled behavior. `GET /api/v1/knowledge-base/facts/search` is unaffected and still searches the full approved corpus, so a fact returned by search (with `pillar: null`) is not guaranteed to appear in a default listing.
### New: Mark content as published with `POST /api/v1/content/{content_id}/publish`
Until now the content workflow ended one step short over the API: you could create a piece, revise it, approve its brief, and publish it to your site yourself, but there was no way to tell Athena the piece was live. The item stayed unpublished forever, and since the URL is the join key citations and mentions attach to, citation tracking never started.
The new publish endpoint (also the MCP tool `publish_content`) closes that loop. Call it after the piece is actually live, passing the exact public URL of the page:
* The URL is stored as the item's citation/metric join key (protocol and trailing slashes are stripped; a bare `acme.com/blog/post` is fine). Query strings and fragments are excluded from the join key for non-YouTube URLs, so pasting a UTM-tagged URL does not break attribution; the display URL keeps them. YouTube URLs keep their params, since the video id lives there.
* The publish time is stamped and the pipeline stage moves to `done`, so the item now counts as published in Content Hub and in `get_tracked_content`.
* A first publish requires a finished article (stage `generated`). Briefs, still-generating or failed pieces, and items with a scheduled CMS publish return `409` with the reason, so incomplete content cannot be marked live.
* Calling it again on an already-published item updates the tracked URL only, keeping the original publish time. The response's `already_published` flag tells you which of the two happened. External and imported pages are live by definition, so a call on them is always a URL-only update.
This is the only way to set a content URL over the API: the rename endpoint (`PATCH /api/v1/content/{content_id}`) remains deliberately title-only.
### New: `list_content` MCP tool for enumerating unpublished drafts
`get_tracked_content` lists content with citation and impression metrics only once its generation pipeline is finished, so a sheet full of in-progress drafts listed as empty: there was no way to enumerate a sheet's unpublished pipeline items without already holding their `content_id`s. Rather than blur that tool's "tracked" semantics with a flag, there is now a dedicated MCP tool, `list_content`, that enumerates every content item a website has, published or not: in-flight drafts, briefs, snipes, optimize and slice runs, scheduled and failed items, plus tracked pages.
It returns identity fields only (`content_id`, `title`, `type`, `stage`, `sheet_id`, `sheet_name`, `topic_name`, `url`, timestamps), no metrics, and supports `sheet_id`, `content_type`, and `stage` filters with the usual `page_num` / `page_size` pagination. Passing the `sheet_id` of a view-type tab (see `sheet_type` on `get_content_hub_sheets`) lists the shared main pool that views overlay, without the view's saved filters. `stage` is the raw pipeline workflow state, not a publication flag: `null` for pages with no pipeline record (most external and imported tracked pages), otherwise the stage the pipeline is at (`pending_brief`, `generated`, `done`, `scheduled`, `failed`, and so on). An item counts as published in Content Hub terms when its stage is `done` (or it is an external or imported page) and it has a `url`; manual editor items carry `generated`. The listing reads from the primary store and is uncached, so an item is listable the moment `create_content` returns its `content_id`, before any brief approval, generation, or publish. `get_tracked_content` and `POST /api/v1/content` are unchanged.
### New: Deterministic draft edits with `POST /api/v1/content/{content_id}/edit`
Until now the only way to change an article body over the API was `revise`, which hands your instruction to an AI model and saves whatever it writes. The new edit endpoint (also the MCP tool `edit_content`) is the deterministic counterpart: you send exact find-and-replace pairs and your replacement text lands verbatim, no model involved.
* Each edit's `find` text must match the current body exactly once. Zero matches (stale snapshot, wrong anchor) or multiple matches (ambiguous anchor) fail the whole call with `400` and nothing is saved; extend the `find` text until it is unique.
* Up to 20 edits per call, applied in order, with later edits seeing earlier results. The batch is recorded as one new version, restorable like any other.
* Optional `expected_version_number` (from the draft endpoint) makes the call fail with `409` when a new version was recorded after your read (a revision, edit, or restore). An app autosave changes the body without recording a version; that drift is caught by the anchors themselves, since a moved or vanished `find` text fails the call.
The `revise` and `brief/revise` descriptions now also state explicitly that their rewrites are AI-generated text, not your literal wording, so it is clear which of the two tools to reach for.
### Fixed: Narrow revise instructions could replace the whole article with the edited passage
`POST /api/v1/content/{content_id}/revise` (and the MCP tool `revise_content`) could destroy a draft when given a narrowly-scoped instruction such as "change only this sentence, alter nothing else": the model sometimes returned only the edited passage, and that fragment was saved as the new article. The endpoint now guards against this. A revision that comes back dramatically shorter than the current draft, without an instruction that calls for shortening, is retried with an explicit whole-document directive; if it still comes back as a fragment, the call fails with a `500` and the draft is left unchanged. Nothing is ever silently truncated, and earlier text remains restorable via the version endpoints.
The response now also includes `body_word_count` and `previous_body_word_count` (both integers), so callers can verify the size change themselves. The returned `body` is always the complete replacement article. Same additions apply to `POST /api/v1/content/{content_id}/brief/revise`'s underlying guard, though its response shape is unchanged.
### Changed: `filters.competitor_ids` on content endpoints is now strict
`POST /api/v1/content` and `POST /api/v1/content/prompts` accept `filters.competitor_ids`. Previously the filter also kept responses that mention no competitors at all, so filtered citation rates and response counts included competitor-free responses. The filter is now strict: a response counts only when it mentions at least one of the given competitor ids, matching how the same filter behaves on the responses and sources endpoints. Requests that omit the filter are unchanged. Both endpoints are also significantly faster.
### New: `fact_review` on content generation
`POST /api/v1/content/generate` (and the MCP tool `create_content`) now accepts an optional `fact_review` object for draft mode: `{ topic_ids, kept_claim_ids, excluded_claim_ids }`. When present, generation uses exactly the reviewed knowledge-base pillars and kept facts instead of computing a selection of its own, so what a reviewer approved is what the draft is written from. `pinned_claim_ids` no longer influences selection when a review is present (the review already reflects any pins); it is still recorded for display. Requires the knowledge base to be enabled: sending `fact_review` with `kb_mode: "none"` or a non-draft `mode` returns a validation error.
Content generation is also now strictly pillar-scoped: knowledge-base claims without a pillar are never used, whether selected automatically, pinned via `pinned_claim_ids`, or kept via `fact_review`. Ids that resolve to an unfiled claim are dropped and reported in the run's selection outcome. File a fact under a pillar to make it available to generation.
### New: `409` when deleting a website that holds your subscription
`POST /api/v1/websites/{website_id}/delete` now returns `409 Conflict` instead of silently succeeding when the target website carries your organization's subscription.
Plans attach per organization, but subscriptions bought before that change sit on one specific website. Deleting that website used to soft-delete the record while leaving the subscription and its credit balance stranded on it: billing continued, and every remaining website reported zero credits. The endpoint now refuses the delete and returns the reason, so the plan can be cancelled or moved first.
Deletes of websites that do not hold a subscription are unaffected, as are all `restore` calls. If you delete websites programmatically, handle `409` as "cancel or move billing first", not as a retryable error.
### Fixed: `cited` was always `false` on responses
`POST /api/v1/responses` and `GET /api/v1/responses/{response_id}` returned `cited: false` on every response, even when the response's own `sources[]` contained your website's domain. The flag was read from a stored value that the ingestion pipeline never populated. It is now derived from the response's sources at read time: `cited` is `true` when any source resolves to your website's root domain (protocol, `www.`, and letter-case insensitive). The fix applies to all historical responses, not just new ones, and the response shape is unchanged. Aggregate citation metrics (such as the sources endpoints) were computed independently and were always correct.
### Fixed: Content detail returned null text for brief-stage drafts
`GET /api/v1/content/{content_id}` (and the MCP tool `get_content_detail`) returned `status`, `brief`, `body`, and every other generation field as `null` for any draft whose article had not been written yet, even though the brief existed and was visible in the dashboard. The bug hid exactly the pieces most worth reading over the API: drafts parked at `generated_brief` awaiting brief approval. These now return their brief and status correctly. A genuinely unknown or inaccessible `content_id` continues to return `404`; `null` fields now only mean the field is actually empty.
### New: `stage` on the content status endpoint
`GET /api/v1/content/{content_id}/status` (and the MCP tool `get_content_status`) now returns a `stage` field alongside the normalized `status`. `status` is unchanged (`running | succeeded | failed`), but it cannot distinguish "actively generating" from "brief ready, waiting for approval": both report `running`, and a draft created with `auto_approve: false` waits at the brief stage indefinitely. `stage` exposes the raw pipeline stage (`scheduled`, `pending`, `pending_brief`, `generated_brief`, `pending_article`, `generated`, `done`, `failed`, or `null` when generation has not started), so a poller seeing `stage: "generated_brief"` knows to call `POST /api/v1/content/{content_id}/brief/approve` rather than keep waiting.
### New: Review and iterate on briefs and drafts
Content generation used to be one-shot: you could start a piece and poll it, but changing what came back meant generating a new one and paying for it again. You can now read a draft, revise it with a plain-language instruction, and step back through its history — for the brief as well as the article.
Every revision is recorded as a version, so nothing is overwritten irrecoverably. The brief and the article share one timeline: `get_content_versions` tells the whole story of a piece, from the brief it was planned with to the article it became.
**The brief phase.** Pass `auto_approve: false` to `POST /api/v1/content/generate` and the piece stops at `generated_brief` instead of writing the article. That gate already existed; these endpoints make it usable end to end.
* **GET /api/v1/content//draft** — The current text: article body, brief, meta description, status, and the latest version number. A narrow read for when you only want the text — `GET /api/v1/content/{content_id}` remains the full record. Also available as the MCP tool `get_content_draft`.
* **POST /api/v1/content//brief/revise** — Rewrites the brief from an instruction ("add a section on pricing objections"). Also `revise_brief`.
* **POST /api/v1/content//brief/approve** — Approves the brief and starts the article from it, as the brief currently stands. Consumes content credits. Also `approve_brief`.
**The article phase.**
* **POST /api/v1/content//revise** — Rewrites the article from an instruction. Iterate by calling it again; each call starts from the current text, so there is no version to pass. Also `revise_content`.
* **POST /api/v1/content//versions** — The version history, newest first, with each entry's label, how it was produced, and who made it. POST rather than GET because it takes pagination in the body. Also `get_content_versions`.
* **GET /api/v1/content//versions/** — The full text of one version. Fetch two and diff them yourself to see what a pass changed. Also `get_content_version`.
* **POST /api/v1/content//versions//restore** — Brings an earlier version's text back as the current draft. Also `restore_content_version`.
Three things worth knowing:
* **Restoring never deletes.** The restored text is appended as a new version on top of the history, so the passes in between stay readable and restorable, and the history records that a restore happened.
* **Revising is not regenerating.** A revision edits the text you already have; it does not re-run research or scraping. Revising a brief after the article exists corrects the brief for a future regeneration — it does not rewrite the article.
* **A piece being generated cannot be revised.** While a generation is in flight these endpoints return `409`; poll `GET /api/v1/content/{content_id}/status` until it reports `succeeded`.
### New: Create saved views over MCP
You can now create saved views (dashboard filter presets) through the MCP server. A saved view captures a named set of filters and appears in the dashboard filter bar for every member of the website.
* **`create_saved_view`** (MCP tool) — Creates a saved view from a `name`, an optional `icon`, and a `filters` object. The `filters` payload is stored verbatim (keys are not case-mapped) and is capped at 64KB. There is deliberately no REST equivalent: creating filter presets is an assistant workflow, not a partner-integration one.
Views created on an API-key MCP connection have no owning user: `user_id` is `null` in `GET /api/v1/saved-views` responses (previously it was always a user ID) and the dashboard shows them as created via API. Such views can only be edited or deleted by website admins, in the dashboard. Views created over a sign-in MCP connection are attributed to the connected user, same as views created in the dashboard.
### New: AthenaHQ plugin for ChatGPT
AthenaHQ is now available as an official plugin in ChatGPT, so connecting no longer requires a custom MCP connector or developer mode. [Install the plugin](https://chatgpt.com/plugins/plugin_asdk_app_6a4da6c4bcfc81919397faceada2af69), sign in with your AthenaHQ account, and mention `@AthenaHQ` in any conversation to ask about share of voice, citations, sources, tracked prompts, and more. Plugin connections are read-only, same as other sign-in connections. See [MCP Server](/api-reference/mcp) for details.
### New: Attributes (brand-perception keywords)
You can now retrieve the brand-perception attributes Athena extracts from AI model responses — keywords like "Affordable" or "Slow Support" — and how often each is mentioned. This is the qualitative half of the picture: the existing metrics tell you how often and where your brand appears, attributes tell you what models actually say about it.
* **GET /api/v1/attributes** — Lists the attributes tracked for a website (`{ "id", "name", "positive" }`). Use it to discover attribute IDs. Also available as the MCP tool `get_attributes`.
* **POST /api/v1/attributes/cumulative** — Per attribute, how many responses mentioned it across the date range, and the percentage. Attributes nobody mentioned are returned with `response_count` 0 rather than omitted. Also available as the MCP tool `get_attribute_metrics`.
* **POST /api/v1/attributes/competitors** — The same breakdown per tracked competitor, so you can compare how your brand is described against theirs. Each competitor has its own denominator; competitors with no responses in the date range are omitted. Also available as the MCP tool `get_competitor_attribute_metrics`.
* **POST /api/v1/attributes/time-series** — The daily trend for one attribute, brand and competitors side by side. Requires an `attribute_id` from the list endpoint. Days with no data are returned as zeros, so the series is gap-free.
Two things worth knowing when reading this data:
* `positive` describes the selected directional observation series. Attribute names are neutral and the same attribute ID can have both positive and negative observations.
* `percentage` is the share of **analyzed** responses, not of all responses. Athena samples responses for attribute extraction, and un-analyzed ones are excluded from the denominator.
### New: Knowledge Base writes
You can now feed a website's brand Knowledge Base through the API. Write inputs are declarative — fact text, optional source URL, optional pillar — with no status or approval field: every fact runs the full ingestion pipeline (deduplication, approval gates, pillar routing) and the response reports what the pipeline decided, per fact. The `outcome` values (`approved`, `pending`, `duplicate`) form an extensible enum: new values may be added as the pipeline evolves, so treat unknown values as non-terminal. Both endpoints require a website-admin API key and the Knowledge Base to be enabled for the organization.
* **POST /api/v1/knowledge-base/facts** — Adds 1-50 brand facts in one call and returns one outcome per fact (`{ "index", "outcome", "fact_id", "pillar_id" }`), which doubles as the ingest report. Facts pinned to a `pillar_id` land exactly there; the rest are routed automatically and may land unfiled. Also available as the MCP tool `add_brand_facts` on API-key connections and org-bound OAuth sessions with brand-knowledge write permission.
* **POST /api/v1/knowledge-base/pillars** — Creates a pillar from a `name` and optional `description`. Get-or-create semantics: an existing name returns the pillar with `created: false`, keeping retries idempotent. Also available as the MCP tool `create_pillar`.
### New: Knowledge Base reads
You can now read a website's brand Knowledge Base through the API: the approved brand facts (statements like "Our Pro plan starts at \$99/month", each backed by a source) and the pillars that organize them. All four endpoints require the Knowledge Base to be enabled for the organization; when it isn't, they return a `403` with `"Knowledge Base is not enabled for this organization"`.
* **GET /api/v1/knowledge-base/facts/search** — Semantic search over a website's approved brand facts. Combines vector similarity with full-text search, so it also reaches facts not filed under any pillar. Also available as the MCP tool `search_brand_facts`.
* **GET /api/v1/knowledge-base/facts** — Lists brand facts, newest first, with offset paging and filters: pillar, review status (defaults to approved), source type, and `unfiled=true` for facts not under any published pillar. Also available as the MCP tool `get_brand_facts`.
* **GET /api/v1/knowledge-base/pillars** — Lists the website's pillars (excluding archived ones) with approved-fact counts, whether a synthesized document exists, and when each was last researched. Also available as the MCP tool `get_pillars`.
* **GET /api/v1/knowledge-base/pillars//document** — Fetches a pillar's synthesized markdown document; returns `document: null` when the pillar exists but has no document yet. Also available as the MCP tool `get_pillar_document`.
### New: Persona discovery
You can now discover a website's personas through the API. Persona IDs previously appeared as bare `persona_id` values in other responses with no way to resolve them to names.
* New **GET /api/v1/personas** endpoint lists a website's personas with per-persona assigned-prompt counts (`{ "id", "name", "description", "prompt_count" }`). Also available as the MCP tool `get_personas`.
### New: Content generation endpoints and MCP actions
You can now create and manage content in Athena programmatically, closing the loop from insight to action: spot a gap, then draft content for it without leaving the API or your AI assistant.
* **POST /api/v1/content/generate** — Starts the content pipeline in one of four modes: `draft` (write new content from `prompt_ids`), `snipe` (outrank a competitor URL), `optimize` (improve an existing URL for AI search), or `slice` (split one URL into several articles). Returns durable `content_ids` you can poll. Consumes content credits. Requires a website-admin API key. Also available as the MCP tool `create_content` on API-key connections.
* **GET /api/v1/content//status** — Returns the normalized generation status (`running`, `succeeded`, or `failed`) for one content item. Poll it per `content_id` returned by the generate endpoint. Also available as the MCP tool `get_content_status`.
* **PATCH /api/v1/content/** — Renames a content item's title. The URL is the item's stable identity and cannot be changed. Requires a website-admin API key. Also available as the MCP tool `rename_content` on API-key connections (initially shipped as `update_content`; renamed because the tool only renames the title).
* **DELETE /api/v1/content/** — Permanently deletes a content item (no undo). Requires a website-admin API key. Also available as the MCP tool `delete_content` on API-key connections.
Listing and reading content were already available (**POST /api/v1/content**, **GET /api/v1/content/**, and the MCP tools `get_tracked_content` / `get_content_detail`).
### New: Topic management endpoints
You can now manage topics via the API, completing the programmatic prompt management round trip: create a topic, get back its `id`, and pass it as `prompts[].topic_id` when creating prompts.
* **GET /api/v1/topics** — Lists a website's active topics with the count of active prompts in each. Use it to resolve a topic name to its `id`. Also available as the MCP tool `get_topics`.
* **POST /api/v1/topics** — Creates a topic on a website from a `name` and optional `description`. Get-or-create semantics: if an active topic with the same name already exists, the existing topic is returned with `created: false` instead of failing, so retries and re-imports are idempotent. Requires a website-admin API key. Also available as the MCP tool `create_topic` on API-key connections.
* **PATCH /api/v1/topics/** — Updates a topic's `name` and/or `description`. Renames don't affect metrics or prompt grouping (everything joins on the topic's `id`). Requires a website-admin API key. Also available as the MCP tool `update_topic` on API-key connections.
* **DELETE /api/v1/topics/** — Soft-deletes a topic. By default its prompts are kept (they stay active and can be re-categorized); pass `delete_prompts=true` to also soft-delete every active prompt in the topic. Reversible: creating a topic with the same name restores it. Requires a website-admin API key. Also available as the MCP tool `delete_topic` on API-key connections.
### New: Prompt tag discovery
You can now discover a website's prompt tags through the API. Previously the `prompt_tags` filter on **GET /api/v1/prompts** and the `tag_ids` field on **POST /api/v1/prompts** required tag UUIDs that the API did not expose anywhere.
* **GET /api/v1/prompts** now includes a `tags` array on each prompt (`[{ "id", "name" }]`, sorted by name, empty when untagged). Existing fields are unchanged.
* New **GET /api/v1/prompt-tags** endpoint lists a website's tags with per-tag prompt counts (`{ "id", "name", "prompt_count" }`), so a tag picker can populate without fetching all prompts. Also available as the MCP tool `get_prompt_tags`.
### Changed: Provisioning responses report billing entity creation
Website and group creation responses now include `billingEntityCreated`: whether the billing entity that backs credits was provisioned. When `false`, the website or group was created but cannot hold credits yet: setting credits fails with a `400` until it is repaired (for groups, call **PATCH /api/v1/groups/** with `billing_enabled: true`; for websites, contact AthenaHQ support). Previously a failed billing setup was silent and only surfaced when setting credits later.
Affects **POST /api/v1/websites** and **POST /api/v1/websites/provision** (always present), and **POST /api/v1/groups** (present when `billing_enabled` is requested).
### New: Write tools on the MCP server
The MCP server is no longer read-only. Connections authenticated with an **API key** now get write tools mirroring the corresponding REST endpoints 1:1: same field names (snake\_case), same validation, same audit logging. OAuth-connected MCP sessions remain read-only and do not see these tools.
* `create_prompts`, `update_prompt`, `set_prompts_status`, `delete_prompt`: the prompt management operations (POST/PATCH/DELETE `/api/v1/prompts...`).
* `create_location`, `update_location`, `delete_location`: the location management operations (POST/PATCH/DELETE `/api/v1/locations...`).
* `start_response_streaming`: starts a response-streaming run (POST `/api/v1/response-streaming/start`). Status polling was already available as `get_response_streaming_status`.
Read endpoints that previously had no MCP tool are now exposed too, completing 1:1 coverage of the procedure-backed API surface: `get_user_by_email` ([POST /api/v1/users/by-email](/api-reference/team-management/look-up-user-by-email), global API key required), `get_response_detail` (GET /api/v1/responses/), `get_groups` and `get_group_detail` (GET /api/v1/groups..., global API key required), `check_ai_access` (POST /api/v1/ai-access/check), and `get_position_distribution` (POST /api/v1/metrics/position/distribution).
### New: Role management endpoints
You can now manage roles via the API — list the built-in system roles (Admin, Editor, Viewer, Billing) and your organization's custom roles, and create, update, or delete custom roles with per-category permission matrices. Creating custom roles is available on the Enterprise plan. All role endpoints require a **global API key**.
* **GET /api/v1/roles** — List all roles with their resolved permission matrices.
* **POST /api/v1/roles** — Create a custom role (Enterprise plan).
* **GET /api/v1/roles/** — Fetch a single role.
* **PATCH /api/v1/roles/** — Update a custom role's permissions.
* **DELETE /api/v1/roles/** — Delete a custom role (fails if still assigned).
### Changed: Assign any role with `role_id`
Invites and organization member role updates now accept a `role_id` — a system role or one of your organization's custom roles — in addition to the coarse `role` (`admin`/`viewer`), which keeps working unchanged. `role` and `role_id` are mutually exclusive.
Affects **POST /api/v1/invites**, **POST /api/v1/invites/bulk**, and **PATCH /api/v1/organizations/members/**.
### Changed: Mention rate and share of voice entries include relative mention rate
The mention rate and share of voice endpoints now return a `relative_mention_rate` field for every brand/competitor entry: the entity's mentions as a percentage (0-100) of responses that mention at least one tracked brand. This is the same "Relative" rate shown in the dashboard's mention rate card. The existing `mention_rate` field stays absolute (share of all responses), and all existing fields are unchanged.
Affects **[POST /api/v1/metrics/mention-rate/cumulative](/api-reference/metrics/cumulative-mention-rate)**, **[POST /api/v1/metrics/mention-rate/time-series](/api-reference/metrics/mention-rate-over-time)**, **[POST /api/v1/metrics/share-of-voice/cumulative](/api-reference/metrics/cumulative-share-of-voice)**, and **[POST /api/v1/metrics/share-of-voice/time-series](/api-reference/metrics/share-of-voice-over-time)** (per entry, per day on the time-series variants). Also returned by the MCP tools `get_mention_rate_cumulative`, `get_mention_rate_time_series`, `get_share_of_voice_cumulative`, and `get_share_of_voice_time_series`.
### New: Trigger response streaming via the API
You can now start a response-streaming run (query the AI models for a website's prompts and ingest the answers) and poll its progress via the API — the same run the dashboard's stream dialog kicks off.
* **[POST /api/v1/response-streaming/start](/api-reference/basics/start-response-streaming)** — Start a run for all active prompts or a selection (up to 1,000), with optional model selection, prompt variations, personas, and locations. Returns the `workflow_id` and `status: "running"`. Requires a website-admin API key.
* **[GET /api/v1/response-streaming/status](/api-reference/basics/get-response-streaming-status)** — Read the latest run's state (`idle` / `running` / `completed` / `failed` / `cancelled`) and queue progress (`pending`, `processing`, `completed`, `failed`, `total`, `percentage`). Pass `workflow_id` to read a specific run.
### New: Look up a user by email
You can now resolve a user's `user_id` from their email address, scoped to your organization. The email is sent in the request body so it never lands in logs.
* **[POST /api/v1/users/by-email](/api-reference/team-management/look-up-user-by-email)** — Returns the user's `user_id`, name, and `access_type` (`organization` or `website`) when the email belongs to your organization; `404` otherwise (indistinguishable from an unknown email, so it cannot be used to enumerate accounts). Requires a global API key.
### New: Remove a user from websites
You can now batch-remove a user's explicit website memberships in one call — the companion to listing a user's websites.
* **[DELETE /api/v1/users//websites](/api-reference/team-management/remove-user-from-websites)** — Remove the user from the websites named in the `website_ids` query parameter (comma-separated, up to 100). Idempotent: websites where the user has no explicit membership return status `not_a_member` instead of failing. Requires a global API key.
### Changed: Filter prompts by tag
[GET /api/v1/prompts](/api-reference/basics/get-prompts) now accepts an optional `prompt_tags` filter (one or more prompt tag IDs) plus a `prompt_tags_operator` (`is_any_of` (default) or `has_all_of`) to control how multiple tags combine. All tag IDs must belong to the same website as `website_id`. Also available on the MCP `get_prompts` tool.
### New: Read a single content item
You can now fetch the full detail of one tracked content item — including its actual text: the content brief (`brief`) and the article/page body (`body`, which holds generated drafts, optimize rewrites, snipe articles, authored text, and scraped tracked-page bodies). The response also carries `status`, so you can poll it while generation runs — `generated_brief` means the brief is ready while the article is still being written.
* **[GET /api/v1/content/](/api-reference/content/get-content-detail)** — Full detail for one content item, including `brief`, `body`, cited source URLs, links, and `status`. Also available as the MCP tool `get_content_detail`.
### Changed: `manual` content type filter
The tracked-content endpoint's `content_type` filter now accepts **`manual`** — user-authored content created directly in the editor (the "Blank Editor" flow), as opposed to Athena-generated or imported content. Existing values are unchanged.
Affects **POST /api/v1/content** (`content_type` filter).
## June 2026
### Changed: Member `role` is now the role's slug
Member-list endpoints now return each member's `role` as its **slug** — the role's normalized name (lowercase, no spaces) — rather than only `admin`/`viewer`. Built-in roles are `admin`, `viewer`, `editor`, and `billing`; a custom role uses its own id (e.g. `contentmanager`). `admin` and `viewer` are unchanged, so integrations that check for them keep working; members that previously reported `viewer` because of a non-admin role (Editor, Billing, custom) now surface their real role.
Affects **GET /api/v1/organizations/members**, **GET /api/v1/websites//members**, **GET /api/v1/groups//members**, and **GET /api/v1/users//websites**.
### New: Manage prompts via the API
Prompts are no longer read-only. You can now create, update, pause/unpause, and delete prompts via the API — the same operations the dashboard performs, with the same geography and ownership validation.
* **[POST /api/v1/prompts](/api-reference/basics/create-prompts)** — Create one or more prompts (up to 1,000 per request), with optional topic, geography, persona/location/tag associations, and paused state.
* **[PATCH /api/v1/prompts/](/api-reference/basics/update-prompt)** — Update a prompt's text, type, volume, topic, geography, or locations. Returns a before/after snapshot.
* **[PATCH /api/v1/prompts/status](/api-reference/basics/pause-or-unpause-prompts)** — Pause or unpause multiple prompts in one transaction.
* **[DELETE /api/v1/prompts/](/api-reference/basics/delete-prompt)** — Delete a prompt (soft when it has responses, hard otherwise).
### New: Manage locations via the API
You can now create, update, and delete locations via the API. `country` is accepted case-insensitively and stored as its canonical label, and any attached prompts are validated against the location's country.
* **[POST /api/v1/locations](/api-reference/basics/create-location)** — Create a location with a country and optional prompt associations.
* **[PATCH /api/v1/locations/](/api-reference/basics/update-location)** — Update a location's name, country, and/or prompt associations. Returns a before/after snapshot.
* **[DELETE /api/v1/locations/](/api-reference/basics/delete-location)** — Soft-delete a location.
## May 2026
### New: MCP server for Claude, ChatGPT, and other AI assistants
You can now connect AthenaHQ to Claude, ChatGPT, and other AI assistants over the [Model Context Protocol](/api-reference/mcp). The read-only server exposes your metrics, prompts, responses, content, sources, competitors, and pitches as tools, so an assistant can answer questions about your AI search visibility in plain language.
* Connect **Claude.ai** or **ChatGPT** by adding a custom connector and signing in with your AthenaHQ account (no API key).
* Connect other MCP clients (including **Claude Code**) with an API key via the `x-api-key` header.
Server URL: `https://api.athenahq.ai/api/mcp`.
### New: Sources endpoints
You can now pull cited-sources data via the API (and via MCP — these are the `get_sources` / `get_source_pages` tools). Each row is classified as `owned` / `competitor` / `partner` / `third_party` based on your tracked competitors, configured partners (affiliates), and per-website source-type overrides.
* **[POST /api/v1/sources](/api-reference/sources/list-sources-by-root-domain)** — Domain-grouped sources for a website. Top cited root domains with citation, mention, brand-mention, and impression metrics for the date range. Supports filters, search, sort, and pagination.
* **[POST /api/v1/source-pages](/api-reference/sources/list-source-pages-per-url)** — Per-URL companion to the above. Returns one row per cited `normalized_url` with the same metrics plus a per-URL daily citation sparkline (`daily_mentions`).
### New: Pitch Workspace endpoints
You can now read pitch workspace reports via the API. Pitches are organization-level resources (not scoped to a single website), so these endpoints require a **global API key** — website-scoped keys are rejected with `403 Forbidden`.
* **[GET /api/v1/pitches](/api-reference/pitch-workspace/list-pitches)** — List non-deleted pitches in the calling organization, with company metadata and run status.
* **[GET /api/v1/pitches/](/api-reference/pitch-workspace/get-pitch-report)** — Fetch a single pitch report: tracked competitors with mention/sentiment stats, generated prompts, positive/negative attributes for both the target and its competitors, top citing domains, and aggregate metrics (`total_responses`, `brand_mentions`, `sentiment_score`, `response_rate`).
### New: Content Hub endpoints
You can now read Content Hub data — tracked URLs, citation/impression metrics, and per-URL prompt breakdowns — via the API. These power GEO reporting that includes both 1st-party (Athena-created) and 3rd-party (link-building placements, Reddit, partner posts) content in one place.
* **[GET /api/v1/content/sheets](/api-reference/content/list-content-hub-sheets)** — List the Content Hub tabs configured for a website. Call this first to discover the `sheet_id`s you can filter by.
* **[POST /api/v1/content](/api-reference/content/list-tracked-content)** — Paginated tracked content with citations, citation %, estimated impressions, and total responses for the date range. Filter by `sheet_id`, `content_type`, `mentioned`, and the standard filter knobs.
* **[POST /api/v1/content/prompts](/api-reference/content/per-content-prompt-citation-breakdown)** — For a single content item, the list of prompts whose AI responses cite it — with per-prompt citation counts and percentages. Works for both topic-attached and 3rd-party content without a topic assignment.
### New: Saved views endpoint
You can now fetch saved views (filter presets) for a website via the API. Saved views capture a named set of dashboard filters that can be reused across the product.
* **[GET /api/v1/saved-views](/api-reference/basics/get-saved-views)** — List saved views for a website. Returns each view's filters, icon, and creator metadata.
### New: Group saved views endpoint
You can now fetch group-level saved views via the API. Group saved views capture filter state shared across the websites in a group rather than scoped to a single website.
* **[GET /api/v1/group-saved-views](/api-reference/basics/get-group-saved-views)** — List saved views for a group. Pass `group_id`; authorization runs against the group's org.
## April 2026
### Updated: Multi-country support on prompts
[GET /api/v1/prompts](/api-reference/basics/get-prompts) now returns a `countries` array on each prompt, listing every country targeted by that prompt along with an `is_primary` flag. The primary country is listed first; remaining countries follow in alphabetical order.
* `countries: [{ country: string, is_primary: boolean }]` — New field. Empty array when the prompt has no countries assigned.
* `country: string` — Deprecated, but still populated for backward compatibility. Returns the primary country (or the alphabetically first, or `"United States"` as a final fallback). New integrations should read `countries` instead.
### New: Delete and restore websites
You can now delete and restore websites via the API. Deleting removes a website from your organization and stops all associated processing; restoring brings it back exactly as it was, with all historical data preserved. This is the recommended flow for partner integrations that need to handle customer churn and reactivation.
* `POST /api/v1/websites/{website_id}/delete` — Deletes a website.
* `POST /api/v1/websites/{website_id}/restore` — Reactivates a deleted website.
Both endpoints require a global API key. Both are idempotent: re-calling them on a website that is already in the target state returns 200.
### Updated: Invite users to groups
[POST /api/v1/invites](/api-reference/team-management/create-invite) now accepts `type: "group"` with a `group_id`, granting the user access to every website in the group. [POST /api/v1/invites/bulk](/api-reference/team-management/bulk-invite-to-websites-or-groups) accepts a new `group_ids` array (mutually exclusive with `website_ids`, max 50) for inviting a user to multiple groups in one request.
Both branches behave consistently with the existing org/website invites: `invite_method: "direct"` adds the user immediately (creating a new user account automatically if the email has none) without sending any email, while `invite_method: "email"` creates a pending invite and sends an invitation. Group invites require a **global API key**. Users who are already members of the organization cannot be invited to individual groups — they already have cascade access to every group.
### New: Team management endpoints
You can now manage team members and pending invites programmatically. These endpoints unblock automated user provisioning, role changes, and cleanup without touching the AthenaHQ dashboard.
**List members and access**
* **[GET /api/v1/organizations/members](/api-reference/team-management/list-organization-members)** — Lists all members of your organization with their email, name, and role. Requires a global API key.
* **[GET /api/v1/websites//members](/api-reference/team-management/list-website-members)** — Lists all users with access to a website, tagged with `access_type` (`organization` for implicit access via org membership, `website` for explicit website membership). Accepts a global or website-scoped API key.
* **[GET /api/v1/users//websites](/api-reference/team-management/list-user-websites)** — Lists the websites a specific user has access to within your organization. Requires a global API key.
**Update and remove members**
* **[PATCH /api/v1/organizations/members/](/api-reference/team-management/update-organization-member-role)** — Update an organization member's role. Requires a global API key.
* **[DELETE /api/v1/organizations/members/](/api-reference/team-management/remove-organization-member)** — Remove a user from your organization. Also cleans up any stray website-member rows across all websites in the organization, in a single atomic transaction. Requires a global API key.
* **[PATCH /api/v1/websites//members/](/api-reference/team-management/update-website-member-role)** — Update a website member's role. Accepts a global or website-scoped API key.
* **[DELETE /api/v1/websites//members/](/api-reference/team-management/remove-website-member)** — Remove a user's explicit access to a website. Accepts a global or website-scoped API key.
**Revoke pending invites**
* **[DELETE /api/v1/invites/org/](/api-reference/team-management/revoke-organization-invite)** — Soft-revoke a pending organization invite. Requires a global API key.
* **[DELETE /api/v1/invites/website/](/api-reference/team-management/revoke-website-invite)** — Soft-revoke a pending website invite. Accepts a global or website-scoped API key.
Mutating endpoints include safety guards: you cannot modify the API key's owning user, the organization owner, or the last remaining admin of an organization.
### Updated: Direct invite responses now include `user_id`
[POST /api/v1/invites](/api-reference/team-management/create-invite) and [POST /api/v1/invites/bulk](/api-reference/team-management/bulk-invite-to-websites-or-groups) now return `user_id` in their success responses **for `invite_method: "direct"` only**. In direct mode, the user is looked up or created immediately, so returning the ID gives you everything you need to call the new member-management endpoints without a discovery round-trip. Email-method invites intentionally do not return `user_id` — doing so would let any API key holder enumerate account existence across tenants by email. This change is backward-compatible; existing integrations continue to work unchanged.
### New: Provision Website endpoint (Beta)
You can now create a fully configured website in a single API call, skipping the onboarding wizard. Optionally set up competitors, prompts, and a processing schedule — all in one request. This endpoint is currently in beta — the request and response schemas may change.
* **[POST /api/v1/websites/provision](/api-reference/basics/provision-website)** — Creates a website with optional competitors, prompts, and schedule. Requires a global API key.
### New: Get group credits
You can now retrieve the current credit balance for a group, including the monthly and one-off breakdown.
* **[GET /api/v1/credits/group](/api-reference/billing/get-group-credits)** — Returns the credit balance for a specific group. Requires a global API key.
## March 2026
### New: Get and update individual groups
You can now fetch a single group by ID and update it — rename the group, add websites, or remove websites.
* **[GET /api/v1/groups/](/api-reference/groups/get-group)** — Retrieve a single group with its associated websites.
* **[PATCH /api/v1/groups/](/api-reference/groups/update-group)** — Rename a group, add websites, and/or remove websites.
Both endpoints require a global API key.
### New: Bulk invite to websites
You can now invite a user to multiple websites in a single API call. The endpoint processes each website independently and returns per-website results, making it easy to onboard users across your organization.
* **[POST /api/v1/invites/bulk](/api-reference/team-management/bulk-invite-to-websites-or-groups)** — Invite a user to up to 50 websites at once. Supports both direct and email invite methods.
## February 2026
### New: Groups endpoints
You can now create and manage groups of websites via the API. Groups let you organize multiple websites under a single entity within your organization.
* **[GET /api/v1/groups](/api-reference/groups/list-groups)** — List all groups for your organization, including associated websites.
* **[POST /api/v1/groups](/api-reference/groups/create-group)** — Create a new group with one or more websites.
Both endpoints require a global API key.
# Approve Content Brief
Source: https://docs.athenahq.ai/api-reference/content/approve-content-brief
/api-reference/openapi.json post /api/v1/content/{content_id}/brief/approve
Approve a content brief and start writing the article from it. Only valid while the piece is at status generated_brief. The article is generated from the brief exactly as it currently stands, including any revisions made with revise_brief or edits made in the app. Consumes content credits; poll get_content_status afterwards, then read the result with get_content_draft.
# Delete Content
Source: https://docs.athenahq.ai/api-reference/content/delete-content
/api-reference/openapi.json delete /api/v1/content/{content_id}
Delete a content row. Destructive: physical row delete, no undo. Powers delete-and-retry. Bulk delete is out of scope.
# Edit Content Draft
Source: https://docs.athenahq.ai/api-reference/content/edit-content-draft
/api-reference/openapi.json post /api/v1/content/{content_id}/edit
Apply exact find-and-replace edits to a content draft's article body. Deterministic, no AI model involved: your replacement text lands verbatim (use the revise endpoint when you want an AI rewrite from an instruction). Each edit's find text must match the current body exactly once; zero or multiple matches fail the whole call with 400 and nothing is saved, so extend the find text until it is unique. Edits apply in order, later ones see earlier results, and the batch is recorded as one new version, recoverable via the versions endpoints. Pass expected_version_number from the draft endpoint to fail with 409 when a new version was recorded after your read (a revision, edit, or restore). An app autosave changes the body without recording a version; that drift is caught by the anchors themselves, since a moved or vanished find text fails the call.
# Get Content Detail
Source: https://docs.athenahq.ai/api-reference/content/get-content-detail
/api-reference/openapi.json get /api/v1/content/{content_id}
Fetch the full detail of a single tracked content item — including the actual text: the content brief (`brief`) and the article/page body (`body`). `body` holds generated drafts, optimize rewrites, snipe articles, authored text, and scraped tracked-page bodies alike.
Use this after listing tracked content (`POST /api/v1/content`) to read the text behind a `content_id`, or to poll `status` while generation runs — `generated_brief` means the brief is ready while the article is still being written. Also exposed as the MCP tool `get_content_detail`.
Tracked pages that have not been scraped yet return `null` text fields. Unknown or hidden `content_id` returns 404.
# Get Content Draft
Source: https://docs.athenahq.ai/api-reference/content/get-content-draft
/api-reference/openapi.json get /api/v1/content/{content_id}/draft
Read the current draft text of a content item — the article body as it stands right now, including every revision applied so far. Use this before revise_content to see what you are changing, and after it to confirm the result. A status of generated_brief means the brief is ready while the article is still being written, so body may still be empty. For the full record (cited urls, links, social posts) use get_content_detail instead.
# Get Content Pipeline Status
Source: https://docs.athenahq.ai/api-reference/content/get-content-pipeline-status
/api-reference/openapi.json get /api/v1/content/{content_id}/status
Get the normalized pipeline status (running | succeeded | failed) for one content row, plus the raw stage behind it. Read-only. Poll once per contentId returned by create_content (content.pipeline.start). A stage of generated_brief with status running means the brief is ready and waiting: for a non-auto-approve draft it stays there until the brief approve endpoint is called, so do not treat running as always in progress.
# Get Content Version
Source: https://docs.athenahq.ai/api-reference/content/get-content-version
/api-reference/openapi.json get /api/v1/content/{content_id}/versions/{version_id}
Read the full text of one saved version of a content item. Use it to compare two passes (fetch both and diff them yourself) or to check what an earlier version said before restoring it.
# List Content Hub Sheets
Source: https://docs.athenahq.ai/api-reference/content/list-content-hub-sheets
/api-reference/openapi.json get /api/v1/content/sheets
Returns the Content Hub tabs configured for a website. Each tab is either a `sheet` (content pinned via `content.sheet_id`) or a `view` (saved filter layout over the main content pool). Call this first to discover the `sheet_id`s you can pass to `POST /api/v1/content`.
# List Content Items
Source: https://docs.athenahq.ai/api-reference/content/list-content-items
/api-reference/openapi.json get /api/v1/content/items
Returns every content item in a website's Content Hub, published or not: in-flight drafts, briefs, snipes, optimize and slice runs, scheduled and failed items, plus tracked pages. This is the enumeration path from a `sheet_id` to its unpublished rows. `POST /api/v1/content` lists only finished pipeline rows, with citation and impression metrics, so a sheet full of generated drafts appears empty there; use this endpoint to see them.
Returns identity fields only (id, title, type, stage, sheet, URL, timestamps, target prompt ids), no metrics. Reads from the primary store and is uncached, so an item is listable the moment `POST /api/v1/content/generate` returns its `content_id`. Read a row's text with `GET /api/v1/content/{content_id}`.
`stage` is the raw pipeline workflow state, not a publication flag: `null` means no pipeline record (most external and imported tracked pages), and manual editor items carry `generated`. Treat an item as published only when its stage is `done` (or it is an external or imported page) and it has a `url`; `done` without a `url` is an unpublished orphan.
Passing the `sheet_id` of a view-type tab (see `sheet_type` on `GET /api/v1/content/sheets`) lists the shared main pool without the view's saved filters. Hidden content (`is_hidden = true`) is excluded. Pagination uses `page_size + 1` lookahead: `pagination.has_more === true` means the next page exists; there is no total-count field. Pass an unknown `sheet_id` or `prompt_id` (or one from another website) and the endpoint returns 403.
Also exposed as the MCP tool `list_content`.
# List Content Versions
Source: https://docs.athenahq.ai/api-reference/content/list-content-versions
/api-reference/openapi.json post /api/v1/content/{content_id}/versions
List the saved versions of a content item, newest first. Each entry carries its version number, label, how it was produced, and who made it. Use it to see how a draft evolved, then get_content_version to read a specific one, or restore_content_version to go back to it.
# List Tracked Content
Source: https://docs.athenahq.ai/api-reference/content/list-tracked-content
/api-reference/openapi.json post /api/v1/content
Returns paginated tracked content with citation, impression, and response metrics joined for the requested date range. Hidden content (`is_hidden = true`) is excluded.
Pagination uses `page_size + 1` lookahead — `pagination.has_more === true` means the next page exists; there is no total-count field.
Use the `sheet_id`, `content_type`, and standard `filters` knobs to scope the result. Pass an unknown `sheet_id` (or one from another website) and the endpoint returns 403.
# Mark Content as Published
Source: https://docs.athenahq.ai/api-reference/content/mark-content-as-published
/api-reference/openapi.json post /api/v1/content/{content_id}/publish
Mark a content item as published at its live URL so Athena starts attributing citations and mentions to it. Call this only after the piece is actually live on the site: the URL becomes the item's citation/metric join key, the publish time is stamped, and the pipeline stage moves to done. A first publish requires a finished article (stage generated), with one exception: an Optimize draft is created from a page that is already live and can be marked published while it waits at stage pending, as long as no Athena review is running on it. Briefs, still-generating or failed pieces, Optimize drafts with a review in flight, and items with a scheduled CMS publish are rejected with 409 and the reason. Pass the exact public URL of the live page (a bare domain path like acme.com/blog/post is fine; the protocol is stripped on store). Calling it again on an already-published item (including external and imported pages, which are live by definition) updates the tracked URL only, keeping the original publish time. This is the only way to set a content URL over the API: the rename endpoint is deliberately title-only.
# Per-Content Prompt Citation Breakdown
Source: https://docs.athenahq.ai/api-reference/content/per-content-prompt-citation-breakdown
/api-reference/openapi.json post /api/v1/content/prompts
For a single tracked content item, returns every prompt whose AI responses cite the URL — with citations, citation %, and estimated impressions for the date range.
Use this to drill into a specific URL after `POST /api/v1/content`. Works for both 1st-party (topic-attached) and 3rd-party / Reddit content without topic assignment.
When the URL exists but has no normalized form (legacy unnormalized rows) the response is a successful 200 with `prompts: []`. Unknown `content_id` returns 404.
# Rename Content
Source: https://docs.athenahq.ai/api-reference/content/rename-content
/api-reference/openapi.json patch /api/v1/content/{content_id}
Rename a content row's title. URL editing is not supported — URL is the content asset's stable identity and cannot be changed here.
# Restore Content Version
Source: https://docs.athenahq.ai/api-reference/content/restore-content-version
/api-reference/openapi.json post /api/v1/content/{content_id}/versions/{version_id}/restore
Bring an earlier version's text back as the current draft — use it when a later pass came out worse than an earlier one. Nothing is deleted: the restored text is appended as a new version on top of the history, so the passes in between remain readable and restorable.
# Revise Content Brief
Source: https://docs.athenahq.ai/api-reference/content/revise-content-brief
/api-reference/openapi.json post /api/v1/content/{content_id}/brief/revise
Rewrite a content brief from a natural-language instruction (for example: 'add a section on pricing objections', 'cut the competitor comparison'). An AI model performs the rewrite server-side, so the result is generated text, not your literal wording. Records each pass as a version; iterate by calling it again, since each call starts from the current brief. Most useful while a piece waits at status generated_brief, where the brief still shapes what the article will say — call approve_brief once it reads right. It also works after the article exists, to correct the brief for a later regeneration; note that revising the brief does NOT rewrite an already-generated article, so use revise_content for that.
# Revise Content Draft
Source: https://docs.athenahq.ai/api-reference/content/revise-content-draft
/api-reference/openapi.json post /api/v1/content/{content_id}/revise
Rewrite an existing content draft from a natural-language instruction (for example: 'tighten the intro', 'add a section on pricing', 'remove the second half'). An AI model performs the rewrite server-side, so the result is generated text, not your literal wording; when you already have the exact replacement text, use the edit endpoint instead. Applies the change to the whole article and records it as a new version, so earlier passes stay recoverable via get_content_versions / restore_content_version. Iterate by calling it again — each call starts from the current text, so no version id is needed. Use this instead of create_content to change a draft; it edits in place rather than generating a new piece. The returned body is always the complete replacement article, never just the edited passage; compare body_word_count with previous_body_word_count to confirm nothing unexpected was lost.
# Start Content Pipeline
Source: https://docs.athenahq.ai/api-reference/content/start-content-pipeline
/api-reference/openapi.json post /api/v1/content/generate
Start the content pipeline in one of four modes — draft (write new content from promptIds), snipe (outrank a competitor url), optimize (improve an existing url for AI search), slice (split one url into several articles). Required fields by mode: draft needs promptIds (resolve real prompt ids first — via prompts.selectForDraft in chat, or get_prompts / GET /v1/prompts over MCP and the API; never invent ids) AND title; snipe needs url AND title; optimize needs url AND title; slice needs url (and must NOT include promptIds). Returns durable contentIds (job handles); poll get_content_status (content.pipeline.status) per id. Credit op; requires approval.
# Track External URLs
Source: https://docs.athenahq.ai/api-reference/content/track-external-urls
/api-reference/openapi.json post /api/v1/content/track
Register existing pages or third-party URLs as tracked Content Hub items so Athena attributes citations and mentions to them. Creates external content rows from bare URLs with no generation and no credit cost. Tracking starts immediately: the normalized URL becomes the citation/metric join key, so pages cited in the website's monitored AI responses accrue metrics with no publish step (use it for guest posts, partner placements, or any page Athena did not generate). Idempotent per URL: a URL already present on the website (any content type) is not duplicated; the response lists it under skipped with the existing content_id and type. Check that type before chaining destructive calls (a skip can resolve to first-party generated content that shares the URL). Rows are created without page text, which citation tracking does not need; the body can be filled from the app later. Duplicate URLs within one call (including tracking-param variants of the same page) collapse to one row, first occurrence wins. Optional sheet_id files rows under a Content Hub tab; view-type tabs resolve to the main pool (null), echoed per row. Optional per-URL fields set the customer's own Content Hub columns on the created row, addressed by column name as shown on the destination tab (text, number, date, checkbox, link, and multi-select columns; unknown multi-select options are created). An unknown column name or a value that does not fit the column type rejects the whole call and nothing is tracked; skipped URLs keep their existing values. Each created and skipped entry includes destination_name and content_hub_url. Share these with the user alongside the created and skipped counts. The link opens the specific item with its website and destination selected. Omitting sheet_id uses the shared pool regardless of the currently open browser tab. A skipped URL remains in its existing tab, even when a different sheet_id was requested.
# Create Group
Source: https://docs.athenahq.ai/api-reference/groups/create-group
/api-reference/openapi.json post /api/v1/groups
Creates a new group with associated websites. Requires a global API key. **Partner integrations** may include an `external_id` to map their own identifier onto the new Athena group.
# Get Group
Source: https://docs.athenahq.ai/api-reference/groups/get-group
/api-reference/openapi.json get /api/v1/groups/{group_id}
Returns a single group by ID, including associated websites. Requires a global API key. **Partner integrations** additionally receive an `externalId` field populated from the partner mapping (if any), and every website object inside `websites` carries its own `externalId` (`null` when that website has no mapping), so sites can be matched by your own identifier instead of by URL.
# List Groups
Source: https://docs.athenahq.ai/api-reference/groups/list-groups
/api-reference/openapi.json get /api/v1/groups
Returns all groups for your organization, including associated websites. Requires a global API key. **Partner integrations** may pass `external_id` as a query parameter to find the Athena group mapped to a partner-supplied identifier. Partner responses additionally include `externalId` on each group and on every website object inside `websites` (`null` when no mapping exists), so sites can be matched by your own identifier instead of by URL.
# Update Group
Source: https://docs.athenahq.ai/api-reference/groups/update-group
/api-reference/openapi.json patch /api/v1/groups/{group_id}
Updates a group's name, adds websites, removes websites, and/or (partners only) sets or clears the `external_id` mapping. At least one field must be provided. Requires a global API key. **Partner integrations** may pass `external_id` as a non-empty string to set/replace the mapping, or as `null` to clear it. The partner response includes `externalId` on the group and on every website object inside `websites` (`null` when no mapping exists).
# Introduction
Source: https://docs.athenahq.ai/api-reference/introduction
Programmatically interact and integrate with AthenaHQ
## AthenaHQ API
The AthenaHQ API enables programmatic and scalable interaction with the AthenaHQ platform. Build custom integrations, automate workflows, and extend AthenaHQ's capabilities to meet your organization's specific needs.
## Authentication
All API requests require authentication using an API key. API keys are managed through your organization's dashboard and can be scoped to specific websites for granular access control.
Generate and manage API keys in your organization settings
For detailed information about authentication methods and API key management,
see the [Authentication](/api-reference/authentication) documentation.
## Dates & Timezones
All timestamps passed to and returned from the API are in UTC, unless otherwise specified.
## Streaming schedules
Response analytics select one schedule at a time. Use `filters.schedule_id` in
JSON requests: `default` (also used when omitted), `manual`, or a custom
schedule's UUID. Default includes all pre-cutover history. Archived schedules
retain their results. There is no combined All schedules selection.
Discover available schedules with `GET /api/v1/prompt-schedules?website_id=...`
and use each row's `selection` value. For `GET /api/v1/date-range`, pass that
value as the `schedule_id` query parameter. The MCP equivalent is
`get_prompt_schedules`.
# Add Brand Facts
Source: https://docs.athenahq.ai/api-reference/knowledge-base/add-brand-facts
/api-reference/openapi.json post /api/v1/knowledge-base/facts
Adds brand facts to a website's Knowledge Base in bulk (1-50 per call). Every fact runs the full ingestion pipeline — deduplication, approval gates, and pillar routing — and there is no way to force-approve: inputs are declarative (text, optional source URL, optional pillar pin) and the response reports one outcome per fact. Facts without a pillar_id are routed automatically and may land unfiled. Requires a website-admin API key. Also available as the MCP tool `add_brand_facts`.
# Create Pillar
Source: https://docs.athenahq.ai/api-reference/knowledge-base/create-pillar
/api-reference/openapi.json post /api/v1/knowledge-base/pillars
Creates a Knowledge Base pillar (a subject area that groups brand facts) from a name and optional description. Get-or-create semantics: if a pillar with the same name already exists (case-insensitive), it is returned with `created: false` instead of failing, so retries and re-imports are idempotent. Requires a website-admin API key. Also available as the MCP tool `create_pillar`.
# Delete Brand Facts
Source: https://docs.athenahq.ai/api-reference/knowledge-base/delete-brand-facts
/api-reference/openapi.json post /api/v1/knowledge-base/facts/delete
Permanently deletes 1-50 brand facts from a website's Knowledge Base. There is no undo. Ids with no fact on the website are reported in not_found_ids instead of failing the call, so retries are idempotent. Requires a website-admin API key; on OAuth MCP connections the signed-in user must hold the admin role. Also available as the MCP tool `delete_brand_facts`.
# Delete Pillars
Source: https://docs.athenahq.ai/api-reference/knowledge-base/delete-pillars
/api-reference/openapi.json post /api/v1/knowledge-base/pillars/delete
Permanently deletes 1-20 Knowledge Base pillars and every fact filed under them. Facts are deleted, not unfiled; there is no undo. Ids with no pillar on the website are reported in not_found_ids instead of failing the call, so retries are idempotent; ids in failed_ids are untouched and safe to retry. Requires a website-admin API key; on OAuth MCP connections the signed-in user must hold the admin role. Also available as the MCP tool `delete_pillars`.
# Get Brand Facts
Source: https://docs.athenahq.ai/api-reference/knowledge-base/get-brand-facts
/api-reference/openapi.json get /api/v1/knowledge-base/facts
Lists a website's brand facts, newest first, with offset paging. By default excludes facts generated by Oracle analysis; pass `include_oracle=true` to include them. Filter by pillar, review status (defaults to approved), source type, or `unfiled=true` for facts not under any published pillar. `unfiled` and `pillar_id` are mutually exclusive. Also available as the MCP tool `get_brand_facts`.
# Get Pillar Document
Source: https://docs.athenahq.ai/api-reference/knowledge-base/get-pillar-document
/api-reference/openapi.json get /api/v1/knowledge-base/pillars/{pillar_id}/document
Fetches a pillar's synthesized markdown document. Returns `document: null` when the pillar exists but has no synthesized document yet (this is a 200, not a 404). Also available as the MCP tool `get_pillar_document`.
# Get Pillars
Source: https://docs.athenahq.ai/api-reference/knowledge-base/get-pillars
/api-reference/openapi.json get /api/v1/knowledge-base/pillars
Lists a website's Knowledge Base pillars (excluding archived ones) with approved-fact counts, whether a synthesized document exists, and when each pillar was last researched. Also available as the MCP tool `get_pillars`.
# Merge Pillars
Source: https://docs.athenahq.ai/api-reference/knowledge-base/merge-pillars
/api-reference/openapi.json post /api/v1/knowledge-base/pillars/merge
Merges 1-20 source pillars into a published target pillar: every fact on the sources (any review status) re-files onto the target, page links carry over keeping the stronger signal, and the source pillars are then deleted. The target must be a published pillar and must not appear among the sources. Unlike the other Knowledge Base writes, retries are strict: missing source ids are rejected rather than skipped, so re-read the pillars before retrying a failed merge. Requires a website-admin API key. Also available as the MCP tool `merge_pillars`.
# Move Brand Facts
Source: https://docs.athenahq.ai/api-reference/knowledge-base/move-brand-facts
/api-reference/openapi.json post /api/v1/knowledge-base/facts/move
Files 1-50 brand facts under a published Knowledge Base pillar. Works for unfiled facts and re-files facts from other pillars. Review status never changes, and only approved facts under a published pillar feed content generation, so moving is what puts approved facts to work. Ids with no fact on the website are reported in not_found_ids instead of failing the call, so retries are idempotent. Requires a website-admin API key. Also available as the MCP tool `move_brand_facts`.
# Search Brand Facts
Source: https://docs.athenahq.ai/api-reference/knowledge-base/search-brand-facts
/api-reference/openapi.json get /api/v1/knowledge-base/facts/search
Semantic search over a website's approved brand facts. Combines vector similarity with full-text search, so it also reaches facts not filed under any pillar. Returns fact text with confidence, source URL and quote, and the published pillar it belongs to (null when unfiled). Also available as the MCP tool `search_brand_facts`.
# Update Brand Fact
Source: https://docs.athenahq.ai/api-reference/knowledge-base/update-brand-fact
/api-reference/openapi.json patch /api/v1/knowledge-base/facts/{fact_id}
Updates one brand fact's text, source URL, or confidence. Only provided fields change; pass source_url: "" to clear the stored source. Changing the text creates a new fact (new id) and archives the current one; the new fact keeps the current review status and is the fact returned. Source URL and confidence edits update the fact in place and re-match the source to the internal link bank. Review status never changes through this endpoint. Requires a website-admin API key. Also available as the MCP tool `update_brand_fact`.
# Update Pillar
Source: https://docs.athenahq.ai/api-reference/knowledge-base/update-pillar
/api-reference/openapi.json patch /api/v1/knowledge-base/pillars/{pillar_id}
Updates a Knowledge Base pillar's name, description, or status. At least one of the three must be provided; only provided fields change. Renaming returns a 409 when another pillar already uses the name. Status accepts published or archived: archiving hides the pillar from pillar listings and stops its facts feeding content generation, while keeping the facts stored. Requires a website-admin API key. Also available as the MCP tool `update_pillar`.
# Looker Studio
Source: https://docs.athenahq.ai/api-reference/looker-studio
Integrate AthenaHQ with Looker Studio
## Setup
Go to the [API Keys page](https://app.athenahq.ai/organization?tab=api) in your AthenaHQ dashboard.
Select which websites to attach to the key, click create, and save the key securely.
Create and manage API keys in your organization settings
1. Add a new data source in a Report or the data sources section
2. Search for and select "Build Your Own" under "Partner Connectors"
3. Paste the Deployment ID (found in the API tab of your AthenaHQ dashboard)
4. Follow authorization prompts and paste your API key
Configure the following options:
| Option | Default | Description |
| ------------------- | ---------------- | -------------------------------------- |
| Website | Required | The website to pull data from |
| Models | All | Filter by LLM models |
| Prompt type | All | Filter by prompt type |
| Prompt status | All | Filter by status (recommended: Active) |
| Prompts | All | Filter by specific prompts |
| Prompt tags | All | Filter by specific prompt tags |
| Prompt tag matching | Any selected tag | Require any or all selected tags |
| Competitors | All | Filter by specific competitors |
## Usage
Once connected, you can build reports using the following dimensions and metrics.
### Dimensions
| Field | Type | Description |
| ------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Date | Date | The date of the data |
| Company Name | Text | The name of the company |
| Model | Text | The LLM model (ChatGPT, Perplexity, etc.) |
| Is Own Brand | Boolean | Whether the company is your brand |
| Topic | Text | The topic associated with the prompt |
| Prompt | Text | The prompt text |
| Response | Text | The raw AI response text. Selecting this field switches the report to per-response granularity. To get binary 0% / 100% mention and citation rates, also include `Company Name` (or `Is Own Brand`) in the report; otherwise multiple entity rows for the same response are averaged together. Best paired with `Prompt`, `Model`, and `Company Name`. |
### Metrics
| Field | Type | Aggregation | Description |
| -------------- | ------ | ----------- | -------------------------------------------------------------- |
| Share of Voice | Number | Average | Distribution of brand mentions vs. competitors on GenAI Search |
| Mention Rate | Number | Average | How often your brand appears in AI responses over time |
| Citation Rate | Number | Average | How often your domain is cited in AI responses |
| Position | Number | Average | Your average position in LLM responses |
# MCP Server
Source: https://docs.athenahq.ai/api-reference/mcp
Connect AthenaHQ to ChatGPT, Claude, and other AI assistants via the Model Context Protocol
AthenaHQ ships a remote [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server. Once connected, an AI assistant like Claude or ChatGPT can query your AI search visibility data in plain language (share of voice, citation and mention rates, ranking positions, cited sources, tracked prompts and responses, content, and pitches) without you writing any API calls.
Connections you sign in to (Claude.ai and ChatGPT) read the same data your account can already see. Write tools are available on API-key connections and, for signed-in connections, wherever your role has the matching write permission. Every write runs the same validation and audit logging as the dashboard.
**Server URL**
```text theme={null}
https://api.athenahq.ai/api/mcp
```
## Connect Claude.ai
No API key needed. You sign in with your AthenaHQ account.
In [claude.ai](https://claude.ai), go to **Customize → Connectors → the "+"
→ Add custom connector**.
Enter `https://api.athenahq.ai/api/mcp` and continue.
You'll be prompted to sign in with your AthenaHQ account and choose which
organization to connect. Claude then discovers all available tools
automatically.
## Connect ChatGPT
The fastest way is the official AthenaHQ plugin. No API key needed. You sign in with your AthenaHQ account.
### Does the plugin have a separate cost?
From AthenaHQ, the plugin is free to install and has no separate plugin cost.
It uses your existing AthenaHQ account, and normal plan limits still apply to
the features and actions you access. Plugin availability in ChatGPT depends on
your OpenAI plan, workspace settings, role, and region.
Open the [AthenaHQ plugin
listing](https://chatgpt.com/plugins/plugin_asdk_app_6a4da6c4bcfc81919397faceada2af69)
in ChatGPT and click **Install plugin**.
Authorize with your AthenaHQ account and choose which organization to
connect.
Type `@AthenaHQ` followed by your question, for example "@AthenaHQ how is my
brand showing up in AI search?", and ChatGPT pulls your data into the
conversation.
Prefer a manual setup? You can still add the MCP server as a custom connector:
in ChatGPT **Settings**, add a custom MCP connector (found under **Apps** or
**Connectors**, depending on your plan and version), enter
`https://api.athenahq.ai/api/mcp`, and sign in with your AthenaHQ account.
Custom connectors require a plan that supports them (Pro, Business, or
Enterprise) and may need developer mode enabled.
## Connect other MCP clients
Clients that don't support the sign-in flow authenticate with an API key using the `x-api-key` header.
Go to the [API Keys page](https://app.athenahq.ai/settings/api) in your dashboard. Scope the key to specific websites if you want to limit access, then save it securely.
Create, view, and manage API keys in your organization settings
Replace `your_api_key_here` with your key.
```json theme={null}
{
"mcpServers": {
"athenahq": {
"type": "http",
"url": "https://api.athenahq.ai/api/mcp",
"headers": {
"x-api-key": "your_api_key_here"
}
}
}
}
```
### Claude Code
```bash theme={null}
claude mcp add --transport http --scope user athenahq https://api.athenahq.ai/api/mcp \
--header "x-api-key: your_api_key_here"
```
## Access and scope
An MCP connection sees exactly what its credential is authorized for, the same scoping as the [REST API](/api-reference/authentication):
* **Organization** and **website** access follow the signed-in user (Claude.ai) or the API key's scope.
* A website-scoped API key is limited to its websites. The existing `get_credits_organization` balance tool also allows scoped keys to read its organization-wide aggregate. Detailed usage tools (`get_credit_usage` and `get_credit_usage_events`) require a global organization API key, or a signed-in user with organization billing access. Website/group-only membership is insufficient for these usage tools.
* **Write tools** register on API-key connections and on signed-in connections bound to an organization. On a signed-in connection, each write is gated by your role's permission for that category (see the [Write tools](#write-tools) table); API keys act with admin privileges within their scope. Every write runs the same validation and audit logging as the dashboard.
Only organization admins can create, edit, or delete API keys. On signed-in
connections, tools follow your role: a viewer can read everything below except
the three org-wide admin reads (`get_groups`, `get_group_detail`,
`get_user_by_email`) and the credit-usage tools, which require organization
billing access. Viewers can only use writes open to every member (such as
`create_saved_view`).
## Available tools
The assistant discovers these automatically once connected. Most map to an endpoint in the [API reference](/api-reference/introduction).
### Metrics
| Tool | What it returns |
| -------------------------------- | ----------------------------------------------------------------------------------------- |
| `get_share_of_voice_cumulative` | Share of voice across competitors for a date range |
| `get_share_of_voice_time_series` | Share of voice over time (daily) |
| `get_citation_rate_cumulative` | Citation rate (how often AI answers link to you) across competitors |
| `get_citation_rate_time_series` | Citation rate over time (daily) |
| `get_mention_rate_cumulative` | Mention rate (how often AI answers name your brand) across competitors |
| `get_mention_rate_time_series` | Mention rate over time (daily) |
| `get_position_cumulative` | Average ranking position in AI answers for a date range |
| `get_position_time_series` | Ranking position over time (daily) |
| `get_position_distribution` | Share of responses where the brand ranks top, middle, or bottom |
| `get_ai_search_value` | AI search value: topic-market value, captured value, headroom, coverage, per-topic detail |
| `get_shopping_metrics` | Shopping Insights: product appearances in AI shopping answers, positions, prices, rivals |
### Analytics queries
Flexible query tools over the same analytics warehouse the dashboard uses, for questions the fixed metrics tools don't cover.
| Tool | What it returns |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `query_metrics` | Aggregated measures (count, avg, sum, min, max) over any cube, grouped by any dimension, with optional period-over-period comparison |
| `query_rows` | Individual rows (response text, identifiers, mentions) from any cube, with cursor pagination |
### Attributes
Brand-perception keywords (like "Affordable" or "Slow Support") extracted from AI answers.
| Tool | What it returns |
| ---------------------------------- | ------------------------------------------------------------------ |
| `get_attributes` | Attributes tracked for a website, with attribute IDs |
| `get_attribute_metrics` | Per attribute, how many responses mentioned it across a date range |
| `get_competitor_attribute_metrics` | The same breakdown per tracked competitor |
| `get_attribute_time_series` | Daily trend for one attribute, brand and competitors side by side |
### Prompts and responses
| Tool | What it returns |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_prompts` | Tracked prompts for a website, with volume, status, and geography |
| `get_prompt_tags` | Prompt tags for a website, with per-tag prompt counts |
| `get_personas` | Personas configured for a website, with per-persona prompt counts |
| `get_topics` | Active topics for a website, with the count of active prompts in each |
| `get_responses` | AI answers for a website, with cited sources, sentiment, and ranking. Set `include_response: false` and `compact_sources: true` for a light variation-level export |
| `get_response_detail` | One AI answer with full sources, mentions, and rank details |
| `get_response_streaming_status` | State and queue progress of the latest (or a specific) response run |
### Content
| Tool | What it returns |
| ------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `get_tracked_content` | Tracked content with citation, mention, and impression metrics |
| `list_content` | Every content item, published or not, each with the ids of the prompts it targets |
| `get_content_detail` | Full text of one content item: brief, body, cited URLs, links, status, and the prompts it was written for |
| `get_content_citation_prompts` | Prompts whose AI answers cited a given content item |
| `get_content_hub_sheets` | Content Hub tabs configured for a website |
| `get_content_status` | Normalized generation status (running / succeeded / failed) for one content item |
| `get_content_draft` | Current draft text of one item: article body, brief, status, latest version |
| `get_content_versions` | Version history of a content item, newest first, with labels and authors |
| `get_content_version` | Full text of one saved version |
Two of these answer different questions about the same page, and it is worth keeping them apart. `get_content_detail` and `list_content` return the prompts a page was **written for** (its targeting, the same ids `create_content` takes); that comes from the content record and does not depend on any AI answer having appeared. `get_content_citation_prompts` returns the prompts whose AI answers **cited** the page over a date range, so it is legitimately empty for a page nothing has cited yet.
Targeting includes prompts that were later deleted, flagged `status: "deleted"`, because the page was still written for them and the Content Hub still shows them. `get_prompts` does not list deleted prompts, so an id from a targeting list may not resolve there; `get_content_detail` returns the prompt text inline for that reason. Targeting is capped at 100 entries per page (25 ids per row in `list_content`), with the untruncated size in `prompts_total` / `prompt_count`.
### Knowledge Base
Requires the Knowledge Base to be enabled for the organization; when it isn't, these tools return an error explaining that.
| Tool | What it returns |
| --------------------- | -------------------------------------------------------------------------------------- |
| `search_brand_facts` | Semantic search over approved brand facts, including facts not filed under any pillar |
| `get_brand_facts` | Paged brand-fact listing with pillar, review-status, source-type, and unfiled filters |
| `get_pillars` | Knowledge Base pillars with approved-fact counts and synthesized-document availability |
| `get_pillar_document` | A pillar's synthesized markdown document |
### Sources and competitors
| Tool | What it returns |
| ------------------ | -------------------------------------------------------------------------------- |
| `get_sources` | Top cited root domains, classified as owned / competitor / partner / third-party |
| `get_source_pages` | Individual cited URLs with per-URL metrics |
| `get_competitors` | Competitors tracked for a website |
### Pitches
| Tool | What it returns |
| -------------- | ------------------------------------------------------------------------------- |
| `list_pitches` | Pitch reports for the organization |
| `get_pitch` | One pitch report: competitors, prompts, attributes, top citing sources, metrics |
### Account and configuration
| Tool | What it returns |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| `list_websites` | Websites your credential can access, with the country market each targets (`baseCountry`) |
| `get_groups` | Groups in the organization (global API key or org-admin sign-in) |
| `get_group_detail` | One group with its member websites (global API key or org-admin sign-in) |
| `get_user_by_email` | User lookup by email, scoped to the caller's organization (global API key or org-admin sign-in) |
| `get_date_range` | Earliest and latest response dates for a website |
| `get_locations` | Geographies configured for a website |
| `get_saved_views` | Saved filter presets for a website |
| `get_group_saved_views` | Saved views shared across a group |
| `get_credits_website` | Credit balance for a website |
| `get_credits_organization` | Credit balance for the organization |
| `get_credit_usage` | Credit usage totals, time buckets, and paginated charged-pool breakdown for the organization |
| `get_credit_usage_events` | Paginated credit charges/refunds, recorded actions, and originating-website attribution |
Credit-usage tools accept `website_id` to identify the organization, an optional `range` (`24h`, `7d`, `30d`, `90d`, or `all`), and an optional UTC `window` with `start_at_utc` and `end_at_utc`. Use an explicit window for calendar months. For subsequent pages, keep the returned window and use `next_offset`; page sizes default to 25 and are capped at 50. `get_credit_usage_events` also accepts `originating_website_id` within the same organization.
Totals describe the full requested interval; entity and event pages may be partial. Charged group pools differ from originating websites, negative credits are refunds, and “Not recorded” means historical attribution is unavailable. These are read-only MCP tools; they add no public REST endpoints.
### Site diagnostics
| Tool | What it returns |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `check_ai_access` | Whether major AI answer engines (ChatGPT, Claude, Perplexity, Gemini, Copilot, Grok, DeepSeek, Rufus) can crawl a public domain, with per-model HTTP and robots.txt verdicts and a diagnostic log shaped for host or CDN tickets. API-key connections only. |
### Write tools
Available on API-key connections and on signed-in connections bound to an organization. On a signed-in connection, each tool follows your role's permission for its category (rightmost column); API keys act with admin privileges within their scope. Every write is validated and audit-logged, same as the dashboard.
| Tool | What it does | Sign-in permission |
| -------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------- |
| `create_prompts` | Create one or more prompts, with topics, tags, personas, and geography | Prompts: write |
| `update_prompt` | Update a prompt's text, type, topic, or geography | Prompts: write |
| `set_prompts_status` | Pause or unpause multiple prompts in one call | Prompts: write |
| `delete_prompt` | Delete a prompt (soft when responses exist, hard otherwise) | Prompts: write |
| `create_topic` | Create a topic (returns the existing topic when the name is taken) | Prompts: write |
| `update_topic` | Update a topic's name or description | Prompts: write |
| `delete_topic` | Delete a topic, optionally with its prompts | Prompts: write |
| `create_location` | Create a geo-location, optionally attached to prompts | Prompts: write |
| `update_location` | Update a location | Prompts: write |
| `delete_location` | Delete a location | Prompts: write |
| `start_response_streaming` | Start a response run for all prompts or a selection | Prompts: write |
| `create_content` | Start the content pipeline (brief or full article, from a prompt or a topic) | Content: write |
| `revise_brief` | Rewrite a content brief from an instruction, recorded as a version | Content: write |
| `approve_brief` | Approve a brief and start the article from it (uses content credits) | Content: write |
| `revise_content` | Rewrite an article draft from an instruction, recorded as a version | Content: write |
| `edit_content` | Apply exact find-and-replace edits to a draft (deterministic, no AI model), recorded as a version | Content: write |
| `restore_content_version` | Bring an earlier version's text back as the current draft (appends, never deletes) | Content: write |
| `publish_content` | Mark a piece as live at its URL so citation tracking starts | Content: write |
| `track_content_urls` | Register existing or third-party URLs as tracked pages (batch, idempotent, no credits) | Content: write |
| `rename_content` | Rename a content row | Content: write |
| `move_content` | Move content items between sheets (values on conflicting custom columns are permanently dropped) | Content: write |
| `delete_content` | Delete a content row (permanent, no undo) | Content: write |
| `add_brand_facts` | Add 1-50 brand facts through the full ingestion pipeline, with a per-fact outcome report | Brand knowledge: write |
| `update_brand_fact` | Update one brand fact's text, source URL, or confidence | Brand knowledge: write |
| `delete_brand_facts` | Permanently delete 1-50 brand facts (no undo; missing ids reported, not errors) | Admin role |
| `create_pillar` | Create a Knowledge Base pillar (get-or-create by name) | Brand knowledge: write |
| `update_pillar` | Update a pillar's name or description, or publish/archive it | Brand knowledge: write |
| `delete_pillars` | Permanently delete 1-20 pillars and every fact filed under them (no undo) | Admin role |
| `merge_pillars` | Merge source pillars into a published target, then delete the sources | Brand knowledge: write |
| `move_brand_facts` | File 1-50 facts under a published pillar (works for unfiled facts) | Brand knowledge: write |
| `create_saved_view` | Save a dashboard filter preset (name, optional icon, `filters` object up to 64KB, stored verbatim) | Any member |
`create_saved_view` is the one write open to every website member, since saved views are personal presets: sign-in creations are attributed to the connected user, while API-key creations have no owning user, show as created via API in the dashboard, and can only be edited or deleted there by website admins. `create_saved_view` and `move_content` are the two write tools with no REST equivalent.
`delete_brand_facts` and `delete_pillars` are the two writes gated on your role itself rather than a category permission: deleting brand knowledge matches the dashboard's admin-only delete, and deleting a pillar permanently deletes every fact filed under it. An Editor with brand-knowledge write can update facts, curate pillars, and merge them, but not delete. API-key connections qualify through their admin scope.
## Example prompts
Once connected, try:
* "What's my share of voice in AI answers versus my tracked competitors this quarter?"
* "Which domains get cited most for the prompts I track?"
* "Show my citation rate trend over the last 90 days."
* "What's my captured AI search value and headroom by topic?"
* "Pull the AI responses that mention my brand and summarize their sentiment."
# Citation Rate Over Time
Source: https://docs.athenahq.ai/api-reference/metrics/citation-rate-over-time
/api-reference/openapi.json post /api/v1/metrics/citation-rate/time-series
Returns daily citation rate breakdown over the specified date range. Each entry contains the date and citation rate percentages for your brand and competitors.
# Cumulative Citation Rate
Source: https://docs.athenahq.ai/api-reference/metrics/cumulative-citation-rate
/api-reference/openapi.json post /api/v1/metrics/citation-rate/cumulative
Returns citation rate percentages across the specified date range. Shows the percentage of AI responses that cite your brand and competitors as sources.
# Cumulative Mention Rate
Source: https://docs.athenahq.ai/api-reference/metrics/cumulative-mention-rate
/api-reference/openapi.json post /api/v1/metrics/mention-rate/cumulative
Returns mention rate percentages across the specified date range. `mention_rate` is absolute (the percentage of all AI responses that mention the brand); `relative_mention_rate` is the percentage of responses mentioning at least one tracked brand.
# Cumulative Position
Source: https://docs.athenahq.ai/api-reference/metrics/cumulative-position
/api-reference/openapi.json post /api/v1/metrics/position/cumulative
Returns average position/ranking across the specified date range. Shows where your brand and competitors typically appear in AI responses.
# Cumulative Share of Voice
Source: https://docs.athenahq.ai/api-reference/metrics/cumulative-share-of-voice
/api-reference/openapi.json post /api/v1/metrics/share-of-voice/cumulative
Returns aggregated share of voice percentages across the specified date range. Shows what percentage of AI responses mention your brand versus competitors. Each entry also includes `relative_mention_rate`: the entry's mentions as a percentage of responses that mention at least one tracked brand.
# Mention Rate Over Time
Source: https://docs.athenahq.ai/api-reference/metrics/mention-rate-over-time
/api-reference/openapi.json post /api/v1/metrics/mention-rate/time-series
Returns daily mention rate breakdown over the specified date range. Each entry contains the date and, per brand/competitor, the absolute `mention_rate` (share of all responses that day) and `relative_mention_rate` (share of that day's responses mentioning at least one tracked brand).
# Position Over Time
Source: https://docs.athenahq.ai/api-reference/metrics/position-over-time
/api-reference/openapi.json post /api/v1/metrics/position/time-series
Returns daily position/ranking breakdown over the specified date range. Each entry contains position metrics for your brand and competitors.
# Share of Voice Over Time
Source: https://docs.athenahq.ai/api-reference/metrics/share-of-voice-over-time
/api-reference/openapi.json post /api/v1/metrics/share-of-voice/time-series
Returns daily share of voice breakdown over the specified date range. Each entry contains the date and SOV percentages for your brand and competitors, plus each company's `relative_mention_rate`: its mentions as a percentage of that day's responses that mention at least one tracked brand.
# Shopping Metrics
Source: https://docs.athenahq.ai/api-reference/metrics/shopping-metrics
/api-reference/openapi.json post /api/v1/metrics/shopping
Returns the Shopping Insights dashboard for a website over a date range: how often the brand's products appear in AI shopping answers (product carousels) versus competitors, average position and price, the top own and competitor products, the competitor leaderboard, retailer breakdown, rank distribution, price comparison, and a daily appearances trend. One call returns every block the in-app Shopping page renders. Only ChatGPT and AI Mode answer with product carousels, so `models` accepts those two ids. Requires a paid plan.
# Get Pitch Report
Source: https://docs.athenahq.ai/api-reference/pitch-workspace/get-pitch-report
/api-reference/openapi.json get /api/v1/pitches/{pitch_id}
Returns a single pitch report by ID, including the company metadata, generated prompts, tracked competitors, brand and competitor attributes, top citing sources, and aggregate metrics (brand mentions, sentiment, response rate).
Requires a **global (organization-scoped) API key**. Website-scoped keys are rejected with `403 Forbidden`. Returns `404 Not Found` if the pitch does not exist, has been deleted, or belongs to a different organization.
# List Pitches
Source: https://docs.athenahq.ai/api-reference/pitch-workspace/list-pitches
/api-reference/openapi.json get /api/v1/pitches
Returns all non-deleted pitch workspace reports for the calling organization, ordered by creation date (newest first). Pitches are org-level resources and are not scoped to a single website.
Requires a **global (organization-scoped) API key**. Website-scoped keys are rejected with `403 Forbidden`.
# Power BI & Microsoft Fabric
Source: https://docs.athenahq.ai/api-reference/powerbi-fabric
Pull AthenaHQ data into Power BI Desktop, Power BI Service, or Microsoft Fabric via the REST API
AthenaHQ does not ship a native connector for Power BI or Microsoft Fabric, but the public REST API works directly with Power Query M, the same language used in Power BI Desktop, Power BI Service, and Fabric Dataflow Gen2.
## Prerequisites
* An AthenaHQ API key (Organization → API tab). See the [Authentication](/api-reference/authentication) page.
* The `website_id` you want to report on. Fetch it with `GET /api/v1/websites`.
* Power BI Desktop, or a Microsoft Fabric workspace with Dataflow Gen2 enabled.
## Setup
Go to the [API Keys page](https://app.athenahq.ai/organization?tab=api) in your AthenaHQ dashboard. Select the websites the key should access, create the key, and save it securely.
Create and manage API keys in your organization settings
Run the following from your terminal:
```bash theme={null}
curl https://api.athenahq.ai/api/v1/websites \
-H "x-api-key: YOUR_API_KEY"
```
Copy the `id` of the website you want to pull into Power BI or Fabric.
* **Power BI Desktop:** Home → Get data → Blank query → Advanced editor.
* **Microsoft Fabric:** Workspace → New → Dataflow Gen2 → Get data → Blank query → Advanced editor.
Paste the M snippet below, replacing `YOUR_API_KEY`, `YOUR_WEBSITE_ID`, and the date range. `start_date` / `end_date` accept ISO-8601 date-time strings (UTC).
```m theme={null}
let
ApiKey = "YOUR_API_KEY",
Website = "YOUR_WEBSITE_ID",
// Adjust to your reporting window. Format: ISO-8601 UTC.
Body = Json.FromValue([
website_id = Website,
filters = [
start_date = "2024-01-01T00:00:00.000Z",
end_date = "2024-01-31T23:59:59.999Z"
]
]),
Source = Web.Contents(
"https://api.athenahq.ai",
[
RelativePath = "/api/v1/metrics/share-of-voice/time-series",
Headers = [
#"x-api-key" = ApiKey,
#"Content-Type" = "application/json"
],
Content = Body
]
),
Json = Json.Document(Source),
Data = Json[data]
in
Data
```
For `GET` endpoints such as `/api/v1/prompts` or `/api/v1/competitors`, omit `Content` and pass parameters through `Query` instead:
```m theme={null}
let
ApiKey = "YOUR_API_KEY",
Website = "YOUR_WEBSITE_ID",
Source = Web.Contents(
"https://api.athenahq.ai",
[
RelativePath = "/api/v1/prompts",
Query = [ website_id = Website ],
Headers = [ #"x-api-key" = ApiKey ]
]
),
Json = Json.Document(Source),
Data = Json[data]
in
Data
```
Each metrics endpoint returns `{ "data": [...] }`. The share-of-voice time-series response is an array of rows keyed by date, with one record per company. Expand it like so:
```m theme={null}
let
AsTable = Table.FromList(Data, Splitter.SplitByNothing(), {"row"}),
Expanded = if List.IsEmpty(Data) then
AsTable
else
Table.ExpandRecordColumn(
AsTable,
"row",
Record.FieldNames(AsTable{0}[row])
)
in
Expanded
```
The `List.IsEmpty` guard keeps scheduled refreshes from erroring when the date range returns no rows. Adjust the expansion step to match the response shape of the endpoint you call.
When the dataset or dataflow is published, set the data source credential for `https://api.athenahq.ai` to **Anonymous**. The API key is passed through the request header rather than via Power BI's credential store, since Power BI's built-in **Web API** credential type only supports an `Authorization` header and cannot store a custom `x-api-key` header.
If your organization requires on-premises data gateways for external traffic, route the connection through the configured gateway.
## Security considerations
When the API key is embedded inside an M query, **any user with edit, build, or contributor access to the dataset, dataflow, or `.pbix` file can open Power Query and read the key**. Storing the key as a Power BI Parameter has the same exposure: parameters are visible to editors. Treat the key as shared credential material and apply the safeguards below.
Recommended practices:
* **Use a dedicated, website-scoped API key for this integration.** Create a separate key from your other automation, and scope it to only the website(s) you need to report on. See [API key scoping](/api-reference/authentication#api-key-scoping). Do not reuse a broadly-scoped organization key.
* **Restrict workspace access.** Limit edit / build / contributor permissions on the Power BI workspace, dataset, dataflow, and source `.pbix` to the smallest set of trusted users. Viewers in Power BI Service cannot read M source, but anyone with access to the `.pbix` file can open it in Desktop and read it.
* **Rotate on suspected exposure.** If the workspace membership changes, a `.pbix` is shared externally, or you suspect leakage, rotate the key from the [API Keys page](https://app.athenahq.ai/organization?tab=api).
* **Avoid committing `.pbix` files containing the key to source control.** Strip the key (or use a parameter overridden in the service) before committing.
Higher-assurance alternatives (for teams with strict secret-handling requirements):
* **Run a thin proxy you control.** Host a small endpoint (Azure Function, Cloud Function, internal service) that injects the AthenaHQ API key from a secure store before forwarding the request. The proxy itself **must** require its own authentication (e.g. an Entra ID / Microsoft account, a per-caller token, mTLS, or be reachable only from an internal network or via the Power BI on-premises data gateway). If the proxy is left anonymous on the public internet, anyone who learns its URL can call AthenaHQ on your behalf, exfiltrate your data, and burn through your quota. The key never lives in the M query, but it inherits whatever access controls you put in front of the proxy.
* **Build a Power BI custom connector (`.mez`).** Custom connectors can use Power BI's credential store for arbitrary headers, keeping the key out of report source. This requires connector development and admin distribution.
## Endpoints
Any endpoint from the [API reference](/api-reference/introduction) can be called from Power Query. Common starting points:
| Endpoint | Method | Purpose |
| -------------------------------------------- | ------ | ------------------------------------------------- |
| `/api/v1/metrics/share-of-voice/time-series` | POST | Daily share of voice across brand and competitors |
| `/api/v1/metrics/mention-rate/time-series` | POST | Mention rate across LLM responses over time |
| `/api/v1/metrics/citation-rate/time-series` | POST | Citation rate over time |
| `/api/v1/metrics/position/time-series` | POST | Average response position over time |
| `/api/v1/prompts` | GET | List tracked prompts |
| `/api/v1/competitors` | GET | List configured competitors |
Each metrics endpoint also has a `/cumulative` variant that returns a single rolled-up value for the date range. Use the POST snippet for metrics endpoints and the GET snippet for `prompts` / `competitors`.
## Authentication
All requests use the `x-api-key` header. See [Authentication](/api-reference/authentication) for full details, including API key scoping.
## Rate limits
API requests are subject to the limits documented on the [Rate limits](/api-reference/rate-limits) page. Power BI scheduled refreshes count against the same quota, so stagger refreshes if you connect many reports.
## Troubleshooting
* **`401 Unauthorized`**: The API key is missing, revoked, or not scoped to the requested `website_id`.
* **Credentials prompt loops in Power BI Service**: Confirm the data source credential is set to **Anonymous** for `https://api.athenahq.ai`. Power BI cannot store the `x-api-key` header itself, so it must live inside the M query.
* **`Web.Contents` dynamic URL warning**: Keep the base URL hard-coded and pass dynamic parts through `RelativePath` and `Query` options. The snippet above already follows this pattern.
* **`405 Method Not Allowed`**: Calling a `GET` endpoint (e.g. `/api/v1/prompts`) with `Content` set forces a POST and is rejected. Use the `GET` variant of the snippet.
# Rate Limits
Source: https://docs.athenahq.ai/api-reference/rate-limits
API rate limits and availability
## Rate Limits
The AthenaHQ API enforces the following rate limits:
* **60 requests per minute** per organization
* **No limit** on total number of requests
Rate limits are enforced on a per-organization basis. All API keys within the same organization share this limit. If you exceed the rate limit, subsequent requests will be rejected until the rate limit window resets.
## Response Headers
All authenticated API responses include rate limit headers:
| Header | Description |
| ------------------------ | --------------------------------------------------- |
| `x-rate-limit-limit` | Maximum requests allowed per minute (60) |
| `x-rate-limit-remaining` | Requests remaining in the current window |
| `x-rate-limit-reset` | Unix timestamp (seconds) when the rate limit resets |
When you exceed the rate limit (429 response), an additional header is included:
| Header | Description |
| ------------- | ------------------------------- |
| `retry-after` | Seconds to wait before retrying |
## API Availability
The AthenaHQ API is available exclusively for Enterprise accounts as an add-on feature. Contact your account manager to enable API access for your organization.
# Get SEO recommendation job
Source: https://docs.athenahq.ai/api-reference/seo-recommendations/get-seo-recommendation-job
/api-reference/openapi.json get /api/v1/seo/recommendations/{job_id}
Read a saved job with website content view access (viewer or higher). Results can contain evidence from submitted drafts. A completed result contains source-grounded recommendations, source_digest, token usage and warnings. Dollar cost is explicitly unavailable. Pending jobs wait for worker capacity; queued time does not expire an analysis. A failed worker returns a structured error; submit a new request_id to retry. Poll a bounded subset of jobs and back off while status remains pending; polling shares the organization-wide API request budget.
# Submit SEO recommendations
Source: https://docs.athenahq.ai/api-reference/seo-recommendations/submit-seo-recommendations
/api-reference/openapi.json post /api/v1/seo/recommendations
Submit one draft or public HTTPS page for asynchronous SEO and AI-search recommendations. The website's organization must have the seo_recommendations entitlement in Autumn, and the caller must have website content administration access. Missing entitlement returns 403; an unavailable entitlement check returns 500 without creating a job. Queued work is checked again before analysis. Reuse request_id with identical input for retries; changed input returns 409. A website may have 1,000 outstanding jobs, with up to four active analyses and 16 across all websites. The website submit ceiling is 120 requests/minute, subject to the organization-wide API budget (default 60 requests/minute shared by submissions, polling and other API calls). Honor Retry-After on 429. Pace submissions and reserve request budget for polling a bounded subset of jobs; do not poll an entire backlog every poll_after_seconds. Polling never starts another analysis.
# List Source Pages (per URL)
Source: https://docs.athenahq.ai/api-reference/sources/list-source-pages-per-url
/api-reference/openapi.json post /api/v1/source-pages
Returns individual cited URLs for a website with citation, mention, and impression metrics — one row per `normalized_url`. Each row also includes a `daily_mentions` sparkline (citation percentage per day across the date range) and the same source-type classification as [POST /api/v1/sources](/api-reference/sources/list-sources).
Use this when you need URL-level resolution (e.g. drill into which specific articles on a partner domain drove citations). For the root-domain rollup, use [POST /api/v1/sources](/api-reference/sources/list-sources).
# List Sources (by root domain)
Source: https://docs.athenahq.ai/api-reference/sources/list-sources-by-root-domain
/api-reference/openapi.json post /api/v1/sources
Returns the top cited sources for a website, grouped by root domain. Each row carries citation, mention, brand-mention, and impression metrics for the requested date range, plus a `default_source_type` classification (`owned` / `competitor` / `partner` / `third_party`).
Companion to [POST /api/v1/source-pages](/api-reference/sources/list-source-pages), which returns the same data grouped per URL (one row per cited page) instead of per root domain.
# Single Sign-On (SSO)
Source: https://docs.athenahq.ai/api-reference/sso
Configure SAML or OIDC single sign-on for your AthenaHQ organization
Single sign-on is available on AthenaHQ **Enterprise** plans.
AthenaHQ supports SAML 2.0 and OIDC and works with any standards-compliant identity provider.
## User provisioning (SCIM 2.0)
AthenaHQ exposes a SCIM 2.0 endpoint for automated user provisioning and deprovisioning from your identity provider:
* **Base URL:** `https://app.athenahq.ai/api/scim/v2`
* **Authentication:** OAuth bearer token. Generate the token from **Settings → General** in the AthenaHQ dashboard.
* **Supported operations:** user create, read, update (PUT and PATCH), and deprovision. Filter is supported (max 100 results per page).
* **Out of scope today:** group provisioning, bulk operations, and sort are not implemented. AthenaHQ does not use passwords, so SCIM password change is not applicable. If you need any of the unsupported operations, mention it when you contact support.
Configure the SCIM endpoint and bearer token in your IdP's provisioning settings to keep AthenaHQ membership in sync with your directory.
## Request setup
To enable SSO for your organization, email [support@athenahq.ai](mailto:support@athenahq.ai) with:
* Your AthenaHQ organization name
* The identity provider you want to connect and the protocol you plan to use (SAML or OIDC)
* The email domain(s) your users sign in with
* A primary technical contact for the rollout
Our team will reply with the AthenaHQ-side configuration for your chosen protocol:
* **SAML connections:** ACS URL, entity ID, and signing certificate so you can register AthenaHQ as a service provider in your IdP. You then send back your IdP's SAML metadata (or sign-in URL + signing certificate).
* **OIDC connections:** the redirect URI and required scopes so you can create an OIDC client in your IdP. You then send back the `client_id` and `client_secret` issued by your IdP.
Any client secret or signing certificate must be shared through a secure channel (e.g. 1Password share, encrypted file, or another agreed secret-handling tool); do not paste secrets into plain email or chat.
Email [support@athenahq.ai](mailto:support@athenahq.ai) to start SSO onboarding
SSO is an Enterprise-tier feature. If you are not on an Enterprise plan, contact your AthenaHQ account team about upgrading.
# Bulk Invite to Websites or Groups
Source: https://docs.athenahq.ai/api-reference/team-management/bulk-invite-to-websites-or-groups
/api-reference/openapi.json post /api/v1/invites/bulk
Invites a user to multiple websites OR multiple groups in a single request. Provide exactly one of `website_ids` or `group_ids` — the two are mutually exclusive. Each target is processed independently, so some may succeed while others fail (e.g., if the user is already a member). In 'email' mode a single consolidated invitation email is sent. Group invites require a global API key.
# Create Custom Role
Source: https://docs.athenahq.ai/api-reference/team-management/create-custom-role
/api-reference/openapi.json post /api/v1/roles
Creates a custom role with a per-category permission matrix. Custom roles are available on the Enterprise plan. Every category is at least 'view' — omitted categories default to 'view'. The role name must be unique in your organization and must not collide with a system role name; the permission matrix must not duplicate an existing role's. Requires a global API key.
# Create Invite
Source: https://docs.athenahq.ai/api-reference/team-management/create-invite
/api-reference/openapi.json post /api/v1/invites
Invites a user to your organization, a specific website, or a group. Use `invite_method: "direct"` to add the user immediately without sending any email — if the email has no existing account, a new user account is created automatically. Use `invite_method: "email"` to create a pending invite and send an invitation email that the recipient must accept. Group invites require a global API key.
# Delete Custom Role
Source: https://docs.athenahq.ai/api-reference/team-management/delete-custom-role
/api-reference/openapi.json delete /api/v1/roles/{role_id}
Deletes a custom role. System roles cannot be deleted, and a role that is still assigned to members or pending invites (or set as a default role) cannot be deleted. Requires a global API key.
# Get Role
Source: https://docs.athenahq.ai/api-reference/team-management/get-role
/api-reference/openapi.json get /api/v1/roles/{role_id}
Returns a single role — a system role or one of your organization's custom roles — with its resolved permission matrix. Requires a global API key.
# List Group Members
Source: https://docs.athenahq.ai/api-reference/team-management/list-group-members
/api-reference/openapi.json get /api/v1/groups/{group_id}/members
Returns all users with access to a group. By default, the response merges **organization members** (implicit access to every group in the org) and users with explicit **group-member rows**, tagging each entry with an `access_type` field (`organization` or `group`). If a user has both an org membership and a `group_members` row, the merged view returns them once as `access_type: "organization"` (org precedence).
Use the `access_type` query parameter to filter: `?access_type=group` returns the raw `group_members` rows (including users who also have org access), and `?access_type=organization` returns only the org's implicit members. Requires a global API key.
# List Organization Members
Source: https://docs.athenahq.ai/api-reference/team-management/list-organization-members
/api-reference/openapi.json get /api/v1/organizations/members
Returns all members of your organization, including user details (email, first/last name) and their organization role. Requires a global API key.
# List Roles
Source: https://docs.athenahq.ai/api-reference/team-management/list-roles
/api-reference/openapi.json get /api/v1/roles
Returns all roles available in your organization: the built-in system roles (Admin, Editor, Viewer, Billing) plus your organization's custom roles, each with its resolved permission matrix. Use a role's `role_id` to assign it via invites or member role updates. Requires a global API key.
# List User Websites
Source: https://docs.athenahq.ai/api-reference/team-management/list-user-websites
/api-reference/openapi.json get /api/v1/users/{user_id}/websites
Returns the websites that a user has access to within your organization, either via organization membership (implicit access to all websites in the org) or via explicit website membership. Organization membership takes precedence — if the user is an org member, all non-paused websites in your organization are returned with `access_type: "organization"`. Otherwise, only websites the user has an explicit `website_members` row for are returned. Returns `404` if the `user_id` does not match any AthenaHQ user. Returns `200` with an empty `websites` array if the user exists but has no access within your organization (this intentionally does not distinguish "user is in a different org" from "user is in your org but has no access"). Requires a global API key. **Partner integrations** additionally receive an `external_id` field on each website (`null` when no mapping exists); direct-customer responses omit the field.
# List Website Members
Source: https://docs.athenahq.ai/api-reference/team-management/list-website-members
/api-reference/openapi.json get /api/v1/websites/{website_id}/members
Returns all users with access to a website — both organization members (implicit access to every website in the org) and users with explicit website-member rows. Each entry includes an `access_type` field (`organization` or `website`) so you can tell them apart. If a user has both an org membership and a stray website-member row, they appear once with `access_type: "organization"`. Accepts a global API key, or a website-scoped key if the website is in the key's allowlist.
# Look Up User By Email
Source: https://docs.athenahq.ai/api-reference/team-management/look-up-user-by-email
/api-reference/openapi.json post /api/v1/users/by-email
Resolves a user's `user_id` from their email address, scoped to your organization. The email is sent in the request body (not the URL) so it never lands in request logs or analytics. Returns the user only when they belong to your organization — either as an organization member (`access_type: "organization"`) or as an explicit member of at least one non-paused website in your organization (`access_type: "website"`). Any other case, including an email that belongs to a user in a different organization, returns `404` with the same body as a truly unknown email, so the endpoint cannot be used to enumerate accounts across tenants. Requires a global API key. Use the returned `user_id` with the member-management endpoints (e.g. list a user's websites or remove website access) without a discovery round-trip.
# Remove Group Member Access
Source: https://docs.athenahq.ai/api-reference/team-management/remove-group-member-access
/api-reference/openapi.json delete /api/v1/groups/{group_id}/members/{user_id}
Removes a user's direct group membership and their explicit website memberships for websites currently in the group. Both sets of rows are removed atomically. The request is idempotent: a retry, or a well-formed user ID with no matching membership rows, returns `200` with `group_membership_removed: false` and `website_memberships_removed: 0`.
Organization membership, membership in other groups, and website membership outside this group are preserved. If another group grants access to one of the same websites, that effective access remains through the other group even though the user's explicit website membership row is removed. Organization members return `409` because their organization-derived access would remain. Requires a global API key, and the API key's own user cannot be removed. The endpoint accepts no request body.
# Remove Organization Member
Source: https://docs.athenahq.ai/api-reference/team-management/remove-organization-member
/api-reference/openapi.json delete /api/v1/organizations/members/{user_id}
Removes a user from your organization. Also cleans up any stray website_members rows for that user across all websites in the organization within a single transaction. Requires a global API key. Cannot remove the API key's owning user, the organization owner, or the last remaining admin.
# Remove User From Websites
Source: https://docs.athenahq.ai/api-reference/team-management/remove-user-from-websites
/api-reference/openapi.json delete /api/v1/users/{user_id}/websites
Batch-removes a user's explicit website memberships within your organization. Pass the website IDs as a comma-separated list in the `website_ids` query parameter (at most 100). Requires a global API key. Idempotent: websites where the user has no explicit membership are reported with status `not_a_member` rather than failing the request, so re-calling is safe. Organization-level access is not affected — this only removes explicit `website_members` rows.
# Remove Website Member
Source: https://docs.athenahq.ai/api-reference/team-management/remove-website-member
/api-reference/openapi.json delete /api/v1/websites/{website_id}/members/{user_id}
Removes a user's explicit membership from a website. Accepts a global API key, or a website-scoped key if the website is included in the key's allowlist. Cannot be used to remove the API key's owning user or the organization owner.
# Revoke Organization Invite
Source: https://docs.athenahq.ai/api-reference/team-management/revoke-organization-invite
/api-reference/openapi.json delete /api/v1/invites/org/{invite_id}
Soft-revokes a **pending** organization invite by setting its status to `revoked`. The invite row is preserved for audit purposes. Returns 409 if the invite is in any other state (already accepted, declined, expired, or revoked), since revoking an accepted invite would leave a misleading audit trail while the underlying membership row remains untouched. To remove an already-accepted member, use `DELETE /api/v1/organizations/members/{user_id}` instead. Requires a global API key.
# Revoke Website Invite
Source: https://docs.athenahq.ai/api-reference/team-management/revoke-website-invite
/api-reference/openapi.json delete /api/v1/invites/website/{invite_id}
Soft-revokes a **pending** website invite by setting its status to `revoked`. Accepts a global API key, or a website-scoped key if the invite's target website is included in the key's allowlist. Returns 409 if the invite is in any other state. To remove an already-accepted member, use `DELETE /api/v1/websites/{website_id}/members/{user_id}` instead.
# Update Custom Role
Source: https://docs.athenahq.ai/api-reference/team-management/update-custom-role
/api-reference/openapi.json patch /api/v1/roles/{role_id}
Updates a custom role's permission matrix. Every category is at least 'view' — omitted categories default to 'view'. System roles cannot be edited. The new matrix must not duplicate an existing role's. Requires a global API key.
# Update Group Member Role
Source: https://docs.athenahq.ai/api-reference/team-management/update-group-member-role
/api-reference/openapi.json patch /api/v1/groups/{group_id}/members/{user_id}
Updates the role of a user who was explicitly added to a group (a `group_members` row, shown as `access_type: "group"` by `GET /api/v1/groups/{group_id}/members`). Accepts either the coarse `role` (admin/viewer) or a `role_id`: a system role or one of your organization's custom roles (see `GET /api/v1/roles`). Provide exactly one. Requires a global API key.
Organization members are out of scope: their access to every group in the org comes from their organization role, so a group-level write would not change what they can do. Targeting one returns `409`; use `PATCH /api/v1/organizations/members/{user_id}` instead. The API key's own user cannot be modified. There is no last-admin restriction at group scope: a group's only admin can be demoted, since organization admins retain admin access to every group in the organization.
**Roles other than `admin` and `viewer` are honored for access but are not yet rendered in the dashboard.** A `role_id` such as Editor or Billing Manager grants that role's real permissions on every website in the group, but the dashboard's group member list currently collapses any non-admin role to "Viewer". Prefer `admin` / `viewer` at group scope when a customer administrator also needs to see the assigned role.
# Update Organization Member Role
Source: https://docs.athenahq.ai/api-reference/team-management/update-organization-member-role
/api-reference/openapi.json patch /api/v1/organizations/members/{user_id}
Updates an organization member's role. Accepts either the coarse `role` (admin/viewer) or a `role_id` — a system role or one of your organization's custom roles (see `GET /api/v1/roles`); provide exactly one. Requires a global API key. Cannot modify the API key's owning user or the organization owner. Cannot demote the last remaining admin.
# Update Website Member Role
Source: https://docs.athenahq.ai/api-reference/team-management/update-website-member-role
/api-reference/openapi.json patch /api/v1/websites/{website_id}/members/{user_id}
Updates a website member's role. Accepts a global API key, or a website-scoped key if the website is included in the key's allowlist. Cannot be used to modify the API key's owning user or the organization owner.
# Brand Profile
Source: https://docs.athenahq.ai/brand-profile
Set up the brand details Athena uses for tracking, scoring, and content generation
Your Brand Profile is the foundation of everything Athena does for your brand. It's where you tell Athena who you are - your name, description, voice, and the traits that define how you want to show up in AI-generated content. The more completely you fill it out, the more accurately Athena can track, score, and generate content on your behalf.
To get there: navigate to **Brand Profile** in the left sidebar.
***
## Overview of the tabs
The Brand Profile has five tabs. You don't need to complete them all at once, but each one unlocks a different layer of Athena's capabilities.
| Tab | What it covers |
| :------------- | :------------------------------------------------------------------ |
| **General** | Your brand's name, description, logo, language, and location |
| **Attributes** | The traits that define your brand's voice (what you are and aren't) |
| **Rules** | Global content rules applied across all content generation |
| **Brand Kits** | Named brand voice guidelines used when generating content |
| **Technical** | LLMs.txt, sitemap, schema, and AI crawler accessibility |
***
## General tab
This is the first thing to fill out. It tells Athena the basics about your brand.
### Fields
**Brand Name** Your company or product name, exactly as you want it used. This is injected into AI content generation prompts as identity context - Athena references this name when generating articles, briefs, Ask Athena columns, and optimization rewrites.
**Brand Description** A short description of your brand, positioning, and what you offer. Write it as you'd explain your company to someone new. This is passed directly into content generation as context, so the more precise it is, the more on-target the output.
**Website Logo** Upload a square image (max 2 MB). Drag and drop directly onto the upload area or click to browse. The logo appears throughout the Athena dashboard.
**Base Location** The primary country your brand operates from. This is used when Athena targets keywords and prompts by geography - so if you're a US-based company, your keyword suggestions, prompt volume data, and content targeting will default to the US market.
**Default Language** The language your content should be written in. Defaults to English. This is used as the language setting when Athena generates and targets content.
### How to save
Make any changes, then click **Save changes** in the bottom right of the tab. The button only activates when there are unsaved edits.
***
## Attributes tab
Attributes define what your brand sounds like and what it avoids. Athena uses these to score AI responses: when an AI model's response about your brand reflects your positive attributes, that's a good signal. When it reflects your negative ones, that's a gap.
### How attributes work downstream
Every time Athena fetches and analyzes AI responses about your brand (across models like ChatGPT, Perplexity, Gemini, etc.), it checks those responses against your attribute list. Responses that align with your positive attributes push sentiment scores up; responses that reflect negative attributes push them down. This is how Athena calculates the **sentiment score** you see in your dashboard.
When you add, edit, or delete attributes, a **backfill bar** appears at the bottom of the screen. This lets you re-score your historical AI responses against the updated attribute list - so your sentiment data stays accurate over time.
### Attribute types
* **Positive** - Traits your brand wants to be associated with (e.g., "innovative," "trustworthy," "enterprise-grade")
* **Negative** - Traits your brand actively wants to avoid (e.g., "expensive," "complicated," "slow")
### How to add an attribute
1. Go to the **Attributes** tab
2. Click **Create new**
3. Enter a name (e.g., "professional," "easy to use")
4. Select **Positive** or **Negative** for the sentiment
5. Click **Add**
The attribute appears in your list immediately and is active by default.
### How to delete an attribute
Click the **...** (more options) icon on any attribute row and select **Delete**.
### Running a backfill after attribute changes
After adding, editing, or deleting attributes, the backfill bar appears at the bottom of the screen. To re-score your historical responses:
1. Choose a date range (defaults to the last 30 days; presets available up to 6 months)
2. Review the pending changes by clicking **View Changes** if needed
3. Click **Backfill** - the number in the badge shows the credit cost (1 credit per 100 responses)
4. Athena will reanalyze responses in the background. This may take a few hours for large date ranges.
If you don't want to backfill, you can dismiss individual changes by clicking the skip icon in the View Changes dialog, or dismiss all at once.
***
## Rules tab
**Note:** The Rules tab is only visible if your account has the content memory feature enabled.
Rules are persistent instructions that apply across all content generation. Think of them as standing editorial guidelines - things like "always use Oxford commas," "never refer to the product as a 'tool'," or "write in second person."
Rules are organized by category:
* **Style** - Voice and prose style guidelines
* **Formatting** - How content should be structured or formatted
* **Terminology** - Specific words or phrases to use or avoid
* **Tone** - Tone of voice instructions
* **Structure** - How pieces of content should be organized
* **Other** - Catch-all for anything that doesn't fit above
### How rules affect content
Every time Athena generates or rewrites content (articles, briefs, optimization rewrites), active rules are included in the generation prompt. Rules can be toggled on or off individually - a rule is only applied if its status toggle is on.
### How to add a rule
1. Go to the **Rules** tab
2. Click **Create New**
3. Write the rule text (e.g., "Do not use the word 'leverage' as a verb")
4. Select a category
5. Click Save
Rules can also be created automatically from your edits in the content editor - when Athena detects a pattern in how you iterate on drafts, it may suggest saving that pattern as a rule.
### How to edit or delete a rule
Click the **...** menu on any rule row to edit or delete it. You can also click directly on the rule text to open the edit dialog.
### Toggling rules on/off
Use the toggle in the **Status** column to activate or deactivate any rule without deleting it. Inactive rules are shown in muted text and are not included in content generation.
***
## Brand Kits tab
Brand kits are named sets of brand voice guidelines. When Athena generates content - articles, briefs, social posts, optimization rewrites - it uses your brand kit's instructions to match your tone and style. You can create multiple kits for different contexts (e.g., one for blog posts, one for social media, one for executive communications) and set one as the default.
### How brand kits affect content
The **default** brand kit's instructions are passed into every content generation prompt. When generating a brief or article, you can also select a specific kit if you want something other than the default. If no kit exists, Athena generates content without brand voice instructions.
### How to create a brand kit
1. Go to the **Brand Kits** tab
2. Click **Create New**
3. In the **Setup** step:
* Enter a **Name** for the kit (e.g., "Blog Posts," "Social Media," "Corporate")
* Enter your **Blog or newsroom URL** - Athena will crawl this to auto-generate brand guidelines based on your existing published content
* Optionally upload **Documents** (up to 5 files, PDF or similar) categorized as either **Rules & Guidelines** or **Brand Context**
4. In the **Customize** step:
* Review and edit the auto-generated guidelines in the editor
* The editor supports rich text; guidelines are stored as structured instructions
5. Click **Save** to finish
The kit will show as **In progress** while Athena generates the guidelines. Once complete, it appears as active in the list.
### How to edit a brand kit
Click on any kit row (or the **Edit** option in the ... menu) to reopen the Customize step. Make your changes and save.
### Setting a default kit
Each kit has a **Set as default** button. Only one kit can be the default at a time. The default kit is used automatically unless you explicitly choose a different kit during content generation. The default kit is marked with a "Default" badge.
### Deleting a brand kit
Open the ... menu on any non-default kit and select **Delete**. The default kit cannot be deleted directly - set another kit as default first, then delete the old one.
***
## Technical tab
The Technical tab gives you visibility into how AI crawlers and search engines see your site. None of these settings affect Athena's content scoring or generation directly - they're tools for improving your site's AI accessibility and structured data.
### LLMs.txt
Think of this as `robots.txt` but for large language models. It tells AI models what your site is about and how to represent your brand. If you haven't generated one yet:
1. Click **Generate llms.txt**
2. Athena will generate the file using AI based on your site content
3. Once generated, click **Edit llms.txt** to review and customize it
### Sitemap
A sitemap lists all your website's pages so search engines and AI crawlers can find and index your content. Use this section to validate that your sitemap is configured correctly. Without a sitemap, pages may be missed by crawlers entirely.
### Schema
Validates the Schema.org JSON-LD structured data on your website. Schema markup helps AI crawlers and search engines understand your content at a deeper level. Use this to check for errors or missing structured data.
### AI Accessibility
Click **Check AI accessibility** to run a check on whether major AI models and crawlers (like GPTBot, ClaudeBot, PerplexityBot, etc.) can access your site's content. If key crawlers are blocked, they can't learn about your brand - which directly affects how AI models describe you.
***
## Quick-start checklist
If you're setting up your Brand Profile for the first time, work through these steps in order:
1. **General tab** - Fill in your brand name, description, and upload your logo. Set your base location and default language.
2. **Attributes tab** - Add at least 5-10 positive attributes and 3-5 negative attributes that reflect your brand voice and what you want to avoid.
3. **Brand Kits tab** - Create at least one brand kit. Point Athena at your blog or newsroom URL and let it auto-generate your first set of guidelines. Review and edit before saving.
4. **Rules tab** *(if available)* - Add any standing editorial rules that should apply to all generated content.
5. **Technical tab** - Generate your LLMs.txt and check your AI accessibility to make sure crawlers can reach your site.
***
## Permissions
Only **admin** members of your organization can edit Brand Profile settings. Members with a **viewer** role can see the profile but cannot make changes.
# Discover
Source: https://docs.athenahq.ai/discover
Run prompt discovery across your website, search data, social signals, and competitor gaps to find the prompts worth tracking
*Find the prompts your market is using - and the gaps your brand isn't covering yet - from one discovery surface.*
## Overview
Discover is Athena's prompt discovery engine, available as the **Discover** tab on the Prompts page. It scans real data sources - your website, Google Search Console, social conversations, and your keyword landscape - then produces a structured, ranked set of suggested prompts you can review and start tracking. It replaces the earlier Planner and Universe tabs; old links redirect here automatically.
*Enterprise plan only. The Discover tab shows a lock icon if your workspace doesn't have access.*
## What it does
**Maps your category** - Analyzes your website, segments, and products, plus the search terms and community discussions in your space.
**Generates real prompts** - Translates raw search data and audience conversations into prompts a real user would type into a search engine or AI assistant.
**Isolates the gaps** - Compares everything against the prompts you already monitor. Suggestions you already cover (previously accepted suggestions, exact matches, and Keyword gaps prompts at 85%+ similarity) are moved to an **Already tracked** section so you only review opportunities that add value.
**Makes it actionable** - Select the suggestions you want and click **Start tracking** to add them to your monitored prompt set.
## Sources
When you start a run, you pick which sources to scan:
* **Website analysis** - market analysis from your website, segments, and products.
* **Search Console** - clusters your Google Search Console keywords into prompts grounded in real search data. *Requires GSC to be connected in Settings > Integrations; otherwise the source appears disabled with a connect link.*
* **Social** - Reddit threads, YouTube comments, and videos in your category.
* **Keyword gaps** - prompts where AI cites competitors but not you, built from your keyword landscape.
* **Custom instructions** - guide discovery with your own topics, products, and tone. Opt-in; requires a short written brief describing what the generated prompts should focus on.
## Running a discovery
1. Go to the **Prompts** page and click the **Discover** tab.
2. Click **Run discovery**.
3. Name the run, choose a country and language, and check the sources you want to scan.
4. Click **Run discovery**. Sources run in the background - allow several minutes to an hour depending on which sources you selected.
5. Open the run from the history list at any time. The detail page shows live progress, and suggestions appear as results come in (Keyword gaps results arrive independently of the other sources), so you don't need to wait for the whole run.
## Reviewing results
Suggestions are grouped by Topic in a spreadsheet-style table with columns for:
* **Source** - which source produced the prompt
* **Funnel** - TOFU (awareness), MOFU (consideration), or BOFU (decision)
* **Intent** - Informational, Commercial, Transactional, or Navigational
* **Type** - Head, Mid tail, or Long tail
* **Volume** - estimated monthly search volume
* **Value** - estimated keyword value (CPC)
Signal chips (such as *Competitor Gap* and *Social Signal*) appear above the table when the run found prompts carrying those signals - use them to surface the strongest opportunities first. Hover the info icon on any row to see why the AI suggested that prompt.
Select prompts individually or by topic, then click **Start tracking (N)**. Athena checks for duplicates and shows a count of new vs. already-tracked selections before confirming. You can also export the currently filtered view as a CSV.
## When to use it
**You're setting up tracking for a new brand or category** - Run discovery to seed your monitored prompt set with a defensible, data-backed starting list rather than guessing.
**You suspect competitors are pulling ahead in topics you're not tracking** - The Keyword gaps source surfaces prompts where AI cites competitors but not you.
**You want to expand into a new product line or audience** - Run a new discovery with custom instructions scoped to the new area before you commit to a tracking plan.
**You're filling gaps in an existing prompt set** - Re-run discovery periodically - every few months, or when you expand into a new product area - rather than just once at setup.
# Getting Started
Source: https://docs.athenahq.ai/getting-started/setup
Set up AthenaHQ and start tracking your brand across AI search
Set up AthenaHQ and start tracking your brand across AI search in just a few
steps. The activation flow takes about 15-20 minutes and is designed to be
self-serve. Once you complete these steps, your workspace begins collecting
data and surfacing insights in your dashboard.
## Prerequisites
Before you begin, make sure you have:
* Admin permissions in your workspace so you can invite teammates and configure
integrations
* Credentials for any tools you want to connect, such as Google Search Console,
Google Analytics 4, Shopify, Webflow, or Looker Studio
* A working list of your competitors
## What's already running in your account
When you log in to AthenaHQ, the onboarding wizard sets up the foundation for
you:
* **Your brand profile**: auto-extracted from your website, including your
industry, name, description, and logo. You can edit it on the Brand Profile
page.
* **A competitor list**: Athena analyzes your site and proposes competitors.
Each competitor has identifiers, which are text patterns Athena uses to
detect mentions in AI responses, and domains, which are URL patterns used to
attribute citations. You can refine both on the Competitors page.
* **About 10 starter prompts**: auto-generated based on your industry and
tagged as Branded or Non-Branded. They live on the Prompts page.
* **A streaming schedule**: the AI engines you selected, running Monday,
Wednesday, and Friday by default. To view and adjust it, click **Schedule** in
the left sidebar.
These are smart defaults to refine, not final settings you need to keep. Your
job now is to review what Athena built, sharpen it, and let it run.
## Onboarding
Complete the six steps below in order. You can return to any step later from
the Settings menu in your dashboard.
Bring your team into the workspace so everyone has visibility into your AI
search performance.
1. From the left sidebar, click **+ Invite People**.
2. Enter the email address of each teammate you want to add.
3. Assign a role, either Admin or Viewer, and click **Send Invite**.
Integrations let AthenaHQ pull in keyword, traffic, and revenue context
from the tools you already use, which makes your prompt tracking and
reporting richer.
1. In **Settings**, navigate to the **Integrations** tab.
2. Connect any integrations that apply to your business:
* **Google Search Console**: surfaces your real-world search keywords to
help generate prompts.
* **Google Analytics 4**: ties AI search visibility back to site traffic.
* **Shopify, Webflow, and WordPress**: publish content directly to your
content management system.
* **Looker Studio**: pipes Athena data into your custom reports.
3. Follow the in-app authentication flow for each integration. Most take
less than a minute.
You do not need to connect every integration to get started. Google Search
Console is the most valuable for new users because it powers prompt
suggestions in Step 5.
Your Brand Profile tells Athena who you are so it can accurately attribute
mentions to your brand.
1. Open the Brand Profile section from the left sidebar.
2. Confirm your Brand Description. Review the auto-generated description
and edit it so it accurately reflects what your company does. A clear,
specific description improves the quality of mention detection.
3. Add at least one Brand Kit. A Brand Kit is a centralized collection of
your company's approved assets and guidelines. It often includes:
* **Brand voice and tone**: a short guide to how your brand should
sound.
* **Vocabulary and lexicon**: approved terminology, brand taglines,
commonly used phrases, and words that should be avoided.
Brand Kit assets and guidelines are used to generate your custom content
in the Content Hub.
Tracking competitors lets you benchmark your share of voice in AI-generated
answers.
1. Navigate to the **Competitors** tab.
2. Refine identifiers for your own brand. List every name, product line,
abbreviation, and alternate spelling for your brand.
3. Build an exhaustive competitor list. Add every competitor across all of
your product lines and service offerings. The more complete the list, the
more meaningful your share-of-voice metrics will be.
4. Add identifiers for each competitor. List every name, product line,
abbreviation, and alternate spelling for each competitor.
Remember:
* Include product line names separately when relevant, such as a parent
company and its specific product names.
* Think about every way a competitor might be referenced in an AI response.
Prompts are the questions Athena runs against AI engines on your behalf. A
strong, representative prompt set is the single biggest driver of useful
insights.
You have two ways to build your starting set.
**Option 1: Upload a CSV**
1. Go to the Prompts tab and click **+ Add More**.
2. Select **Add Prompts**, then navigate to the CSV tab.
3. Use the template to format your prompt list and drag your CSV to upload.
**Option 2: Use Discover (Enterprise-only)**
1. Go to the Prompts tab and click **Discover**.
2. Click **Run discovery**.
3. Check the sources you want to scan (website analysis, Search Console,
social, keyword gaps) and click **Run discovery**.
4. When results come in, select the prompts you want and click
**Start tracking**.
Aim for 50-100 prompts to start. You want enough coverage to see patterns,
but a focused set is easier to act on than hundreds of low-signal prompts.
The final step turns tracking on. This is where Athena starts running your
prompts against the AI engines you select on a schedule you control.
1. From the left sidebar, click **Schedule**.
2. Under **Automatic runs**, make sure the schedule is on.
3. Under **Frequency**, keep **Weekly** and select the days when Athena
should run your prompts. To change from twice a week to once a week,
leave only one day selected.
4. To run less often, under **Repeat every**, choose 2, 3, or 4 weeks. You
can also select **Monthly** and choose a day of the month.
5. Pick which AI engines to track. Select the products that matter to your
audience, such as ChatGPT, Claude, Gemini, Perplexity, or Google AI
Overviews.
6. Double-check the Fan-out toggle and confirm it is selected or deselected
based on your streaming strategy.
7. Click **Save schedule**.
Saving your schedule is the most commonly missed step. Double-check that
your changes are saved before leaving the dialog.
Your workspace is now live. Initial results typically appear in your dashboard
within a few hours.
## Need help?
Our team is here to support you. Contact us at
[support@athenahq.ai](mailto:support@athenahq.ai).
## Troubleshooting
If something does not look right after activation, run through this checklist:
* Confirm your Brand Profile description is accurate and specific.
* Verify your brand and competitor identifiers include every relevant variation
you want counted.
* Make sure you saved your changes in the Schedule dialog.
* Check that the AI engines and days you selected match your tracking goals.
* Allow a few hours after first activation for data to populate.
* Still stuck? Reach out to
[support@athenahq.ai](mailto:support@athenahq.ai).
# Add Website (Onboarding Wizard)
Source: https://docs.athenahq.ai/guides/add-website
Guides a user through creating and configuring a new website (brand profile, region, competitors, prompts, GSC, and run schedule) before landing in the main app.
`app.athenahq.ai/add-website`
## Purpose
The Add Website page is the onboarding wizard that guides customers through creating and configuring a new tracked website. It walks users through providing their URL, confirming their brand details, and setting up the initial lists of competitors and prompts to track.
Whether a customer is signing up for the first time, or an existing customer is adding an additional brand to their organization's account, this flow ensures the platform has the essential context, like region, terminology, and AI models, to begin generating insights. Once the setup is complete, the platform kicks off its first analysis run and drops the user into their new dashboard.
## What's on the page
The page is split into two halves: the left panel hosts the active configuration step, and the right panel displays a decorative, animated gradient that previews the progress being made.
Depending on whether the user is brand new or an existing customer, the left panel cycles through the following steps:
**About You (First-time users only)**
Collects the user's First Name, Last Name, and their role (e.g., General, Content Marketer, SEO, Executive, PR). It may also show a "Let teammates join automatically" toggle if their email domain allows for automatic team discovery.
**Website URL**
A simple input field where the user enters the domain they want to track.
**Region**
Allows the customer to set the "Country" and "Language" that the AI should use when researching prompts.
**Review (Card Stack)**
A three-card stack that confirms the AI-generated data. Customers must review and click "Continue" on each card:
* **Brand profile:** Displays the extracted "Name", "Description", and "Industry".
* **Competitors:** A table listing the competitors Athena found for the brand.
* **Prompts:** A table of the branded and non-branded search queries Athena suggests tracking.
**Google Search Console (Optional)**
A step to securely connect the brand's Google Search Console account for deeper insights.
**Schedule**
Configuration for the automated tracking runs.
* **Models:** A grid of available AI models (ChatGPT, AI Overviews, Perplexity, Gemini, Copilot, AI Mode, Grok, Claude, DeepSeek).
* **Days:** Selectable days of the week to run the analysis.
* **Cost summary:** A breakdown showing the estimated credit cost for the "First run" and the "Estimated monthly" usage based on the selected prompts, models, and days.
### Competitors Table (Review Step)
* **Name:** The name of the competitor.
* **Domain:** The primary website URL for the competitor.
* **Identifiers:** A list of alternative names or aliases for the competitor. Includes an info icon with the tooltip: *"Different ways AI might refer to this brand, like nicknames or abbreviations."*
* **Actions:** A kebab menu (⋯) for editing or deleting the competitor.
### Prompts Table (Review Step)
* **Prompt:** The specific query text.
* **Type:** A badge indicating if the query is "Non-Branded" or "Branded". Includes an info icon with the tooltip: *"Branded prompts mention your company by name. Non-branded prompts are generic industry queries."*
* **Actions:** A kebab menu (⋯) for editing or deleting the prompt.
### Pricing Selection Popup
If an existing customer adds a new organization or website and requires a subscription, a full-screen pricing dialog appears before they can complete the flow. It offers plan tiers (Free, Starter, Enterprise), a "Monthly" / "Annual (17% off)" toggle, and options to "Sign out".
## What you can do here
* **Navigate steps:** Use the **Continue** and **Back** buttons to move through the wizard.
* **Add website URL:** Type or paste a domain; the system validates it and uses it to automatically scrape brand information in the background.
* **Edit brand details:** On the Brand Profile card, type directly into the Name and Description fields to correct the auto-generated text.
* **Add competitor:** Click **Add competitor** below the table to open a drawer where you can search for and add new competitors manually or in bulk.
* **Edit or delete competitor:** Click a row in the Competitors table, or click the **⋯** menu on a row and select **Edit** or **Delete**.
* **Manage identifiers:** Click the identifiers dropdown on a competitor or brand row to add, remove, or edit aliases. You can also toggle case-sensitivity for the identifiers here.
* **Add prompts:** Click **Add prompts** below the Prompts table to open a drawer for generating more AI suggestions, manually typing new queries, or importing a CSV.
* **Edit or delete prompt:** Click a row in the Prompts table, or use the **⋯** menu to select **Edit** or **Delete**. Editing allows you to change the prompt text and switch its Type (Branded vs. Non-Branded).
* **Connect GSC:** On the Google Search Console step, click **Connect** to open a secure Google login popup. Once connected, click **Disconnect** to remove it.
* **Select AI models:** On the Schedule step, click the model cards to toggle them on or off. Locked models on Free plans show a lock icon.
* **Set schedule days:** Click the days of the week (Sun, Mon, Tue, etc.) to toggle when automated tracking runs.
* **Save draft or exit:** Click the **X** icon in the top left to open the "Leave setup?" dialog. From there, click **Save for later** to preserve your progress and return to your dashboard, or **Delete draft** to permanently discard the setup and leave.
* **Choose a subscription plan:** If presented with the Pricing dialog, click **Subscribe now** to enter the Stripe checkout flow, **Get started** to claim free credits, or **Get in touch** to schedule a call for Enterprise plans.
## Data shown
The onboarding flow relies on live data extraction. When a user enters their Website URL, Athena visits that domain to automatically generate the brand description, identify competitors, and brainstorm relevant industry prompts. The region (country and language) is auto-detected based on the domain's extension (like `.uk` or `.de`) or the user's current location.
## Common workflows
### Setting up a new website
1. Enter the Website URL and wait a moment while the platform analyzes the domain.
2. Confirm or correct the detected Country and Language on the Region step.
3. On the Review step, verify the Brand Profile, then click Continue to review the auto-generated Competitors and Prompts.
4. Optionally connect Google Search Console.
5. Select the AI models to track and the days of the week to run them, then click Finish to complete the setup and start the first analysis.
### Adding competitors manually
1. On the Competitors review card, click **Add competitor**.
2. In the drawer, search for the competitor's URL or name.
3. Add the competitor to the list, which will automatically generate alternative identifiers for them.
### Resuming an abandoned setup
1. If a user exits the wizard via "Save for later", the website is kept as a draft.
2. Upon returning to the Add Website page for that draft, the wizard bypasses completed steps and resumes exactly where the user left off (e.g., the Review step).
## Empty, loading, and error states
* **Loading:** Full-screen animated video loaders appear during transitions, accompanied by messages like "Loading draft...", "Analyzing website...", "Saving...", or "Starting initial analysis...".
* **Empty tables:** If no prompts or competitors are found, the tables display a gray "No prompts added" placeholder or an empty list with an active "Add" button.
* **Errors:** Toasts appear for issues such as "Couldn't read your website automatically. Fill in the brand details manually..." if the automated scrape fails, or "Failed to load draft" if returning to a deleted setup.
* **Permission Blocks:** If a user without administrative access tries to create a new website, they see a message: *"You don't have permission to add a website. Ask an org admin for organization write access."*
## Linked from / links to
* **Linked from:** The main app redirect (if the user has no completed website), the "Add Website" button in the left sidebar, or the organization switcher menu.
* **Links to:** The main Olympus dashboard (upon finishing or saving a draft), the Login page (if signing out), Stripe Checkout (for plan purchases), and Cal.com (for Enterprise inquiries).
## Common support questions
**Why are some AI models locked on the schedule step?**
Free plans restrict access to certain premium models (like Grok, AI Mode, Claude, and DeepSeek). Hovering over a locked model shows the tooltip: *"Available on the Starter plan"*. The user must upgrade to select them.
**What happens if I change the website URL after I've already reviewed the competitors and prompts?**
Changing the URL on a saved draft will completely reset the brand profile, region, competitors, and prompts to match the newly entered domain. Any manual edits made for the old URL will be lost.
**How do I skip the automated schedule?**
During the Schedule step, if you deselect all days of the week, the automated schedule is turned off. The initial run will not happen automatically, and you will need to manually trigger tracking from your dashboard later.
**Why did I get an error saying I can't add a website?**
Only Organization Admins have the permission to create new websites from scratch. If a user is a Viewer, they will be blocked unless they were specifically invited to resume an existing draft by an Admin.
# ChatGPT Ads
Source: https://docs.athenahq.ai/guides/ads
Show which sponsored ads ChatGPT serves against the customer's tracked prompts, who is buying them, and daily trends.
`app.athenahq.ai/ads`
## Purpose
The ChatGPT Ads page allows you to see the sponsored ads that ChatGPT serves against your tracked prompts. It reveals which advertisers (including your tracked competitors) are buying ad placements on your highest-priority topics, what their creatives look like, and how frequently those ads appear over time.
Because generative AI engines are beginning to monetize answers with sponsored links, this page serves as an early-warning system for paid competitive threats. It helps you understand if competitors are buying their way to the top of answers where your brand organically ranks, or if you are losing visibility to paid placements.
*Note: Ad tracking began in July 2026, and only ChatGPT serves ads today.*
## What's on the page
### Page Header & Filters
* **Page Title:** Reads "ChatGPT Ads" with an info icon. The tooltip explains: *"Shows the sponsored ads ChatGPT serves alongside answers to your tracked prompts, and which advertisers are buying them."*
* **Filter Row:** Contains controls to adjust the **Date Range**, apply **Topics & Prompts** or **Prompt Tags** filters, and manage **Views** (to save your filter combinations).
### ChatGPT Ad Pressure (Hero Card)
* **ChatGPT ad pressure:** A headline percentage metric showing the share of tracked answers that contained at least one sponsored ad.
* **Metric description:** Reads *"Sponsored ads ran against \[X] of \[Y] answers to your tracked prompts."*
* **Daily trend sparkline:** A visual area chart spanning the bottom of the card. Hovering over the trendline shows a tooltip with the exact date, "Ads captured", and "Answers with ads" for that day.
* **Top advertisers on your prompts:** A mini-leaderboard showing the top 4 advertisers in the selected period, complete with their favicon, brand name, relative bar indicator, and a "You" or "Competitor" badge if applicable.
* **View answers with ads:** A drilldown button that navigates directly to the Responses page, pre-filtered to show only the answers that served ads.
### Stat Rail
Four compact tiles summarizing ad volume:
* **Ads captured:** Displays the total number of ads tracked. The tooltip explains: *"Every sponsored ad ChatGPT returned for your tracked prompts, whether or not it was displayed in the answer. The Ads shown tile counts only displayed ads."* Clicking this tile drills down to the Responses page.
* **Advertisers:** The number of distinct advertisers buying ads in this period.
* **Competitors advertising:** The number of your specifically tracked competitors found buying ads.
* **Ads shown:** The number of ads that were actually rendered for the user. Displays a subtext (e.g., *"\[X] auctioned but not shown"*). The tooltip explains: *"Each captured ad reports whether ChatGPT displayed it. Shown means the ad rendered in the answer. Auctioned but not shown means the advertiser won an ad slot for the prompt but ChatGPT did not display the ad, which still reveals who is bidding."* Clicking this tile drills down to the Responses page.
### Advertisers
This table ranks advertisers by the number of ads captured in the selected period.
* **Info tooltip:** *"Advertisers ranked by ads captured in the selected period. Tracked includes your brand and tracked competitors. Expand a row to see which prompts trigger their ads and the latest creative."*
* **Segmented Toggle:** Lets you switch between viewing **All** advertisers or only **Tracked** ones (your brand plus tracked competitors).
* **Search:** A search bar to filter the table by advertiser name.
* **Columns:**
* **#:** Rank position based on ad count.
* **Advertiser:** The brand's favicon and name. Can include a "You" or "Competitor" badge.
* **Ads:** The number of ads captured for this advertiser, alongside a relative colored bar indicating volume.
* **Shown:** The number of ads from this advertiser that were actually displayed in ChatGPT.
* **Prompts:** The number of unique tracked prompts that triggered this advertiser's ads.
* **Last seen:** The most recent date an ad from this advertiser was captured.
* **Expand toggle:** A chevron on the far right that opens an inline detail view.
* **Expanded Row Detail:** When expanded, the row reveals two sections:
* **Prompts triggering these ads:** A list of specific prompts that surfaced this advertiser, with the exact number of ads per prompt. Clicking a prompt drills down to the Responses page specifically for that prompt.
* **Latest creative:** The title and body text of the advertiser's most recent ad. If a destination URL is available, clicking this box opens the advertiser's landing page in a new tab.
### Top creatives
This table lists the most frequently captured ad copies.
* **Info tooltip:** *"Creatives are grouped by advertiser and ad copy, so tracking URL variations count toward the same creative. Captures and shown counts measure exposure in tracked ChatGPT answers, not clicks, conversions, spend, or performance."*
* **Search:** A search bar to filter creatives by text.
* **Columns:**
* **#:** Rank position by capture count.
* **Creative:** The ad's headline and body text. If a URL is known, hovering shows a link icon, and clicking opens the landing page in a new tab.
* **Advertiser:** The brand favicon and name of the advertiser running this creative.
* **Captures:** The number of times this specific creative was returned across your tracked prompts.
* **Shown:** The number of times this creative was actually rendered in ChatGPT.
* **Prompts:** The number of distinct tracked prompts that surfaced this creative.
* **Last seen:** The most recent date this creative was captured.
## What you can do here
* **Filter your view:** Use the filter row to change the date range or filter down to specific **Topics & Prompts** or **Prompt Tags**.
* **Save filter views:** Click **Views** to save your current filter configuration for easy access later.
* **Drill down to specific responses:** Click **View answers with ads** in the hero, or click the **Ads captured** / **Ads shown** stat tiles to jump to the Responses page pre-filtered to ad-bearing answers.
* **Inspect advertiser strategies:** Expand a row in the Advertisers table to see exactly which of your tracked prompts trigger their ads and read their latest ad copy.
* **Analyze specific prompts:** From an expanded advertiser row, click any prompt in the "Prompts triggering these ads" list to jump directly to the Responses page to read the full ChatGPT answer alongside the ad.
* **View landing pages:** Click on a linked creative in the Top Creatives table, or in an expanded advertiser row, to open the advertiser's actual destination URL in a new browser tab.
* **Toggle Segments:** Use the **All / Tracked** toggle on the Advertisers table to filter out unknown noise and focus solely on your defined competitors.
* **Search tables:** Use the local search inputs above the Advertisers and Top Creatives tables to find specific brands or ad copy text.
## Data shown
The data on this page reflects sponsored ads that ChatGPT returned alongside answers to the specific prompts you are tracking. The "You" and "Competitor" labels are matched against the brands and competitors you configured during onboarding or in your workspace settings.
## Common workflows
**Investigating competitor ad strategy:**
1. Go to the **Advertisers** table and toggle the segment to **Tracked**.
2. Look for rows with the orange **Competitor** badge.
3. Click the chevron on the right side of a competitor's row to expand it.
4. Review the **Latest creative** to see their messaging.
5. Look at the **Prompts triggering these ads** list, and click on a high-volume prompt to jump to the Responses page and see how their ad looks in context against the AI's organic answer.
**Finding top-performing creatives:**
1. Scroll down to the **Top creatives** card.
2. Scan the highest-ranked creatives to see what messaging advertisers are using frequently.
3. Click the title of a creative to open its landing page and see where the advertiser is routing traffic.
**Recovering from an empty state:**
1. If you land on the page and see the "No ads data yet" screen, read the description explaining that only ChatGPT serves ads today and that tracking more commercial prompts increases your chances of capturing them.
2. Click the **Manage prompts** button.
3. Add new prompts that reflect high-intent, commercial searches where advertisers are more likely to bid.
## Empty, loading, and error states
* **No ads data yet:** If your tracked prompts have *never* captured a single ad response, the entire page is replaced with a "No ads data yet" screen featuring an illustration of an ad in ChatGPT. It explains how ad capture works and offers a **Manage prompts** button to help you track more commercial searches.
* **No ads in this date range:** If you have captured ads historically but there are none in your *currently selected date filter*, the dashboard renders a smaller empty state card stating "No ads in this date range."
* **Table Empty States:** If a search yields no results, or if the "Tracked" segment has no data, the tables show "No advertisers match..." or "No creatives found."
* **Loading:** While the page loads, skeleton placeholders appear for the hero card, stat tiles, and table rows. If your subscription access is still resolving, you will see a full-page neutral loading spinner.
* **Errors:** If the dashboard data fails to load, a "Couldn't load ads data" card appears with a **Try again** button. If an individual table fails, it displays "Couldn't load advertisers/creatives" with a **Try again** link. If your plan entitlement fails to verify entirely, a full-page "Something went wrong" / "Couldn't verify access" screen is shown.
## Linked from / links to
* **Linked from:** The main app sidebar navigation (under the "Ads" item).
* **Links to:**
* **Responses page:** Via the "View answers with ads" link, stat tiles, and prompt drilldowns inside expanded rows.
* **Prompts page:** Via the "Manage prompts" button in the empty state.
* **External URLs:** Clicking linked ad creatives opens the advertiser's landing page in a new tab.
## Common support questions
**Why is "Ads captured" higher than "Ads shown"?**
An engine might return an ad in the background data, but choose not to display it to the user. "Ads captured" counts everything the engine processed, while "Ads shown" only counts ads that were actually rendered on screen for the user to see.
**What does "Auctioned but not shown" mean?**
This means an advertiser successfully bid and won an ad slot for a specific prompt, but ChatGPT ultimately decided not to render the ad in the final answer. We still track this because it reveals who is actively bidding on your keywords.
**Why does an advertiser show up as "Unknown advertiser"?**
Occasionally, the system captures an ad but cannot resolve a normalized root domain or brand name from the creative's data. These are grouped into an "Unknown advertiser" bucket. This row cannot be expanded.
**Why do I see the "No ads data yet" screen?**
Ad tracking only applies to ChatGPT, and ChatGPT typically only serves ads on highly commercial, transactional prompts. If you are tracking informational queries, you may not trigger any ads. Try adding more commercial prompts to your workspace.
**Can I see ads from Google AI Overviews or Perplexity?**
No. As noted in the page tooltips, only ChatGPT currently serves the sponsored ads tracked on this dashboard.
# Brand Profile
Source: https://docs.athenahq.ai/guides/brand-profile
Central hub for managing a website's brand identity: basic profile info, brand attributes, content rules, brand voice/kits, and technical AI-crawler configuration (llms.txt, sitemap, schema, AI accessibility).
`app.athenahq.ai/brand-profile`
## Purpose
The Brand Profile page is the central hub for managing how your brand is perceived and understood by AI models within Athena. It allows you to define your core brand identity, set rules for how Athena generates content, establish brand voice guidelines, and manage technical elements that ensure AI web crawlers can properly read your website.
Setting up the Brand Profile ensures that the content Athena creates sounds like your company and that the AI analytics accurately track the attributes (positive or negative) you care about most.
## What's on the page
### Header and Tabs
* **Page Header:** Displays "Brand Profile" with the subtitle "Your brand identity in one place".
* **View-only banner:** If you do not have permission to edit the brand profile, a floating pill appears at the bottom reading "View-only · Brand Knowledge". Hovering over it explains you need to ask an admin for write access.
* **Navigation Tabs:** Switches between **General**, **Attributes**, **Rules** (if available on your plan), **Brand Kits**, and **Technical** settings.
### General Tab
* **Brand Name:** The core name of your brand.
* **Industry:** A dropdown to select your company's industry category.
* **Website logo:** An upload area for your brand's logo. Must be a square image.
* **Brand Description:** A text area to describe your brand, positioning, and what you offer.
* **Base location:** The default operating country for your brand.
* **Default language:** The default language Athena should assume for your brand.
* **Save changes button:** Saves any updates made to these fields.
### Attributes Tab
* **Header & "Create new" button:** Allows you to define what your brand sounds like (Positive) and what it avoids (Negative).
* **Active Attributes Table:** Lists your currently tracked traits.
* **Attribute:** The name of the trait (e.g., "professional").
* **Sentiment:** Shows whether it is "Positive" (blue icon) or "Negative" (orange icon).
* **(⋯) Menu:** Contains the **Delete** action.
* **Deactivated attributes:** A collapsible section showing attributes you have previously deleted. Contains a **Restore** button next to each.
* **Attribute Backfill Bar (Floating):** If you add, delete, or restore an attribute, a bar appears at the bottom of the screen noting the number of changes (e.g., `Added "friendly"`). It allows you to select a date range and spend credits to **Backfill** (reanalyze historical data with your new attributes).
### Rules Tab
*(Note: This tab only appears if your plan includes the Content Memory feature.)*
* **Header & "Create New" button:** Manage global writing rules that apply across all content.
* **Brand rules table:**
* **Rule:** The text instruction (e.g., "Stop using em dashes").
* **Category:** The type of rule (Style, Formatting, Terminology, Tone, Structure, or Other).
* **Status:** A toggle switch indicating if the rule is currently active.
* **(⋯) Menu:** Contains **Edit** and **Delete** actions.
### Brand Kits Tab
* **Header & "Create New" button:** Manage guidelines for tone, voice, and style used during content generation.
* **Brand Kits table:**
* **Name:** The name of the brand kit.
* **Status:** The current state of the kit.
* *Draft:* "Setup is incomplete: click to continue"
* *In progress:* The kit's instructions are currently generating.
* *Retry:* "Generation failed: click to retry"
* *Default:* The currently active kit.
* *Set as default:* A button to make this kit the active one.
* **(⋯) Menu:** Contains **Edit** and **Delete** actions.
### Technical Tab
* **LLMs.txt:** Tells AI models what your site is about. Contains buttons to **Generate llms.txt** or **View llms.txt**.
* **Sitemap:** Generate and manage your XML sitemap. Includes a URL input field, a **Generate** button, and a collapsible "Generated sitemaps" section showing the URL, URL count, and creation date of existing sitemaps.
* **Schema:** Validate Schema.org JSON-LD structured data on your website. Includes a URL input, a **Validate** button, and preset example links to try.
* **AI Accessibility:** Includes a **Check AI accessibility** button that opens a dialog to see how AI models access your site.
## What you can do here
### General Profile Actions
* **Edit info:** Update your name, description, country, or language, then click **Save changes**.
* **Upload logo:** Drag and drop or click the upload area to add a logo. *Important: The logo must be perfectly square and under 5 MB.* It accepts JPEG, PNG, GIF, WebP, or SVG.
### Attribute Actions
* **Create new attribute:** Click **Create new**, type a name, choose "Positive" or "Negative" sentiment, and click **Add**. (Max 12 of each sentiment).
* **Delete attribute:** Open the ⋯ menu on an active attribute and click **Delete**. This deactivates it and moves it to the "Deactivated attributes" list.
* **Restore attribute:** Open the "Deactivated attributes" section and click **Restore** next to a trait to make it active again.
* **Backfill changes:** When you change attributes, the floating Attribute Backfill Bar appears. Adjust the date range preset (e.g., "Last 30 days"), review the required credit cost, and click **Backfill** to re-process past AI responses against your new traits. Click **View Changes** to see a list of pending adjustments, or dismiss them individually or all at once.
### Rule Actions (if applicable)
* **Create New Rule:** Click **Create New**, type your rule (max 30 words), select an optional category, and click **Add rule**.
* **Edit / Delete Rule:** Open the ⋯ menu on a rule row to **Edit** its text/category, or **Delete** it (requires confirmation).
* **Toggle Rule:** Click the switch in the Status column to turn a rule on or off instantly.
### Brand Kit Actions
* **Create a kit:** Click **Create New** to open a multi-step modal wizard. You will provide a blog URL, edit generated source notes, define brand tones, upload reference documents, and generate final guidelines.
* **Edit / Resume a kit:** Click on any row, or open the ⋯ menu and click **Edit**. If the kit is a draft, it will resume where you left off.
* **Set default:** Click the **Set as default** button on a finished kit to make it the primary voice for new content.
* **Delete kit:** Open the ⋯ menu and click **Delete**. You will be asked: *"Are you sure you want to delete '\[Name]'? This action cannot be undone."*
* **Retry generation:** If a kit says "Retry", click the badge to attempt generation again.
### Technical Actions
* **Manage LLMs.txt:** Click **Generate llms.txt**. Once created, click **View llms.txt** to open a dialog where you can preview the text, edit the markdown, or view the raw text. You can also click **Regenerate** or **Save** from inside the dialog.
* **Generate Sitemap:** Type an optional path (e.g., `blog`) next to your domain and click **Generate**.
* **View / Export Sitemap:** Click a generated sitemap row to open it. From the dialog, you can page through the URLs, click **Copy XML**, **Download XML**, or **Delete sitemap**.
* **Validate Schema:** Paste a URL and click **Validate** (or click a "Try:" example). Athena will check for JSON-LD data and display any issues or syntax errors alongside instructions on how to fix them.
* **Check AI Accessibility:** Click **Check AI accessibility** to open a dialog. Athena will test your domain against the specific web crawlers used by ChatGPT, Claude, Perplexity, Gemini, Copilot, AI Mode, AI Overviews, Grok, DeepSeek, and Rufus to tell you if your site is Accessible, Partial, or Blocked.
## Data shown
* **Brand settings:** Displayed data comes from your organization's core configuration settings.
* **Brand Kits & Rules:** The custom writing instructions and tones you have built or generated using Athena's AI tools.
* **Technical validations:** Sitemaps and LLMs.txt are generated dynamically based on your site's content. Schema and AI Accessibility checks are performed live by reaching out to the specified URL when you request them.
## Common workflows
### Updating basic brand identity
1. Navigate to the **General** tab.
2. Fill out or update the Brand Name, Industry, Logo, and Brand Description.
3. Ensure your Base location and Default language are correct.
4. Click **Save changes** at the bottom right.
### Adding attributes and backfilling data
1. Go to the **Attributes** tab and click **Create new**.
2. Type the name of a trait you want to track, select "Positive" or "Negative", and click **Add**.
3. The floating Attribute Backfill Bar will appear at the bottom of the screen.
4. Select a date range (e.g., "Last 30 days"), review the credit cost, and click **Backfill**. Athena will process past responses to track this new trait.
### Validating site crawler access
1. Go to the **Technical** tab.
2. Under AI Accessibility, click **Check AI accessibility**.
3. A dialog will open and automatically begin pinging your domain with the user agents of major AI models.
4. Review the results to see if any bots are being blocked by your site's firewall or robots.txt file.
## Empty, loading, and error states
* **Empty states:** If you have no data in a section, you will see friendly placeholder cards (e.g., "No attributes yet", "No brand kits yet", "No rules yet") with brief instructions on how to get started.
* **Loading states:** While data is loading, you'll see animated gray placeholder shapes (skeletons). Generating sitemaps, brand kits, or LLMs.txt will show a loading spinner on the button.
* **Error states:** If you lack permissions, fields will be grayed out and a "View-only" banner will appear. If you try to upload a logo that isn't square or is too large, or if a generation fails, a red toast message will appear at the top of the screen explaining the issue.
## Linked from / links to
* **Linked from:** The main Sidebar navigation, the Content editor (via the deep link "Manage brand kits"), and the Onboarding Tour (which directs new users here to establish brand guidelines).
* **Links to:** The Schema validator empty state links out to official `schema.org` documentation. The Sitemap panel links out to `sitemaps.org` protocol documentation.
## Common support questions
**Why won't my logo upload?**
Logos must have the exact same width and height (a perfect square) and be under 5 MB in size. Supported formats are JPEG, PNG, GIF, WebP, or SVG.
**Why don't I see the Rules tab?**
The Rules tab requires the Content Memory feature to be active on your subscription plan.
**Why are my "Save" and "Create" buttons disabled?**
Editing the brand profile requires write access to Brand Knowledge. If you only have view access, you will see a "View-only" banner at the bottom of your screen, and all editing controls will be disabled.
**What does the Attribute Backfill bar do?**
When you add or remove an attribute, your historical data doesn't automatically know about the change. The Backfill bar lets you spend credits to go back in time (e.g., the last 30 days) and re-analyze past AI responses to see if they exhibited your new brand attribute.
**How many attributes can I track?**
You can have a maximum of 12 active Positive attributes and 12 active Negative attributes at one time.
# Competitors
Source: https://docs.athenahq.ai/guides/competitors
Manage tracked competitors (and your own website's identifiers/domains), review discovered competitor suggestions, restore deleted competitors, and control historical reanalysis (backfill) of competitor/identifier changes.
`app.athenahq.ai/competitors`
## Purpose
The Competitors page is where you manage how Athena tracks your brand and your competitors in AI search responses. It allows you to add known competitors, review AI-discovered competitor candidates, and configure the specific keywords (identifiers) and URLs (domains) used to detect when a brand is mentioned or cited.
Because AI engines often refer to brands by varying names or abbreviations, this page is critical for ensuring accurate Share of Voice tracking. When you make changes to identifiers or competitors, this page also provides the tools to "backfill" those changes, spending credits to reanalyze your historical data so past charts reflect your new tracking rules.
## What's on the page
### Identifier Suggestions Bar
Appears above the Tracked competitors table if Athena's AI detects new ways engines are referring to your tracked brands. It displays the suggested keyword, how many responses it was seen in, and offers inline buttons to **Dismiss** or **Add** the suggestion. A **Review all** button opens a detailed modal to bulk-process suggestions.
### Discovered Competitors Table
Found on the "Discovered competitors" tab. Lists brands Athena has noticed in your data that you aren't tracking yet.
* **Competitor**: The candidate's logo, name, and domain. Clicking the row expands it to show "Evidence"—specific snippets and prompts where the brand was mentioned by models like ChatGPT, Claude, Perplexity, or Gemini.
* **Mention %**: The share of analyzed responses mentioning this brand.
* *Tooltip*: "Percentage of AI responses that mention this competitor"
* **Mentions**: The raw count of mentions.
* *Tooltip*: "Total number of times this competitor was mentioned across all responses"
* **Mentioned in**: The unique response count.
* *Tooltip*: "Unique responses mentioning this competitor out of total analyzed"
* **Last seen**: The most recent date the brand was mentioned.
* **Actions**: An **Add** button to instantly track the candidate.
### Deleted Competitors Table
Found on the "Deleted" tab. Lists previously removed competitors by Name and Website, with a **Restore** button for each.
### Change Queue Bar
A persistent bar at the bottom of the screen that tracks pending tracking changes (like adding a keyword or renaming a competitor).
* When changes are queued, it summarizes the count (e.g., "3 pending changes") and offers a **Review & backfill** button.
* When a backfill is running, it shows a progress bar (e.g., "Reanalyzing X of Y responses") and a **Details** button.
* If a backfill fails, it shows "Backfill failed" with **Dismiss** and **Retry** buttons.
## What you can do here
* **Add a new competitor**: Click **Add competitor**. You can add a single brand, paste a list of names/URLs under the "Multiple" tab, or upload a spreadsheet via the "Upload a CSV or Excel file" section. You can optionally have Athena's AI generate identifiers for your imports.
* **Manage Identifiers**: Click the identifiers count on any row. From the dropdown, you can type to **Add** a new keyword, click an existing one to edit it, or click the X icon to remove it. You can also toggle **Match case** to enforce exact capitalization.
* **Manage Domains**: Click the domains count on any row. You can **Add** a domain (including wildcards like `*.example.com`), remove one, or hover over a secondary domain and click **Make primary** to set it as the brand's main URL.
* **Edit a brand's name**: Click the three-dot menu (⋯) on a row and select **Edit**. For competitors, you have the option to automatically update your identifiers to reflect the new name.
* **Delete a competitor**: Click the three-dot menu (⋯) and select **Delete**. You will be asked to confirm: "Are you sure you want to delete \{name}? You can restore it later from the deleted competitors section."
* **Bulk Actions**: Select multiple checkboxes to reveal the bulk action bar at the bottom. You can **Delete**, **Export** (download a CSV of the selected brands), or **Reset** your selection.
* **Restore a competitor**: Go to the Deleted tab, click **Restore**, and confirm the action to bring the brand back into your active tracking.
* **Review and Backfill Changes**: When you add/remove identifiers or domains, those changes apply to *new* responses immediately. To apply them to your historical data, click **Review & backfill** in the bottom bar. In the dialog, you can:
* Click the **Undo** arrow icon on any specific change to revert it.
* Click **Undo all** to cancel all pending edits.
* Use the **Date range picker** to define how far back to reanalyze data. The dialog calculates the credit cost dynamically.
* Click **Start backfill** to spend credits and update history, or **Skip backfill** to clear the queue and keep your changes for future tracking only (spending no credits).
* **View Mention Evidence**: On the Discovered tab, click a row to reveal snippets. Clicking a specific snippet opens the **Responses Drawer**, showing the full AI response and citations.
## Data shown
This page displays your own brand configuration alongside the list of competitor brands you have chosen to track. It also analyzes the text of your previously collected AI responses to suggest new competitor candidates (brands frequently mentioned alongside yours) and new identifiers (terms engines frequently use to refer to your tracked brands).
## Common workflows
**Adding competitors via CSV**
1. Click **Add competitor** in the top right.
2. In the drawer, select the **Multiple** tab, then scroll to the "Upload a CSV or Excel file" section.
3. Optionally click **Download Template** to see the required format (Name, URL(s), Identifiers).
4. Upload your file. Check the box if you want Athena to use AI to generate missing identifiers.
5. Review the parsed companies in the preview, make any necessary edits inline, and click **Add N competitors**.
**Updating a brand's keywords and backfilling**
1. In the Tracked competitors table, click the **Identifiers** dropdown for a brand.
2. Add a new keyword that an AI engine has been using to refer to them.
3. Notice the bottom Change Queue bar appears, indicating 1 pending change.
4. Click **Review & backfill**.
5. In the dialog, leave the date range as "All time" (or select a shorter window to save credits).
6. Click **Start backfill** to reanalyze your historical responses for this new keyword.
**Handling AI Identifier Suggestions**
1. If Athena detects new aliases for your brands, the Identifier suggestions bar appears at the top of the table.
2. Click **Review all** to open a detailed dialog.
3. Page through the suggestions for each brand. Click **Add** for accurate aliases, or **Dismiss** for irrelevant ones.
4. Alternatively, if all suggestions for a brand are accurate, click **Add all N identifiers**.
5. Run a backfill from the bottom bar to apply these new aliases historically.
## Empty, loading, and error states
* **No website selected**: If you haven't selected a workspace from the main sidebar, the page displays a building icon and "No website selected. Choose a website from the sidebar to see its tracked competitors."
* **Empty tables**: If a tab has no data, you will see "No results.", "No discovered competitors yet", or "No deleted competitors".
* **Loading**: While tables are fetching data, an animated skeleton loader appears.
* **Backfill errors**: If a backfill job fails, the bottom bar turns red and reads "Backfill failed. Something went wrong while reanalyzing..." with a **Retry** button to start it again at no extra cost, and a **Dismiss** button to clear the alert.
## Common support questions
**Why isn't my new keyword showing up in my past charts?**
When you add a new identifier or domain, it applies to *future* AI responses automatically. To apply it to past data, you must click "Review & backfill" in the bottom bar and click "Start backfill" to reanalyze your history.
**What is the difference between an Identifier and a Domain?**
Identifiers are text keywords used to detect *mentions* of a brand in the body of an AI response (e.g., "Acme Corporation" or "AcmeCorp"). Domains are URLs used to track *citations* (e.g., footnoted links back to `acme.com`).
**Can I delete my default identifier?**
No. The default identifiers (derived from the exact brand name and primary domain) are permanent. If the brand name is wrong, you can edit the brand's name via the row's action menu, which allows you to seamlessly update the underlying identifiers.
**Why is the Export button asking me to upgrade?**
Data exports (downloading CSVs of your competitors) are a premium feature. Customers on the Free plan will be prompted to upgrade when clicking the Export button.
**How much does a backfill cost?**
The cost depends on the number of historical responses being reanalyzed. When you open the "Review & backfill" dialog, it will calculate and display the exact credit cost before you confirm the action.
# Content Hub
Source: https://docs.athenahq.ai/guides/content
A spreadsheet-style hub for creating, importing, tracking, enriching with AI agent columns, and publishing all of a website's content.
`app.athenahq.ai/content`
## Purpose
The Content Hub is a powerful spreadsheet-style workspace where customers manage their entire content lifecycle. It allows marketers to plan, track, generate, and publish content optimized for AI search.
Customers can use this page to import existing URLs, write new AI-optimized drafts from scratch, execute bulk AI actions (like analyzing competitors or generating FAQs) across multiple pages at once using custom "Athena Agent" columns, and track performance metrics such as AI citations, traffic, and search rankings in one unified view.
## What's on the page
**Page Header & Toolbars**
* **Page Title**: Displays "Content" or the current view name.
* **View-only Banner**: A floating notice reading "View-only · Content" if the user lacks write permissions. Hovering shows: "Ask an org admin for Content write access to make changes here."
* **Filters**: A contextual filter bar to drill down into content by date range, search queries, Athena content types, published status, models, prompts, locations, and custom column values.
* **Create Button**: Opens a dialog to generate new content via predefined workflows.
* **Import / Export**: Actions to upload CSVs, scan domains, or download the current view as a CSV.
**Sheet Tab Bar**
* **Tabs**: Organize content into different saved views (e.g., "All content", "Published"). The tabs can be dragged left or right to reorder them.
* **New sheet (+)**: Opens the "New Sheet" dialog to create a fresh view, optionally populated with pre-built AI agents.
* **Tab Dropdown Menu (▼)**: Available on user-created tabs to "Rename", "Duplicate", or "Delete" the sheet.
**Content Spreadsheet Grid**
* **Row Checkbox**: Used to select one or multiple rows for bulk actions. Users can hold Shift and click to select a range. A toast appears after initial uses: "Hold Shift and click another checkbox to select or deselect a range."
* **Content Title**: The name of the article or page. May include a badge indicating how it was created (e.g., Draft, Snipe, Optimize, Slice). Clicking the title opens the Content Editor sidebar.
* **URL**: The live web address for the content, which acts as the tracking link for metrics.
* **Status**: Shows the current phase of the content (e.g., "Pending review", "Drafting...", "Approved", "Dismissed").
* **Metrics**: A dynamic column that displays performance data. Clicking the gear icon (⚙) opens a dropdown to switch the visible metric. Options include:
* **AI citations**: "Freshness score", "Citation %", "Citations"
* **AI positions**: "Google ranking", "GEO ranking"
* **Organic search**: "Clicks", "Impressions", "CTR" (Disabled with tooltip: "Connect GSC to unlock" if Google Search Console isn't connected)
* **Site analytics**: "Traffic", "Bounce rate", "Engagement rate", "Avg duration", "AI traffic" (Disabled with tooltip: "Connect GA4 to unlock" if GA4 isn't connected)
* **Created / Updated / Published Date**: Timestamps tracking the content's lifecycle.
* **Prompts**: The target prompts linked to the specific piece of content.
* **Custom Columns**: Standard structured data fields (Text, Number, Date, Checkbox, Link, Multi-select).
* **Athena Agent**: AI-generated responses based on a custom prompt. Displays "\[empty]" if no data is present, or "Has value" / the actual response text.
* **Web Search**: Displays search results gathered from the web based on a configured query.
* **Cited Sources**: Retrieves top cited sources for the row's linked prompts.
* **Freshness Score**: Analyzes source publication dates to determine how fresh the content needs to be.
* **Source Analysis**: Analyzes specific target URLs against a custom prompt.
* **OG image**: A generated social media preview card.
* **Approval**: A checkbox that requires specific assigned users to approve the row.
**Aggregate Metrics Footer**
* A sticky footer at the bottom of the table summarizing the currently visible rows, showing totals like content count, average citation rate, total citations, and traffic. Clicking it opens a drawer with detailed time-series charts.
**Content Sidebar / Editor Overlay**
* Clicking a row opens a rich text editor overlay with tabs for "Content", "Brief", "Metadata", and "Agents". It includes tools for AI revision, version history, and publishing.
## What you can do here
**Creating & Importing Content**
* **Create**: Click the "Create" button to open the action dialog. Options include:
* **Write**: Create content optimized for AI search.
* **Optimize**: Optimize existing content for AI search.
* **Snipe**: Snipe highly-cited content and outrank competitors.
* **Slice**: Split content into multiple articles.
* **Blank editor**: Open a blank editor to write or paste.
* **Import**: Click "Import" to choose "Import CSV" or "Domain Import" (which scans your site's sitemap to pull in existing pages).
* **Export as CSV**: Found under the "Columns" (⚙) popover or the main toolbar, allows downloading the current grid data.
**Managing Sheets and Columns**
* **Add a column**: Click the "+" button on the far right of the table header to add base columns (Text, Date, Link, etc.), special columns (Approval, OG image), or pre-built Agent columns.
* **Column settings**: Click the gear (⚙) above the "Add column" button to toggle column visibility ("Hide all", "Show all"), drag to reorder columns, or open "Column dependencies" to see how agent columns relate to one another.
* **Edit a column**: Click the dropdown arrow on any column header to "Rename" or "Delete column". For AI columns, options like "Edit Prompt", "Edit Query", "Edit Settings", or "Edit Approvers" are available.
**Running AI Agents (Bulk or Single Row)**
* **Bulk Run**: Click a custom AI column's header menu and select the run action (e.g., "Bulk Athena Agent", "Bulk Search", "Bulk Retrieve", "Bulk Analyze"). You can choose to run it for "All rows", "Missing only", "Stale rows", or "Ready rows".
* **Run Row**: Right-click or select a specific row to open the "Run Athena Agent columns" dialog. This lets you execute multiple agent columns for that specific row simultaneously. It will warn you if there is a "Circular dependency detected."
**Using the Content Editor**
* **Fetch content**: On external rows missing text, click "Fetch content" (cloud download icon) to pull the live page data into the editor.
* **Revise with Athena AI**: In the editor, click this pill to open a chat. Ask Athena to rewrite or adjust the text. The proposed changes appear as a highlighted diff in the document.
* **Accept / Reject**: Review the AI's proposed changes and click "Accept" (⌘↵) or "Reject" (esc) in the floating strip.
* **Version History**: Click the history toggle to view past revisions (e.g., "v5"), see what was "Kept" or "Discarded", and restore previous states.
## Data shown
The data here represents your brand's entire tracked content inventory. This includes live pages imported from your domain, manually added external URLs, drafts generated by Athena's AI workflows, and competitor pages you are analyzing. The metrics are aggregated from AI engines (ChatGPT, Claude, Gemini, Perplexity, Copilot, Grok, DeepSeek), Google Search Console, and Google Analytics 4.
## Common workflows
**Generating a new AI-optimized article**
1. Click the "Create" button and select "Write".
2. Choose a Brand kit and provide the target keywords or prompts.
3. Wait for Athena to generate the content brief.
4. Review the brief in the sidebar editor, make any necessary adjustments, and click "Approve" to generate the full article.
5. Once the article is ready, use the "Publish" or "Track" buttons to push it to your CMS or mark it as live.
**Enriching content with a Custom Agent**
1. Click the "+" button on the right edge of the table headers and select "Custom agent".
2. Type a description of what you want the agent to do (e.g., "Summarize the key points of this content").
3. Save the column.
4. Click the dropdown arrow on the new column's header and select "Bulk Athena Agent".
5. Choose "Missing only" to generate summaries for all rows that don't have one yet.
**Importing existing website pages**
1. Click the "Import" button and select "Domain Import".
2. Enter your website URL and click to start the scan.
3. Once the sitemap is processed, review the list of discovered URLs.
4. Select the checkboxes next to the pages you want to track (or click "Select all articles").
5. Click the import button to add them to your spreadsheet.
## Empty, loading, and error states
* **Empty states**: If no content exists or matches a search, a message appears saying "No content to display. Content will appear here once articles are created." For agent columns, if generation yields nothing, it displays "No columns generated. Try a different prompt."
* **Loading states**: The table displays animated shimmer bars while content or metrics are fetching. When bulk-running agents, individual cells display a spinning loader or "Waiting" badge. A global loading bar appears across the top of the screen during navigation.
* **Error states**: If a bulk action or generation fails, a red toast notification appears (e.g., "Failed to update cell value"). If an AI column prompt references a deleted column, a red alert icon appears with the tooltip "Prompt references a deleted column," and an inline banner warns: "This prompt references \[N] deleted columns. Remove the missing reference(s) or they will output '\[column deleted]'." If the editor sidebar fails to load, a "Couldn't load this content" screen appears with a "Try again" button.
## Linked from / links to
* **Linked from**: The main app sidebar navigation ("Content"), Oracle remediation draft cards, and various recommendation flows throughout the app.
* **Links to**: The "Knowledge Base" setup page, the "Brand Profile" settings (to manage Brand Kits), and individual prompt detail pages when clicking a linked prompt badge.
## Common support questions
**Why is my metric column showing as empty or "Not published"?**
Metrics require a live URL to be tracked. If your content is still in the "Draft" phase or doesn't have a URL entered in the URL column, Athena cannot fetch traffic or citation data for it.
**How do I fix a "Circular dependency detected" error?**
This happens when two Athena Agent columns reference each other in their prompts, creating an infinite loop. Open the "Column dependencies" view from the Column Settings (⚙) menu to see the map of your columns, then edit one of the column's prompts to remove the reference to the other.
**Why can't I edit or run my agent columns?**
If you see a "View-only" banner at the bottom of the screen, you do not have write access to the Content Hub. You will need to ask an organization admin to update your role permissions.
**Where did my older metric data go after I excluded a page from attribution?**
When you select rows and exclude them from attribution, their citations are retroactively removed from all past periods, not just going forward. This ensures your metrics accurately reflect only the pages you actively want to claim credit for.
**Why is the "Organic search" metric group greyed out?**
Those specific metrics (Clicks, Impressions, CTR) require a connection to Google Search Console. If the integration isn't set up in your organization settings, the metrics will remain locked.
# Create Pitch Report
Source: https://docs.athenahq.ai/guides/create-pitch
A two-step wizard for analyzing a website and generating (or cloning) a pitch report with competitors and prompts before creating it.
`app.athenahq.ai/create-pitch`
## Purpose
This page provides a two-step wizard that allows customers to generate a competitive pitch report by analyzing a target website. The tool automatically researches the website's brand profile, primary competitors, and relevant search prompts (both branded and non-branded) to build a comprehensive pitch.
Customers can also arrive at this page to clone and tweak an existing pitch report, skipping the initial analysis step to jump straight into customizing the data.
## What's on the page
### Access gating states
Before the wizard renders, the page checks if the organization has access to the pitch workspace feature and sufficient pitch credits.
* **Pitch access required:** A full-page message shown if the organization lacks the required plan or feature access. Includes a "Contact Support" button and a "Back to Dashboard" button.
* **No Pitch Reports Available:** A full-page message shown if the organization has access but has run out of pitch credits. Includes a "Contact Support" button and a "Back to Workspace" button.
### Progress steps header
Shows a numbered `1 — 2` progress line. The title and subtitle update dynamically:
* **Step 1:** "Create Pitch Report" (or "Clone Pitch Report" if duplicating an existing pitch).
* **Step 2:** "Review & Customize".
### Step 1: Website URL
* **Website URL:** A text input where the user provides the target domain (e.g., `example.com`).
* **Country:** A searchable dropdown to select the base country for the pitch's research and localization.
* **Language:** A searchable dropdown to set the language for the analysis.
### Step 2: Review & Customize
* **Brand profile card:** Shows the website's logo, name, and URL. Also includes an identifiers dropdown (e.g., "1 identifier") to manage the brand names associated with the website.
* **Name:** An editable text field containing the analyzed website's name.
* **Description:** An editable text area containing the AI-generated description of the company.
* **Customization Tabs:** A toggle switch to alternate between managing **Competitors** and **Prompts**.
* **Add button:** Located above the tabs, this opens either the Competitor or Prompt drawer depending on which tab is active.
* **Competitor list:** Shows the researched competitors. Each row displays the competitor's logo, name, URL, their specific identifiers, and a `⋯` (More) menu. If a cloned competitor is missing a URL, a warning stating "Add a website URL" is shown instead of the link.
* **Prompt list:** Shows the researched search queries. Each row displays the prompt text, a badge indicating if it is "Branded" or "Non-Branded", and a `⋯` (More) menu.
* **Scroll indicator / More button:** A small floating "More" button that appears if the content overflows, allowing the user to quickly scroll down.
### Bottom navigation
* **Back:** Returns to the previous step without losing data.
* **Analyze Website / Create Pitch Report:** The primary action button. Changes to a shiny "Analyzing website..." or "Processing..." state while work is occurring.
## What you can do here
* **Analyze a website:** On Step 1, clicking "Analyze Website" triggers the AI to research the domain, generate a company description, find competitors, and create relevant search prompts.
* **Edit identifiers:** Clicking the "N identifier(s)" button opens a dropdown where you can add, rename, or delete tracking aliases for the brand or competitor. It also includes a "Match case" toggle to enforce capitalization.
* **Add a competitor:** Clicking "Add" while on the Competitors tab opens the "Add New Competitor" drawer.
* **Edit or delete a competitor:** Clicking a competitor row, or opening its `⋯` menu and selecting **Edit**, opens the Competitor drawer. Selecting **Delete** from the `⋯` menu removes the competitor from the list entirely.
* **Add a prompt:** Clicking "Add" while on the Prompts tab opens the "Add Prompt" drawer.
* **Edit or delete a prompt:** Clicking a prompt row, or opening its `⋯` menu and selecting **Edit**, opens the Prompt drawer. Selecting **Delete** from the `⋯` menu removes the prompt.
* **Change Prompt Type or Country:** Inside the Prompt drawer, you can assign a prompt to a specific country and classify its Type as "Branded" (high intent) or "Non-Branded" (discovery).
* **Create Pitch Report:** On Step 2, clicking this validates all data and generates the final pitch, then navigates the user to the Pitch Workspace.
* **Quickly visit a domain:** Clicking the logo/URL on the brand profile card or any competitor row opens that website in a new browser tab.
## Data shown
The page displays real-time AI research generated specifically for the provided URL, including a summarized company description, up to 10 discovered competitors, and up to 25 relevant search prompts. If the page was opened via a "clone" action, it instead pre-fills with the exact saved data from the cloned pitch report.
## Common workflows
**Create a new pitch report from scratch**
1. Navigate to the Create Pitch Report page.
2. Enter the target website URL and confirm the Country and Language on Step 1.
3. Click "Analyze Website" and wait for the AI to generate the competitive research.
4. On Step 2, review and edit the generated Name, Description, and brand Identifiers.
5. Review the Competitors and Prompts tabs, using the "Add" button or `⋯` menus to adjust the lists as needed.
6. Click "Create Pitch Report" to finalize the pitch and open it in the workspace.
**Clone an existing pitch**
1. Click "Clone" on an existing pitch in the Pitch Workspace.
2. The wizard will automatically skip Step 1 and open directly onto Step 2 with the cloned data pre-filled.
3. If any competitor is missing a URL (which can happen on older cloned pitches), click it to open the drawer and provide the domain.
4. Make any desired adjustments to the prompts or competitors.
5. Click "Create Pitch Report" to save the new copy.
## Empty, loading, and error states
* **Loading:** An animated spinner is shown if the page is still verifying the organization's feature access or loading clone data. During Step 1 analysis, skeleton placeholders mimic the competitor and prompt cards while they are being generated.
* **Empty:** If all generated competitors or prompts are deleted, the respective tab shows "Add at least one competitor to create this pitch." or "Add at least one prompt to create this pitch."
* **Errors:**
* If analysis fails on Step 1, a toast says "Failed to analyze the website and generate pitch research. Please try again."
* Toast errors appear if a user tries to add more than 10 competitors or 25 prompts.
* Toast errors appear if duplicate identifiers are added.
* Submission validation errors appear if the user tries to create the pitch with a blank website name, an empty competitor list, a competitor missing a URL, or an empty prompt list.
## Linked from / links to
* **Linked from:** The Pitch Workspace (via the "Create Pitch" or "Clone Pitch" buttons) and the main sidebar navigation.
* **Links to:**
* The Pitch Workspace (upon successful creation or when clicking "Back to Workspace").
* The main dashboard (`/olympus`) when clicking "Back to Dashboard" from an access-denied screen.
* Support (`mailto:support@athenahq.ai`) from access-denied screens.
## Common support questions
**Why is the "Create Pitch Report" button disabled?**
The button disables itself if the pitch is missing required information. This happens if there are zero competitors, zero prompts, or if a competitor is missing its website URL (often seen when cloning older pitches). Adding the missing data will re-enable the button.
**Why did the page skip Step 1?**
If you click "Clone" on an existing pitch, the system already has the URL, language, and country data. It skips Step 1 so you can immediately begin tweaking the cloned data on Step 2.
**How does the system decide if a prompt is Branded or Non-Branded?**
When adding or typing a new prompt, the system automatically marks it as "Branded" if the text contains the website's name. However, once you manually change the Type dropdown in the prompt drawer, this auto-detection stops, and it respects your manual choice.
**Can I add more than 10 competitors?**
No, a single pitch report is currently limited to a maximum of 10 competitors and 25 prompts.
# Glossary
Source: https://docs.athenahq.ai/guides/glossary
Provides a searchable, categorized reference of plain-language definitions for every metric, score, and concept used across AthenaHQ.
`app.athenahq.ai/glossary`
## Purpose
The Glossary page serves as the central dictionary for every metric, score, and concept used across the AthenaHQ platform. It provides customers with plain-language definitions, formulas, and examples for everything from Share of Voice to AI Search Value.
Customers use this page to understand exactly what their numbers mean, how Athena collects and calculates data, and the terminology behind their prompt strategies. It is frequently accessed via deep links embedded in tooltips and help icons throughout the app.
## What's on the page
**Category Navigation**
Depending on the user's screen size, a navigation menu appears to help them jump between sections. On wide screens, this is a sticky left rail labeled "On this page". On narrower screens, it collapses into a horizontal, scrollable pill bar pinned just beneath the page header.
**Hero Section**
The top of the page features a "Reference" tag, the main title "The AthenaHQ glossary", and a brief introduction explaining that the page contains definitions for metrics, scores, and concepts.
**Glossary Sections**
The definitions are grouped into six main categories, each displaying an icon, title, and a brief description of what the category covers. Inside each category is a list of expandable terms:
* **Visibility & rankings**: Covers "Mention Rate", "Share of Voice (SOV)", "Position", and "Filtering by model".
* **Citations & sources**: Covers "Citation Rate", "Sources vs. citations", "Attributed Citations", and "Traffic Source Metrics".
* **Sentiment & perception**: Covers "Brand sentiment & traits".
* **Value & ROI**: Covers "AI Search Value".
* **How Athena collects data**: Covers "Stream Data", "Volume estimation (QVEM)", and "Responses Analyzed".
* **Prompt strategy**: Covers "Funnel stage", "Search intent", "Personas", "Locations", and "Competitors".
**Expandable Term Rows**
Every glossary term sits in its own row, displaying the term name and a one-line summary. Clicking the row expands it to reveal a detailed explanation, which often includes mathematical formulas, styled example boxes, and bulleted lists.
## What you can do here
* **Jump to a category**: Click any category label in the left rail or the top pill navigation. The page will smoothly scroll to that section, and the navigation menu will highlight the active category.
* **Expand or collapse a definition**: Click any term row to toggle it open or closed. You can have multiple terms expanded at the same time.
* **Deep link to a term**: If a user navigates to the page using a specific URL hash (e.g., via a tooltip on another page), the glossary will automatically scroll down to that exact term and expand it.
## Data shown
This page displays static, pre-written reference content authored by the AthenaHQ team. It does not display customer-specific data, live metrics, or active account configurations.
## Common workflows
**Understanding a specific metric calculation**
1. A customer is looking at their dashboard and is unsure how their "Mention Rate" is calculated.
2. They navigate to the Glossary and click "Visibility & rankings" in the "On this page" navigation menu.
3. They click the "Mention Rate" row to expand it.
4. They read the plain-language explanation and review the formula to understand the difference between relative and absolute mention rates.
**Following a contextual help link**
1. While configuring a scheduled data stream, a customer clicks an info icon next to "Stream Data".
2. They are redirected to the Glossary page with a deep link targeting that specific term.
3. The page loads, automatically smooth-scrolls to the "Stream Data" definition, and expands it so they can read exactly how prompt fan-out and scheduling work.
## Empty, loading, and error states
* **Loading**: While the app verifies the customer's active subscription, the page returns a blank state and does not render the glossary UI.
* **Empty**: This page relies entirely on static definitions, so it never has an "empty" data state.
* **Error / No Access**: Access to the glossary requires an active paid subscription plan. If a customer is on the Free plan or their subscription verification fails, the page simply renders as blank (returns nothing) rather than showing a dedicated paywall or error message.
## Linked from / links to
* **Linked from**: Information icons and contextual tooltips throughout the app (such as the Stream Data dialog or impression volume tooltips) often deep-link directly to specific terms on this page.
* **Links to**: This page does not feature outbound links; it serves purely as a reference destination.
## Common support questions
**Why is the glossary page blank for me?**
The glossary is gated behind an active subscription. If your organization is on a free plan, or if your payment is past due and your grace period has ended, the page will not load.
**Can I link my team directly to the definition for AI Search Value?**
Yes. You can copy the URL while you are anchored to a specific term, and anyone in your organization with an active login will be taken directly to that expanded definition when they click the link.
**What's the difference between a Source and a Citation?**
A Source is a unique URL or domain that an AI model pulls from. A Citation is a single occurrence of that source being referenced in a specific answer. The glossary's "Citations & sources" section breaks this down completely.
**Where can I see how volume estimates are calculated?**
Under the "How Athena collects data" section, expand the "Volume estimation (QVEM)" row to see a breakdown of the public and private data sources the model uses to generate estimates.
# Group Dashboard
Source: https://docs.athenahq.ai/guides/group-id
Show combined AI-search visibility metrics (share of voice, mention/citation rate, position, dollar value) across all websites in a group, with filters and saved views.
## Purpose
The Group Dashboard provides a combined view of AI-search visibility metrics across multiple tracked websites. It allows customers to monitor Share of Voice, Mention Rates, Citation Rates, ranking positions, and the estimated dollar value of their AI presence at an aggregate level, rather than checking each website individually. Customers can filter this data by specific websites, topics, prompts, dates, and models, and save these configurations as custom views for quick access.
## What's on the page
* **Page Header**: Displays "Group / " followed by the name of the group you are currently viewing.
* **Filter Bar**: A sticky bar at the top of the dashboard containing all data controls.
* **Date Range**: Allows you to pick the primary time period for the data. You can also pick a "compared to" period to see historical deltas (like "+2.5%").
* **Websites, Topics & Prompts**: A dropdown that lets you narrow down the dashboard to specific websites in the group, specific topics, or individual prompts.
* **+ Add filter**: A menu to add more specific filters (like Models, Prompt status, Locations, etc.) or import filters from an individual website's view.
* **Combine websites**: A toggle switch. When turned on, the dashboard combines all the websites in the group into a single aggregated brand view. When turned off, it breaks out performance metrics for each website individually.
* **Views**: A dropdown menu to save the current filter setup, switch between saved views, or revert to the "Default" view.
* **Dashboard Cards**:
* **Share of Voice**: A donut chart and ranked list showing how often AI models mention your grouped brand(s) compared to your top competitors.
* **Mention Rate**: A time-series chart showing the percentage of AI responses that mention your brand over time.
* **Citation Rate**: A time-series chart showing how often AI responses directly cite your tracked content over time.
* **Position Over Time**: A chart tracking your average ranking position in AI responses over time.
* **Dollar Value Captured**: Estimates the monetary value of your brand's AI visibility.
* **Card Controls**:
* **(i) (Info icon)**: Hovering or clicking this icon on any card opens an explanation of what the metric means and how it is calculated.
* **Drag handle**: Located in the top-right of each card (appears on hover), allowing you to click and drag to rearrange the dashboard layout.
* **Resize handle**: Located in the bottom-right of cards, allowing you to drag and resize the card's width or height.
## What you can do here
* **Filter the dashboard data**:
* Click **Date Range** to select a time frame and an optional "compared to" period (which adds trend badges like "+X%" to the metrics). To clear the comparison, click the **x** next to the comparison date.
* Click **Websites, Topics & Prompts** to open a popover where you can search, expand websites/topics, and check specific prompts. Click **Apply** to update the dashboard. You can also click **Clear** to remove the selection, or **Select All** to select every prompt. If a filter is active, you can clear it quickly by clicking the **x** on the filter chip.
* Click **+ Add filter** to filter by Models (ChatGPT, AI Overviews, Perplexity, Gemini, Copilot, Claude, AI Mode, Grok, DeepSeek), Prompt status (Active, Paused, Both), Prompt type (Non-Branded, Branded, Both), Variations, Locations, Personas, Prompt tags, and Brand identifiers.
* If you have active filters, click **Clear All** (appears next to the filters) to reset them.
* **Toggle "Combine websites"**: Click the switch next to the "Views" dropdown to change whether the charts display data for the group as one massive brand (combined) or break out lines/segments for each website individually.
* **Save a view**: Set up your desired filters, click **Views** in the top right, and click **Save as view**. Type a name, pick an icon, and click **Save**.
* **Switch to a saved view**: Click **Views** and select any saved view from the list to instantly apply its filters. Choose **Default** (or click the **x** on the active view's name) to go back to the standard unfiltered view.
* **Manage saved views**: Open the **Views** menu, hover over a saved view, and click the three-dot (⋯) kebab menu to access:
* **Edit**: Change the view's name and icon.
* **Update filters**: Overwrite the view's saved filters with whatever filters you currently have active on screen.
* **Set as default** (or **Remove default**): Make this view load automatically when you open the group.
* **Delete**: Permanently removes the saved view.
* **Import filters from a website view**: If an individual website in the group has a saved view you want to reuse, click **+ Add filter** and select **Import from view**. Check the views you want to bring in and click **Import N view(s)**. If the imported view conflicts with your current group filters (e.g., one wants Active prompts, the other wants Paused), you will see a "Some filters conflict" screen where you can review the changes and click **Import anyway** or **Back**.
* **Customize dashboard layout**: Hover over the top-right corner of any card to grab the six-dot handle and drag it to a new position. Grab the bottom-right corner to resize the card.
* **Retry a failed card**: If a card fails to load its data, you will see a "Something went wrong..." message. Click the **RefreshCw (retry) icon** button to try loading it again.
## Data shown
The dashboard displays aggregated mention counts, citation percentages, search positions, and estimated dollar values calculated from the AI model responses tracked across all the websites in the current group. The competitors shown are the top 100 competitors by mention rate across the entire group.
## Common workflows
**Compare current performance to a previous period**
1. Click the **Date Range** filter chip at the top of the dashboard.
2. Select your primary date range (e.g., "Last 30 days").
3. In the "compared to" section, pick a comparison range (or use the "Previous Period" preset).
4. The dashboard cards (like Share of Voice and Mention Rate) will reload to show green/orange badges indicating how your metrics changed between the two periods.
**Scope the dashboard to specific websites or topics**
1. Click the **Websites, Topics & Prompts** filter button.
2. Expand a website to see its topics, or expand a topic to see its prompts. You can also use the search bar to find them quickly.
3. Check the boxes next to the websites, topics, or individual prompts you want to analyze.
4. Click **Apply**. The dashboard will instantly update to show data only for those selections.
**Import a saved view from a single website**
1. Click **+ Add filter** in the filter bar and choose **Import from view**.
2. In the "Import from website view" dialog, you will see a list of saved views from the websites in this group.
3. Check the boxes for the views you want to merge into your group dashboard.
4. Click **Import N view(s)**. If there are conflicting settings (like different models selected), review how they will be resolved and click **Import anyway**.
**Save and reuse a dashboard configuration**
1. Set up your date range, select specific websites/prompts, and add any other filters (like Models or Locations) from the **+ Add filter** menu.
2. Click the **Views** button in the top right.
3. Click **Save as view**, type a name, choose an icon, and click **Save**.
4. The next time you visit the group, you can click **Views** and select this view to restore all your filters instantly.
**Toggle between combined and per-website chart display**
1. Find the **Combine websites** switch located next to the Views dropdown in the filter bar.
2. Click the switch to turn it off. The charts will re-render, breaking out performance metrics to show a separate line or segment for each individual website in your group alongside your competitors.
## Empty, loading, and error states
* **Empty state**: If your selected filters exclude all data (or if the websites in the group have no data yet), the dashboard charts will blur out and display a "No data" message.
* **Loading state**: While the group data is initially loading, a spinning loader icon is centered on the screen. Skeleton outlines of the charts will show while data is being fetched.
* **Error state**: If a specific metric fails to load, its card blurs out and displays "Something went wrong..." with a circular retry button.
## Linked from / links to
* **Linked from**: Accessed by clicking a group name in the left sidebar navigation, or from Market Landscape / group listing pages.
* **Links to**: The "Import from view" dialog references saved views from individual websites.
## Common support questions
**Why can't I see the "Export as CSV" option in my group saved view menu?**
Group saved views contain filters that span multiple websites. The standard CSV exporter only supports single-website exports, so the "Export as CSV" option is deliberately hidden in the group Views menu.
**What does the "Combine websites" toggle do?**
When turned on, the dashboard treats all the websites in your group as one giant brand, combining all their mentions and citations into a single "Group" line or chart segment. When turned off, the dashboard breaks out the data so you can see a separate line or segment for each individual website in the group alongside your competitors.
**Why did some of my competitors disappear from the charts?**
To keep the dashboard fast and readable, the charts cap the competitor list to the top 100 competitors (ranked by how often they are mentioned). If a competitor falls outside the top 100, they will not be drawn on the charts.
**Why can't I edit or delete a group saved view?**
Group saved views can only be edited or deleted by the person who created them, or by a user with Group Admin privileges. If you are a Viewer in the group and did not create the view, those options will be locked.
# Group Billing
Source: https://docs.athenahq.ai/guides/group-id-billing
Lets a group admin/billing-authorized user enable shared billing for a website group, buy or manage credits pooled across that group's websites, and view the group's invoice history.
## Purpose
The Group Billing page allows administrators to manage pooled credits that are shared across a specific group of websites. Instead of buying credits for each website individually, you can purchase group credits that any website in the group can draw from. You can also view past invoices for group-level purchases here.
## What's on the page
**Billing / Group credits header**
Explains that credits are shared across the group. It includes an information icon `(i)` that opens a dialog explaining how group credits work.
**Websites row**
Shows the logos of all the websites included in the group, along with a total count. Hovering over a logo displays the website's name.
**Group credits remaining**
Displays your current group credit usage. If you have both monthly and one-time credits, they are separated into their own cards. Each card shows a progress bar, the number of credits used, the number left, and the date when monthly credits will reset.
**Manage subscription button**
Only visible to customers on specific managed or partner billing plans. This button opens a new tab to manage your subscription directly in the billing portal.
**Add credits button**
Opens a dialog to purchase more one-time or monthly credit packages for the group.
## What you can do here
* **Enable billing:** If the group does not have billing set up yet, you will see an empty state with an **Enable billing** button. Clicking this provisions a billing account for the group so you can start sharing credits.
* **View how group credits work:** Click the info icon `(i)` next to the header to open a dialog explaining credit priority and renewal behavior.
* **Add credits:** Click **Add credits** (or **Add more credits**) to open the purchase dialog.
* Choose between the **One-time** or **Monthly** tab (monthly may be hidden depending on your specific plan).
* Use the **-** and **+** buttons to select the number of credit packages you want to buy.
* Click **Add \[N] credits** to proceed to checkout.
* **Manage subscription:** Click **Manage subscription** to open your external billing portal (if applicable to your plan type).
* **Filter billing history:** Use the **Select month** dropdown above the table to view invoices from a specific month.
* **View an invoice:** Click the link icon in the **Invoice** column to open the full receipt.
## Data shown
* **Group credits:** Drawn from your subscription plan and any add-on credit packages you have purchased specifically for this group.
* **Websites:** The active websites currently assigned to this group.
* **Billing history:** Securely fetched from your Stripe billing account.
## Common workflows
**Purchasing shared credits for a group**
1. Ensure your websites are added to the group.
2. Navigate to the group's Billing tab.
3. If prompted, click **Enable billing**.
4. Click **Add credits** in the top right.
5. Select whether you want the credits to be **One-time** or **Monthly**.
6. Adjust the quantity of packages, review the total cost, and click **Add credits** to complete the purchase.
**Checking why a website is out of credits**
1. Go to the group's Billing tab.
2. Check the **Group credits remaining** section to see if the shared pool is depleted.
3. If the group pool has credits but a specific website cannot run prompts, verify that the website is actually listed in the row of website logos on this page.
## Empty, loading, and error states
* **Empty states:**
* If billing hasn't been set up yet, the page shows a "Group billing not enabled" card.
* If no credits have been purchased yet, the progress bar area shows "No credits purchased for this group yet."
* If the group has never been billed, the Billing history table shows "No invoices yet."
* **Loading states:** While checking your subscription and balances, skeleton placeholders appear where text, progress bars, and amounts will load.
* **Error states:** If enabling billing, purchasing credits, or opening the subscription portal fails, a red error toast appears in the bottom right corner (e.g., "Failed to add credits").
## Linked from / links to
* **Linked from:** The main Group page navigation tabs.
* **Links to:** The Stripe checkout flow (when buying credits), the external billing management portal, and hosted Stripe invoice receipts.
## Common support questions
**Q: Why aren't my group credits being used?**
Website-specific credits are prioritized. A website will always consume its own monthly or one-time credits first. Group credits are only drawn from when a website's individual balance reaches zero.
**Q: Do monthly group credits roll over?**
No. Monthly group credits auto-renew at the start of each billing period. Any unused monthly credits from the previous period do not roll over.
**Q: Why can't I click "Manage subscription"?**
This button is restricted to the organization owner or members with explicit billing administrator privileges. If it is disabled, hover over it to read the specific tooltip explaining why you lack access.
# Competitor Heatmap
Source: https://docs.athenahq.ai/guides/heatmap
Show a matrix of brand vs. competitors across topics with mention/citation percentages so users can spot visibility gaps and drill into specific competitor+topic prompts.
`app.athenahq.ai/heatmap`
## Purpose
The Competitor Heatmap page provides a visual matrix that pits your brand against your tracked competitors across all of your specialized topics. It allows you to quickly spot where your brand is leading the conversation and where competitors are capturing more visibility in AI search responses.
By representing mention and citation rates as color-coded percentage cells, marketers can instantly identify visibility gaps. If a competitor has a dark, high-percentage cell for a critical topic while your brand has a lighter cell, you can click directly into that data point to investigate the exact prompts they are winning.
## What's on the page
**Page Header**
Displays the title "Competitors vs Topics Heatmap."
**Filter Row**
Located just below the header, this toolbar allows you to narrow down the data populating the heatmap. It includes a Saved Views dropdown and multiple filters (Date range, Models, Prompt status, Locations, Countries, Personas, Prompt variation, Prompt tags, Prompts, Owned domains, Mention %, Sentiment %, and Competitors).
**Metric Toggle**
Found on the right side of the filter row, this toggle switches the metric displayed in every cell of the heatmap matrix between **Mention %** and **Citation %**.
**More Options (⋯) Menu**
Located to the right of the metric toggle, this dropdown menu houses additional page actions, specifically the option to export the heatmap.
**Heatmap Matrix**
This is the core visualization of the page. It is a dynamic table featuring:
* **Topic (Row Header):** Lists the topics actively tracked by your brand. Topics with no data for the selected filters are excluded.
* **Brand / Competitor Columns:** The first column defaults to your brand, followed by columns for each tracked competitor (complete with their logo and name).
* **Data Cells:** The intersecting cells display the Mention % or Citation % for that specific topic and entity. The color intensity corresponds to the percentage value (darker colors equal higher percentages).
**Footer Summary Bar**
Located at the bottom of the heatmap matrix, this text bar confirms the total count of topics and competitors currently being displayed (e.g., "Showing 4 topics across 2 competitors").
## What you can do here
* **Switch metrics:** Click the "Mention %" or "Citation %" toggle tabs above the matrix to change the data metric visualized in the heatmap cells.
* **Drill down into specific prompts:** Click any colored data cell in the heatmap. This will navigate you to the Prompts page, automatically filtered to show the specific topic row and competitor column you clicked.
* **Reorder columns:** Click and drag a competitor's column header left or right to reorder the matrix. This also updates the column order in your CSV exports.
* **Pin columns:** Pin a column to keep it anchored to the left while you scroll horizontally through a large list of competitors.
* **Sort by performance:** Click any brand or competitor column header to sort the topic rows by that entity's performance (highest to lowest percentage). Click again to reverse the sort, and click a third time to clear the sorting.
* **Hover for crosshairs:** Hover your mouse over any data cell to highlight its corresponding row and column, making it easier to read across large grids.
* **Export as CSV:** Click the **⋯** (More options) menu in the top right and select **Export as CSV**. This will download the currently filtered heatmap, respecting your custom column order. *Note: Data export is a paid feature. Free-plan users clicking this will see an upgrade prompt.*
* **Add Competitor:** If you have zero competitors set up, click the "Add Competitor" button in the center of the blank state screen to go to the Competitors page.
## Data shown
The heatmap displays aggregated percentage rates (either mentions or citations) for your brand and tracked competitors, categorized by the topics you have configured. The values are drawn from AI model responses over the selected date window. Models tracked include ChatGPT, AI Overviews, Perplexity, Gemini, Copilot, Claude, AI Mode, Grok, and DeepSeek.
## Common workflows
**Spotting and investigating a visibility gap**
1. Open the heatmap and ensure the "Mention %" tab is selected.
2. Scan the rows (topics) to find a cell where your brand's color is noticeably lighter than a competitor's cell.
3. Click the competitor's high-percentage cell.
4. You will be taken to the Prompts page, automatically filtered to show exactly which prompts that competitor is winning for that topic, allowing you to review the AI responses.
**Exporting a localized competitor report**
1. Use the filter bar to select a specific country or location (e.g., "United Kingdom").
2. Drag the column headers to place your most important competitors next to your brand.
3. Click the **⋯** (More options) menu and select **Export as CSV** to download the custom-ordered matrix to share with regional marketing teams.
## Empty, loading, and error states
* **Empty (No Competitors):** If your website has no competitors configured, the page displays a blurred-out mock heatmap with a "No Competitors Yet" overlay. A button prompts you to "Add Competitor."
* **Empty (No Data for Filters):** If your filters are too restrictive (e.g., a date range with zero responses), the matrix disappears and displays "No data available for the selected filters." The footer will read "No topics or competitors to display."
* **Loading:** An animated loading spinner appears in the center of the matrix area while competitor data or heatmap metrics are being fetched.
* **Error:** If the heatmap data fails to load due to a network issue, the matrix gracefully defaults to the standard "No data available" empty state.
## Linked from / links to
* **Linked from:** The main application sidebar under the Competitors section.
* **Links to:** The **Prompts** page (when clicking a data cell) and the **Competitors** page (when clicking "Add Competitor" in the blank state).
## Common support questions
**Why isn't a specific topic showing up on the left side of the heatmap?**
The heatmap is anchored to your brand's strategy. It only displays topics that your brand is actively tracking. If a competitor ranks for a topic that you have not configured for your own brand, it will not appear as a row here.
**Why did a whole competitor column disappear when I added a Mention % filter?**
The Mention % and Sentiment % filters evaluate the entire column. If *none* of a competitor's topics meet the threshold you set, their entire column is hidden to reduce clutter. Note that your own brand's column is protected and will always remain visible.
**Why doesn't anything happen when I click a cell with a dash ("–")?**
A dash indicates that there is absolutely no data (null) for that specific combination of topic and competitor. Because there are no underlying prompts to show you, these empty cells are not clickable.
**Why does it say 0.1% instead of 0%?**
To help differentiate between absolute zero mentions (which may be a tracking gap) and very low visibility, any calculated percentage that is greater than 0 but less than 0.1% is rounded up to display as "0.1%".
**Why does the Export as CSV button ask me to upgrade?**
Exporting data to CSV is a feature reserved for paid subscription plans. If you are on a free plan, the button remains visible so you know the feature exists, but clicking it will open an upgrade dialog.
# Home (Ask Athena chat landing page)
Source: https://docs.athenahq.ai/guides/home
A minimal chat-first landing page where users type or pick a suggested prompt to start a conversation with Athena AI about their brand's AI search presence.
`app.athenahq.ai/home`
## Purpose
The Home page serves as a chat-first landing experience for the application. It provides customers with a clean, focused, search-engine-style interface where they can immediately start asking questions about their brand's AI search performance.
Rather than navigating through complex dashboards to find specific data, users can simply type a question, attach a file, or click a suggested prompt. Submitting a question instantly launches the full Ask Athena conversational AI window to provide answers, insights, and analysis.
## What's on the page
* **Greeting:** A personalized headline that adapts to the user's local time of day ("Morning", "Afternoon", "Evening", or "Up late") and includes their first name if available on their profile.
* **Subtitle:** A dynamic subheading welcoming the user. It explicitly names their currently active workspace ("Ask Athena anything about \[Brand]'s AI search presence").
* **Chat Composer:** The central text input box where users type their questions. It includes a placeholder reading "Ask Athena...".
* **Attachment Previews:** When files are uploaded, they appear as small thumbnail or document cards inside the top of the composer box. Each shows the file name and size, along with an "X" button to remove it.
* **Composer Actions:** A bottom row of tools inside the chat box featuring:
* **Add files or images** (paperclip icon): Opens the device's file browser to upload documents.
* **Start dictation** (microphone icon): Activates the device's microphone to allow voice-to-text input.
* **Send** (up arrow icon): Submits the prompt to the AI.
* **Quick Prompts:** Four rounded suggestion chips located beneath the chat box. These allow users to launch common queries with a single click:
* "How is my brand performing?"
* "Compare my competitors"
* "Which sources cite me the most?"
* "What type of content should I create?"
## What you can do here
* **Send a custom question:** Type your question into the composer and press Enter (or click the Send button). This transitions the screen into the full-screen Ask Athena chat interface with your question already submitted.
* **Use a quick prompt:** Click any of the four suggested prompt chips to immediately launch the AI chat and auto-send that specific question.
* **Attach files:** Click the paperclip icon to upload a file from your computer. You can also drag and drop files directly onto the composer (which brings up a "Drop files here" overlay), or paste copied files/screenshots directly into the text box.
* **Remove an attachment:** Click the "X" on any staged attachment preview card to delete the file before sending your message.
* **Use voice dictation:** Click the microphone icon to begin speaking your question. The system will transcribe your speech into the text box in real-time. Click the microphone again to stop.
## Data shown
* The greeting name is pulled from the user's configured profile information.
* The brand name displayed in the subtitle is drawn from the currently active workspace/website the user has selected.
## Common workflows
**Starting a fresh analysis via chat**
1. Log in or navigate to the Home page.
2. Click the "How is my brand performing?" quick-prompt chip.
3. The interface will transition to the fullscreen Ask Athena chat, and the AI will begin typing out a comprehensive summary of the brand's metrics.
**Uploading a file for the AI to review**
1. Drag a document (like a PDF or spreadsheet) directly from your computer onto the chat composer.
2. Wait a moment for the upload to process; a preview card will appear above the text box.
3. Type a specific question about the file (e.g., "Summarize the key takeaways from this report").
4. Press Enter to submit the file and prompt together.
**Dictating a question on the go**
1. Click the microphone icon inside the composer.
2. Speak your question aloud.
3. Verify the transcribed text in the input box.
4. Click the Send button (up arrow) to submit the question to the AI.
## Empty, loading, and error states
* **Loading:** The page intentionally displays nothing while the app verifies the user's workspace access and subscription status. This prevents the interface from flashing before it is ready.
* **Empty:** There is no "empty" state for this page, as its purpose is to act as a blank canvas for new questions.
* **Errors:**
* **File limits:** If a user uploads an oversized file, a notification appears reading: "\[filename] (\[size]MB) exceeds \[limit]MB limit".
* **Unsupported files:** If a user uploads an unreadable file format, a notification appears reading: "\[filename]: unsupported file type".
* **Upload failures:** Generic upload failures display "Failed to upload \[filename]".
* **Concurrent uploads:** Dropping new files while an existing batch is still uploading shows "Wait for the current upload to finish".
* **Microphone access:** If voice dictation is blocked by the browser, a notification appears reading: "Microphone access denied. Check browser permissions."
## Linked from / links to
* **Linked from:** The main sidebar navigation (labeled "Home"). For many users, this is the default screen they see immediately upon logging in.
* **Links to:** Submitting a prompt or clicking a suggestion chip opens the fullscreen **Ask Athena** chat window overlay.
## Common support questions
**Why did my file upload fail?**
The chat supports specific file types and sizes. Images are capped at 5MB, documents and spreadsheets (like PDFs or CSVs) at 10MB, and plain text files at 2MB. If the file exceeds these limits or is an unsupported format, it will be rejected.
**Why don't I see the microphone button?**
The microphone button only appears if the customer's web browser actively supports media recording and voice transcription features. If they are on an older or unsupported browser, the button is hidden.
# Insights
Source: https://docs.athenahq.ai/guides/insights
Shows a prioritized queue of AI-generated insights and content-opportunity recommendations for growing the website's AI-search visibility, with tools to act on, resolve, or discard each one.
`app.athenahq.ai/insights`
## Purpose
The Insights page shows a prioritized queue of AI-generated insights and content-opportunity recommendations designed to grow your website's AI-search visibility. It acts as a smart to-do list, surfacing material changes in your brand's performance and giving you direct tools to act on, resolve, or discard each opportunity.
By checking your latest data for actionable signals, this page helps you understand what is moving the needle and where to focus your effort next, without requiring you to dig through raw metrics yourself.
## What's on the page
* **Page header**: Displays the "Insights" title, a description tooltip, tabs to toggle between "Insights" and "Content opportunities", and a "Date range" filter.
* **Insights view filter + queue progress**: Shows tabs for "Open", "Done", and "Discarded" insights along with their counts. On the right, a progress bar shows how many queue slots are resolved (e.g., "3/5 resolved") and displays a "Queue full" pill if your active queue is at capacity.
* **Insight cards list**: A stacked list of insight cards.
* **Left side**: Shows priority (a 3-segment colored bar indicating impact vs. effort), a category badge, the insight title, a description, and a "Supporting Data" toggle button.
* **Right side**: Shows an "Action" checklist. You can tick off steps, add new ones, and use the "Mark done", "Ask Athena", or overflow ("...") buttons.
* **Content opportunities grid**: Visible when the "Content opportunities" tab is selected. This is a two-column grid grouping recommendations into "In progress" and "To do". It includes collapsible sections for "Lower priority", "Filtered out by date", "Completed", and "Deleted" opportunities.
* **Discard insight dialog**: A modal that appears when you choose to discard an insight, capturing a reason via radio buttons (e.g., "Not relevant to my business") and an optional free-text explanation.
* **Discard recommendation dialog**: A modal for discarding a content recommendation, asking for a reason and detailing what will happen to any linked generated content (e.g., whether it will be hidden or stay in your content grid).
## What you can do here
* **Check for new insights**: In the empty state, click **Check for new insights** to scan your latest data for material changes. The app will show a loading state and toast the outcome.
* **Switch tabs**: Click **Insights** or **Content opportunities** in the header to switch between the two queues.
* **Filter by view**: Click the **Open**, **Done**, or **Discarded** pills to change which subset of insights is displayed.
* **Filter by date**: Click the **Date range** button to filter visible insights (by period) and content opportunities (by first-seen date).
* **View supporting data**: On an insight card, click **Supporting Data (n)** to flip the left panel and see the underlying data points backing the insight. Click **Back** to return to the description.
* **Toggle action checkbox**: Click the checkbox next to an action item to mark it complete. Ticking the last item off prompts you to mark the whole insight as done.
* **Edit action text**: Click on an existing action item's text to edit it inline.
* **Add action**: Click **Add action** at the bottom of the checklist to write a custom step for the insight.
* **Delete action**: Hover over an action item and click the **X** icon to remove it (destructive).
* **Mark done**: Click **Mark done** on an insight card to resolve it, moving it from the Open queue to the Done tab.
* **Ask Athena**: Click **Ask Athena** on an insight card to open the chat panel, pre-filled with a prompt to help you implement the insight's remaining actions.
* **Discard (Insight)**: Click the **...** (More actions) menu on an open insight and select **Discard** to remove it. Submitting the dialog moves it to the Discarded tab.
* **Restore (Insight)**: On the Discarded tab, click the **...** menu on a card and select **Restore** to move it back to the Open queue.
* **Start (Content opportunity)**: Click **Start** on an un-started opportunity to kick off content generation. This navigates you to the Content page.
* **Continue (Content opportunity)**: Click **Continue** on an in-progress opportunity to jump back into the draft on the Content page.
* **Discard (Content opportunity)**: Click **Discard** to remove an un-started opportunity.
* **Delete (Content opportunity)**: For an in-progress opportunity, open the **...** menu and select **Delete** to discard it.
* **Restore (Content opportunity)**: Expand the "Deleted" section, click the **...** menu on a card, and select **Restore** to bring it back to the active queue.
* **Expand/collapse sections**: Click the headers for **Lower priority (n)**, **Filtered out by date (n)**, **Completed (n)**, or **Deleted (n)** to reveal hidden content opportunities.
* **Retry**: Click **Retry** if the page encounters an error loading your insights.
## Data shown
* **Insights**: Proactive observations generated automatically from your website's tracked prompts, competitors, and historical content performance.
* **Generation run history**: Context about your latest check, explaining what was reviewed, what was skipped (and why), and when the last check occurred.
* **Content opportunities**: Recommendations for creating or optimizing content, scored based on potential impact, urgency, and topic coverage.
* **Generated content**: Any drafts, briefs, or published articles that are linked directly to your content recommendations.
## Common workflows
**Check for and resolve a new insight**
1. Navigate to the Insights page. If your queue is empty, click **Check for new insights**.
2. Wait for the scan to finish; a toast will notify you if new insights were found or if no material changes occurred.
3. Review a new insight card in the Open view. Check off action items as you complete them, or click **Add action** to create your own steps.
4. When you tick off the final action item, a prompt will ask "Mark this insight as done?".
5. Click **Mark done** to confirm and move the insight to your Done tab.
**Act on a content opportunity via Ask Athena**
1. Make sure you are on the Insights tab.
2. Find an insight you want to tackle and click **Ask Athena**.
3. The chat panel will open, pre-filled with a prompt detailing the insight's remaining action items.
4. Chat with Athena to execute the steps. Athena can mark actions complete as you progress.
**Start and discard a content opportunity**
1. Switch to the **Content opportunities** tab in the page header.
2. Find an opportunity under "To do" and click **Start**. Content generation will begin and you'll be routed to the Content page.
3. If you decide you don't want to finish it, return to the Insights page, locate the in-progress card, click the **...** menu, and select **Delete**.
4. Choose a reason in the Discard recommendation dialog and click **Discard**.
5. If you change your mind later, expand the **Deleted (n)** section, click the **...** menu on the card, and select **Restore**.
## Empty, loading, and error states
* **Empty**: If there are no open insights, you will see a "No active insights" message over blurred placeholder cards. It will describe the last check (e.g., "We reviewed 5 signals: 1 change was too small to act on"). If eligible, a "Check for new insights" button is shown. On the Content opportunities tab, an empty queue displays "All caught up. No content opportunities right now. Check back soon."
* **Loading**: While fetching data, skeleton insight cards (gray pulsing shapes) are displayed. For content opportunities, skeleton grid cards appear.
* **Error**: If loading fails, a "Failed to load insights" message is displayed along with the specific error text and a **Retry** button.
## Linked from / links to
* **Linked from**: The main sidebar navigation (Insights), and content recommendation deep links that route through the Content page back to here.
* **Links to**: The Content page (when clicking Start or Continue on a recommendation), and the Ask Athena chat panel (when clicking Ask Athena on an insight).
## Common support questions
**Why can't I see the "Check for new insights" button?**
Insights require historical data to spot trends. The button will not appear until your website's first data run finishes. It may also be hidden if you have open insights that are currently filtered out by your Date Range setting (to prevent you from exceeding the maximum queue size).
**What do the colored bars on the insight card mean?**
The bars indicate the priority of the insight based on a combination of potential impact and required effort. Three green bars indicate the best opportunities (high impact and low effort). Fewer bars (yellow or red) mean the insight requires higher effort or offers lower relative impact.
**Why is my queue full?**
The Open insight queue is capped at 5 insights per website, and the active Content opportunities queue is capped at 10. To generate new insights or recommendations, you must first clear space by marking existing items as Done, or Discarding them.
**What happens to my generated drafts if I discard a content opportunity?**
Nothing is permanently deleted. If the content was already published or marked as completed, it stays in your content grid. If it was a never-published draft or brief, it will be hidden from your main content grid so it doesn't clutter your workspace. You can always restore the opportunity later to bring the draft back.
**Why is the "Ask Athena" button disabled?**
The "Ask Athena" button requires your organization to have Ask Athena access included in your subscription plan. If you are on a plan that does not include it, the button will be grayed out and show an upgrade tooltip on hover.
# Knowledge Base
Source: https://docs.athenahq.ai/guides/knowledge-base
Central workspace for building, curating, and verifying a website's AI-answer knowledge base: pillars (topics), source claims/facts, internal link bank, and unfiled facts.
`app.athenahq.ai/knowledge-base`
## Purpose
The Knowledge Base is the central workspace for building, curating, and verifying the facts and claims that Athena uses to understand your brand. It organizes your company's verified information into categories called "Pillars" (topics), tracks the web pages and documents those facts were extracted from, and manages "unfiled" facts that haven't been categorized yet.
By managing your Knowledge Base here, you ensure that any content Athena generates or analyzes is grounded in accurate, approved truth about your products, services, and positioning.
## What's on the page
### Page Header
* **Page Title:** "Knowledge Base".
* **Review N pending:** A conditional button that only appears if you have claims awaiting review. Clicking it takes you to the dedicated review queue.
* **Verify facts:** A button to cross-check your approved facts against AI responses Athena has collected to flag contradictions.
* **Add knowledge (+):** A dropdown menu with options to add new information to your workspace.
* **Progress Overlays:** Floating cards in the bottom right corner showing the real-time progress of active research tasks (like "Discovering pillars" or "Verifying facts").
### Pillars Tab
A table organizing your knowledge base into major topics.
* **(Checkbox):** Selects the pillar for bulk actions.
* **Pillar:** The name and description of the topic. If there are facts waiting for human approval, a "\[N] pending" badge appears here. Clicking the pillar name opens its detailed view.
* **Content coverage:** A progress bar and percentage showing how many of this pillar's approved claims are currently covered by your existing published content. A tooltip explains: "Percentage of a pillar's claims covered by your existing content".
* **Duplicate pillars callout:** A warning banner that appears if the system detects multiple pillars with the exact same name, offering a quick way to combine them.
### Internal Links Tab
A table of all the web pages you have added or crawled to extract facts.
* **(Checkbox):** Selects the link for bulk actions.
* **URL:** The web address of the page (links out to the actual page).
* **Title:** The title of the page, if successfully scraped.
* **Claims:** The number of facts Athena extracted from this specific link. Clicking this number opens a details panel.
* **Status:** The current processing state of the link (e.g., Finished, Researching, Pending, Scraped, Failed).
### Unfiled Facts Tab
This tab only appears if you have approved facts that are *not* attached to any published pillar.
* **Search bar:** Allows you to find specific unfiled facts by keyword.
* **Source filters:** Tabs to filter the list by where the fact came from (All, Research, Uploads, Content hub).
* **Fact list:** Displays the fact text, a badge showing its origin (e.g., "Upload"), its confidence level, the date it was added, and a link to the source if available.
* **Usage chip:** If a fact was used to write an article, a "Used in N articles" badge appears. Hovering over it reveals links to the generated content.
* **Delete all N:** A button to instantly wipe out all unfiled facts matching your current search/filter.
## What you can do here
### Top-Level Actions (Header)
* **Verify facts:** Opens a dialog to pick specific pillars and run a validation check against third-party AI responses.
* **Add knowledge -> Create pillar:** Opens a dialog to manually name and describe a new pillar. You can check "Auto-research" to have Athena immediately hunt for facts to fill it.
* **Add knowledge -> Discover pillars:** Instructs Athena to scan your website and automatically suggest and build pillars for you.
* **Add knowledge -> Add URLs:** Opens a dialog where you can paste specific web addresses or enter a domain to crawl. You can choose whether to just add them to the link bank, or also extract claims from them.
* **Add knowledge -> Upload document:** Opens a dialog to extract facts by uploading a PDF/DOCX file or pasting raw text.
* **Add knowledge -> Extract from Content Hub:** Opens a list of your published articles, allowing you to select pieces to extract facts from. (Note: This consumes credits).
### Pillar Bulk Actions
Select one or more checkboxes in the Pillars table to reveal the command bar at the bottom of the screen:
* **Edit:** (Only visible when exactly one pillar is selected) Rename or change the description of the pillar.
* **Refresh:** Tells Athena to re-evaluate the pillar, re-associate relevant links, and regenerate its underlying synthesis document.
* **Export CSV:** Downloads all claims inside the selected pillars as a spreadsheet.
* **Merge:** (Visible when 2+ pillars selected) Opens a dialog to combine the selected pillars into one. You must choose a published pillar as the "target" to keep. The others are deleted and their facts are moved over.
* **Delete:** Permanently removes the selected pillars *and every fact filed under them*.
* **Verify facts:** A shortcut to run a verification check specifically on the selected pillars.
* **Reset:** Clears your checkbox selection.
### Internal Link Bulk Actions
Select checkboxes in the Internal Links table to reveal the command bar:
* **Refresh:** Re-scrapes the selected URLs and extracts any new facts that might have been added to the page.
* **Delete:** Opens a confirmation dialog. **Crucial note:** Deleting a link *cascades* and deletes every fact that was sourced from that link. The confirmation dialog will show you a preview of exactly which facts (grouped by pillar) are about to be destroyed.
* **Reset:** Clears your selection.
### Unfiled Facts Actions
* **Delete all N:** Permanently deletes all unfiled facts that match your current filter.
* Select rows -> **Move to pillar:** Opens a dropdown to pick a published pillar to file these facts under.
* Select rows -> **Delete:** Permanently deletes the selected facts.
### Pillar Details (Drilldown)
Clicking a pillar's name opens a large dialog managing that specific topic.
* **Pillar options (⋯ menu):** Found in the top right. Contains **Edit**, **Refresh**, **Export claims (CSV)**, and **Delete**.
* **Add knowledge (+ menu):** Opens the Add knowledge flow pre-scoped to this pillar. Includes an extra **Import CSV** option to bulk-upload facts from a spreadsheet.
* **Claims tab:** Lists all facts inside the pillar. You can filter by Status (Pending, Approved, Rejected).
* **Per-claim actions:** Hover over a claim to reveal a menu allowing you to **Approve**, **Reject**, **Delete**, **Mark as pending**, **Change pillar**, or **Edit fact**.
* **Bulk claim actions:** Select checkboxes next to claims to reveal a command bar to bulk **Approve**, **Reject**, **Delete**, **Mark as pending**, or **Change pillar**.
* **Approve all pending:** A quick button to approve every pending fact in the pillar.
* **Sources tab:** Shows a list of every page or document that contributed approved facts to this pillar. Clicking a source filters the Claims tab to only show facts from that specific origin.
### Source Link Details (Drilldown)
Clicking the number in the "Claims" column on the Internal links tab opens this view.
* **Linked pillars:** Shows which pillars this page is associated with.
* **Facts sourced from this link:** Lists every specific claim extracted from the URL. You can hover over any fact and click the trash can icon to **Delete fact** individually.
## Data shown
* **Pillars (Topics):** The thematic categories your brand's information is grouped into.
* **Claims (Facts):** The atomic pieces of verified information about your business. These come from web research, manual entry, file uploads, or scraped pages.
* **Internal Links:** The library of tracked web pages Athena uses as source material.
* **Content Coverage:** A metric showing how effectively your marketing content is utilizing the approved facts you've gathered in your Knowledge Base.
* **Active Runs:** Live status tracking for background jobs like website discovery, pillar research, or fact verification.
## Common workflows
**Discovering your Knowledge Base from scratch:**
1. Land on the empty Knowledge Base page and click **Discover pillars**.
2. Confirm the prompt to start research.
3. Watch the "Discovering pillars" overlay in the bottom right as Athena scans your site.
4. Once complete, click into the newly created pillars to review and approve the extracted facts.
**Adding a specific PDF or document:**
1. Click the **Add knowledge** dropdown and select **Upload document**.
2. Upload your PDF or DOCX file (or paste raw text).
3. Click **Extract claims**. Athena will process the text and add the new facts to your unfiled list (or directly to a pillar if you started from inside a Pillar Detail view).
**Cleaning up duplicate pillars:**
1. If Athena detects pillars with the exact same name, a yellow "Duplicate pillars" banner appears on the Pillars tab.
2. Click **Merge duplicates**.
3. Review the list of duplicates that will be combined.
4. Click **Merge N duplicates** to automatically fold them into their original pillars.
**Reviewing and categorizing Unfiled Facts:**
1. Go to the **Unfiled facts** tab.
2. Read through the facts. Check the boxes next to facts that belong together.
3. In the command bar that appears, click **Move to pillar**.
4. Select the appropriate published pillar to file them under.
## Empty, loading, and error states
* **Empty:** If you have absolutely no pillars, links, or unfiled facts, you will see a "No knowledge yet" screen with a large "Discover pillars" button. If a discovery run is actively happening, this is replaced with a "Discovering pillars" live status screen.
* **Loading:** When data is fetching, the page displays gray skeleton placeholder rows.
* **Error:** If the system fails to load data inside a dialog (like a pillar's claim list), it shows a "Couldn't load claims" message with a "Try again" button. This prevents users from confusing a network error with an empty pillar.
## Linked from / links to
* **Linked from:** The main sidebar navigation.
* **Linked from:** The Oracle page (users are redirected here when managing fact verification).
* **Links to:** `/knowledge-base/review` (via the "Review N pending" button).
* **Links to:** External source URLs open in a new browser tab.
* **Links to:** The Content editor, via the "Used in N articles" hover chip on individual claims.
## Common support questions
**"Why did my facts disappear when I deleted a link?"**
Internal links act as the foundation for the facts extracted from them. If you delete a URL from your Internal Links tab, every single fact that was sourced *exclusively* from that page is permanently deleted along with it. The system will show a warning preview of exactly what facts will be destroyed before you confirm.
**"I can't find the Unfiled Facts tab anymore."**
The Unfiled Facts tab automatically hides itself when there are zero unfiled facts in your workspace to keep the interface clean.
**"I'm trying to merge two pillars but the 'Merge' button is disabled."**
To merge pillars, at least one of the selected pillars must have a "Published" status. You cannot merge a group of pillars if they are all still in "Draft" or "Archived" status because there is no valid target to keep.
**"I see the Delete button, but when I click it, it says I don't have permission."**
While all users with Knowledge Base access can view the Delete buttons, only users with Organization Admin privileges can actually delete claims, pillars, or internal links. This is a safety measure to prevent accidental data loss.
**"Why am I being asked to upgrade when I click Export CSV?"**
Exporting your Knowledge Base data to a spreadsheet is a premium feature. If your workspace is on a free plan, clicking Export will prompt you to view upgrade options.
# Knowledge Base Pillar Detail
Source: https://docs.athenahq.ai/guides/knowledge-base-pillarId
Detail page for a single Knowledge Base pillar (topic), where users review/manage its claims, sources, associated pages, generated document, and matching content.
`app.athenahq.ai/knowledge-base`
## Purpose
The Knowledge Base Pillar Detail page gives you a dedicated workspace to manage a single topic (pillar) in your knowledge base. It allows you to review the individual facts (claims) that make up the pillar, track where those facts came from, and see how they are being used across your generated content and existing website pages.
This page is central to the review and curation workflow. You can manually add new facts, approve or reject AI-extracted facts, organize sources, and generate a readable summary document for the entire topic.
## What's on the page
* **Header**: Shows a back link to the main Knowledge Base, the pillar's title and description, and when it was last researched.
* **Status dropdown**: Lets you view and change the pillar's status (Draft, Published, Researching, Archived).
* **Options menu (⋯)**: A menu in the top right corner for editing the pillar's details, regenerating its document, exporting its facts, or deleting the pillar entirely.
* **Claims tab**: Displays a list of all facts belonging to this pillar as cards. Each card shows the fact text, where it came from (source chip), its review status (Approved, Rejected, Pending review), confidence level, how many generated articles use it, and when it was added or reviewed. A duplicate badge also appears if the fact is similar to an existing one.
* **Sources tab**: Lists all distinct sources (like specific URLs, uploads, or AI responses) that provided approved facts for this pillar, along with a count of facts from each.
* **Associated pages tab**: Shows pages from your website that are linked to this pillar, sorted by how well they match.
* **Document tab**: Renders the readable markdown document generated from this pillar's approved facts.
* **Matching articles tab**: Lists existing content on your website that covers this pillar's claims, showing a match percentage and the number of matching claims for each article.
* **Add claim button**: A floating button in the bottom right to manually add a new fact to the pillar.
**Tooltips and badges:**
* **Duplicate**: "Same claim as another one in your knowledge base. Only the original is used in content."
## What you can do here
**Pillar Actions:**
* **Change status**: Use the dropdown in the header to change the pillar's status to Draft, Published, Researching, or Archived.
* **Edit**: Inside the header options menu (⋯), opens the "Edit pillar" dialog to update the title and description.
* **Regenerate**: Inside the header options menu (⋯), rebuilds the pillar's document from its currently approved facts.
* **Export facts (CSV)**: Inside the header options menu (⋯), downloads all facts in this pillar as a spreadsheet.
* **Delete**: Inside the header options menu (⋯), permanently removes the pillar and all its facts. You will be asked: "Are you sure you want to delete this pillar?"
**Tab Actions:**
* **Generate document**: If no document exists on the Document tab, clicking this generates one for the first time.
* **Find matching pages**: On the Associated pages tab, starts a scan of your website to find pages that match this pillar.
* **Filter by source**: Clicking a row in the Sources tab switches to the Claims tab and filters it to show only approved facts from that specific source. Click the "X" on the "Source: ... · approved only" chip to clear the filter.
* **View claim usage**: Hovering over a "Used in N articles" chip on a fact card reveals a list of content articles grounded by that fact. Clicking an article name opens it in the content editor.
* **View claim evidence**: Clicking the text of a fact card opens the "Claim" dialog, which displays the full fact text, the exact quote from the source (if available), the source link, confidence level, and a "View AI response →" link if the fact came from an AI interaction.
* **Open source**: Clicking the arrow icon on a row in the Sources tab, or clicking an article in the Matching articles tab, opens the external webpage in a new browser tab.
**Fact Actions (inside the ⋯ menu on each fact card):**
* **Approve**: Approves a pending fact into the pillar.
* **Reject**: Rejects a pending or approved fact so it stops feeding content generation. Rejecting an approved fact asks: "Reject this claim? It stops feeding content generation and won't be re-imported by future research runs."
* **Mark as pending**: Moves an approved or rejected fact back to the pending review queue.
* **Edit fact**: Opens the "Edit fact" dialog to modify the fact text, source URL, and confidence level.
* **Change pillar**: Opens the "Change pillar" dialog to reassign the fact to a different published pillar.
* **Delete**: Permanently removes the fact from your knowledge base.
## Data shown
* **Pillar details**: The name, description, status, and generated document for the topic.
* **Claims**: The individual facts, stats, and sources extracted or manually added for this topic.
* **Coverage**: Data connecting your existing website pages and generated content articles to the facts in this pillar.
## Common workflows
**Reviewing pending facts:**
1. Open a pillar and stay on the **Claims** tab.
2. Look for cards with a yellow "Pending review" badge.
3. Click the **⋯** menu on the card and select **Approve** or **Reject**.
4. A toast notification will confirm the action, and the pillar's totals will automatically update.
**Manually adding a fact:**
1. Click the floating **Add claim** button on the bottom right.
2. In the dialog, enter the fact text and an optional source URL.
3. Click **Save**. The new fact will be added to the list and automatically marked for usage.
**Filtering facts by a specific source:**
1. Click the **Sources** tab.
2. Find the source (like a specific blog post URL) and click anywhere on the row.
3. The view will switch back to the **Claims** tab, showing only the approved facts derived from that source.
4. Click the **X** on the filter chip at the top to see all facts again.
## Empty, loading, and error states
* **Loading**: While data is being retrieved, skeleton placeholders appear for the header text, tabs, and content rows.
* **Empty claims**: If the pillar has no facts, the Claims tab shows "No claims yet. Add claims below or run pillar research." Filtering by a source with no facts shows "No facts from this source."
* **Empty sources**: The Sources tab shows "No sources yet" along with "Sources appear when this pillar has approved facts."
* **Empty associated pages**: The Associated pages tab shows "No pages linked yet" along with a button to "Find matching pages."
* **Empty document**: The Document tab shows "No document generated yet" and a "Generate document" button.
* **Empty matching articles**: The Matching articles tab shows "No matching articles found."
* **Error**: If the pillar has been deleted or the URL is invalid, the page displays "Pillar not found." with a link "Back to Knowledge Base."
## Linked from / links to
* **Linked from**: The Knowledge Base list page, and deep links from the content editor's research sidebar.
* **Links to**: The main Knowledge Base page (via the back link), the content editor (via fact usage chips), and external source URLs.
## Common support questions
**Why is the "Export facts (CSV)" button asking me to upgrade?**
Exporting knowledge base data is a premium feature. If you are on a free plan, clicking this button will present a subscription plan upgrade dialog instead of downloading the file.
**Why don't all facts show up when I click a source in the Sources tab?**
Clicking a source filters the Claims tab to show only *approved* facts from that source. Any pending, rejected, or duplicate facts from that source are hidden while the filter is active.
**What does the "Duplicate" badge mean?**
It means the system detected that this fact is essentially saying the same thing as another fact already in your knowledge base. To prevent repetition, only the original fact is fed into content generation.
**I accidentally rejected an approved fact. How do I get it back?**
When you reject a fact, a toast notification appears with an "Undo" button. Clicking "Undo", or selecting "Mark as pending" from the fact's kebab menu, will return it to the pending queue where you can approve it again.
**Why are "Regenerate" and "Generate document" disabled?**
These buttons are disabled if the pillar contains zero facts, or if a document generation process is already running in the background.
# Review pending claims
Source: https://docs.athenahq.ai/guides/knowledge-base-review
Lets a Knowledge Base user triage all AI-extracted claims that need human approval before they can count toward published pillars, with per-claim and bulk approve/reject/delete/assign actions.
`app.athenahq.ai/knowledge-base/review`
## Purpose
This page allows users to triage AI-extracted facts (claims) before they are officially added to their Knowledge Base. Athena holds back certain claims for manual review if it cannot independently verify them, such as low-confidence extractions, claims from third-party sources, or comparisons against competitors.
Support agents can guide users here to actively manage their brand's truth by approving valid claims into pillars, rejecting incorrect claims, or deleting facts they don't want stored.
## What's on the page
### Page header and intro
* **Page title**: "Review pending claims" with a "Back to Knowledge Base" link.
* **Intro copy**: Explains why claims require human review. If the queue is larger than one page, it displays the current pagination range (e.g., "Showing 1–100 of 250.").
### Filter bar
* **Confidence tabs**: Filters the queue by Athena's extraction confidence (All, High, Medium, Low).
* **Source tabs**: Filters the queue based on where the claim was found (All sources, Web research, AI responses, Uploads, Your site).
* **Selection toolbar**: Appears automatically on the right side of the filter bar when one or more claims are selected. It displays the selected count and provides bulk action buttons (Clear, Approve, Reject, Delete).
### Pending claims list
The main interface is a stacked card listing all claims on the current page.
* **Select all row**: A header bar with a checkbox to select all visible claims. It also shows a count of how many claims on the page are "reviewable" versus "without pillar."
* **Select-all-matching banner**: If a user selects all visible rows on a page but more claims match their current filters on other pages, a banner appears offering to "Select all \{N} matching claims".
* **Claim row**: Each individual row represents a single fact awaiting review, alongside its associated metadata and action buttons.
**Pending claims list row elements:**
* **Select**: A checkbox to include the claim in a bulk action.
* **Claim text**: The extracted fact or statement.
* **Pillar**: A clickable link to the assigned pillar (topic). If the claim isn't filed yet, this shows an **Assign a pillar** button instead.
* **Confidence**: A badge indicating the AI's confidence in the extraction (e.g., "High confidence").
* **Source**: A badge labeling the claim's origin (Web research, AI response, Upload, Your site, Manual).
* **Source link**: An external link labeled "Source" that opens the original web page, if available.
* **Source quote**: A verbatim snippet of text from the source that supports the claim.
* **Row actions**: Quick-action buttons to Approve (✓), Reject (✕), or Delete (🗑) the individual claim.
### Pagination footer
Shows the current page number and total pages, with **Previous** and **Next** buttons to navigate through the queue.
### Assign a pillar dialog
A modal that appears when a user clicks "Assign a pillar" on an unfiled claim. It contains a searchable dropdown to select an existing published pillar so the claim can be approved.
## What you can do here
* **Filter claims**: Click any Confidence or Source tab to narrow down the queue. Changing filters resets your current selection and returns you to page 1.
* **Select claims**: Check individual boxes, use the header checkbox to "Select all visible claims", or click the banner link to "Select all \{N} matching claims" across the entire filtered queue.
* **Approve claims (bulk)**: Click the **Approve** button in the selection toolbar. This approves all selected claims into their respective pillars. Tooltips explain why this might be disabled:
* *"Approve works on the selected page only, because each claim is approved into its own pillar."*
* *"Approve \{N} claims across \{X} pillars"*
* *"\{N} selected claims can't be approved without a pillar"*
* **Reject claims (bulk)**: Click **Reject** in the toolbar to hide selected claims and block them from future re-import. If rejecting the whole queue, it asks for confirmation ("Reject all \{N} matching claims?"). A success toast appears with an **Undo** option.
* **Delete claims (bulk)**: Click **Delete** in the toolbar to permanently remove selected claims. It prompts for confirmation, noting that deleted claims might be re-imported by future research runs.
* **Clear selection**: Click the **Clear** button in the toolbar, click "Clear selection" in the banner, or press the `Escape` key on your keyboard.
* **Approve/Reject/Delete (single)**: Use the small icon buttons on the right side of any row to take action on just that claim.
* **Assign a pillar**: Click **Assign a pillar** on a row that lacks one. Select a published pillar from the dropdown and click **Assign**.
* **Navigate pages**: Click **Previous** or **Next** at the bottom of the page.
## Data shown
The page displays pending (unreviewed) facts extracted for the active website. The data is pulled directly from the user's Knowledge Base queue. The "Assign a pillar" dropdown displays published pillars the user has already created for this website.
## Common workflows
**Approving valid claims:**
1. Filter the queue by "High" confidence.
2. Review the visible claims. If they look accurate, click the header checkbox to select all visible claims.
3. Click **Approve** in the selection toolbar.
4. The claims are moved into their assigned pillars and the next page of claims loads.
**Mass rejecting incorrect claims:**
1. Filter the queue by "Low" confidence.
2. Click the header checkbox to select all visible claims.
3. A banner appears. Click **Select all \{N} matching claims**.
4. Click **Reject** in the selection toolbar.
5. Confirm the action in the dialog to reject all low-confidence claims at once.
**Filing an unassigned claim:**
1. Locate a claim that says "Assign a pillar". (The Approve button will be disabled).
2. Click **Assign a pillar**.
3. In the dialog, select a relevant published pillar from the dropdown.
4. Click **Assign**.
5. The row updates with the new pillar name, and the Approve button is now enabled.
## Empty, loading, and error states
* **Empty**: If the queue is totally empty, it shows "Nothing to review. All extracted claims have been reviewed." If filters are active but yield no results, it shows "No pending claims match these filters. Try different filters."
* **Loading**: Displays gray skeleton placeholder rows while fetching the claims list.
* **Error**: Actions that fail (like a failed bulk deletion) will trigger a red error toast. If a mass reject/delete operation is interrupted because another user or background process is mutating the same rows, a yellow warning toast explains how many claims were successfully processed and asks the user to try again for the remainder.
## Linked from / links to
* **Linked from**: The Knowledge Base main page (usually via a "Review \{N} pending" banner/button).
* **Links to**: The Knowledge Base main page (via the back button). Clicking a pillar name takes the user to the Pillar detail page (`/knowledge-base/{topicId}`). Clicking "Source" opens the original third-party web page in a new tab.
## Common support questions
**Why is the Approve button disabled for some claims?**
A claim cannot be approved until it has a designated home in the Knowledge Base. If a claim lacks a pillar, the user must click "Assign a pillar" to file it before they can approve it.
**Why can't I bulk approve all matching claims across the whole queue?**
The "Approve" action is restricted to the current page's selection. Because claims are approved into specific individual pillars, the system only processes them in visible batches. Users can mass reject or mass delete across the whole queue, but approvals must be done page-by-page.
**What is the difference between rejecting and deleting a claim?**
Rejecting a claim hides it and tells the AI never to import that specific fact again. Deleting a claim removes it entirely, which frees up space, but means the AI might re-import the exact same fact during a future web research run if it finds it again.
**I accidentally rejected a batch of claims. Can I get them back?**
Yes. Immediately after rejecting claims, a success toast appears at the top of the screen with an **Undo** button. Clicking this restores the claims back to the "pending" review queue.
# Olympus (Dashboard)
Source: https://docs.athenahq.ai/guides/olympus
The main analytics dashboard for a website, showing customizable cards on brand visibility, share of voice, citations, sentiment, and business value in AI search results.
`app.athenahq.ai/olympus`
## Purpose
Olympus is the central analytics dashboard for a website's AI search performance. It provides high-level and detailed views of how often the brand is mentioned, cited, and perceived across AI models, and translates that visibility into estimated business value.
Customers use this page to monitor their overall Share of Voice compared to competitors, spot trends over time, identify content gaps, and quantify the return on their optimization efforts in AI search.
## What's on the page
**Filter Row**
* **Views Dropdown**: Lets users load saved filter combinations.
* **Filter Chips**: Contextual filters to narrow the dashboard data by Date Range, Models (e.g., ChatGPT, Claude, Perplexity), Competitors, Topics & Prompts, Personas, Locations, etc.
**Stat Cards (Top Row)**
* **Responses Analyzed**: Total AI responses analyzed across the active filters.
* **Sources Tracked**: Number of unique sources cited in the filtered AI responses.
* **Attributed Citations**: The percentage and raw count of responses that cite the brand's tracked content.
**Dashboard Grid (Modular Cards)**
Users can customize which cards appear here. The available cards include:
* **Share of Voice**: A donut chart and ranked list showing how often AI mentions the brand versus competitors.
* **AI Search Value**: A gauge showing what the brand's presence in AI answers is worth (estimated in dollars), alongside "Headroom to grow" and a "Driven by Athena" attribution stat.
* **Share of Voice by Model**: A bar chart showing the brand's visibility on each individual AI model.
* **Daily Share of Voice**: An area chart tracking daily Share of Voice trends over time.
* **Mention Rate**: An area chart tracking the brand's mention rate vs. competitors.
* **Position over Time**: An area chart tracking the brand's average ranking position in AI responses.
* **Citation Rate**: An area chart tracking how often AI cites the brand's content compared to competitors.
* **Sources Visualization**: A Sankey diagram showing which sources drive AI brand mentions vs competitor mentions.
* **Attributed Citations Growth**: A chart tracking the growth of citations to tracked content over time.
* **Top Attributed Content**: A list of the brand's tracked source URLs most frequently cited by AI models.
* **Most Cited Content**: A list of the top pages from the website appearing in AI responses (regardless of whether they are actively tracked).
* **Competitor Heatmap**: A grid comparing the brand's visibility against competitors across all tracked topics.
* **Positive Brand Traits**: A radar/bar chart showing the distribution of positive traits AI associates with the brand.
* **Negative Brand Traits**: A radar/bar chart showing the distribution of negative traits AI associates with the brand.
* **Dollar Value Captured**: Estimated advertising value captured from AI presence compared to the equivalent ad value.
* **What's Working**: A preview card highlighting the top content performance win detected after an optimization.
## What you can do here
* **Filter data**: Click any filter chip (or "Add filter") to scope the dashboard.
* **Start a tour**: Click the small info icon next to the "Olympus" page title to launch an interactive tour.
* **View Metric Methodology**: Click the small "ⓘ" (info) icon on any individual card to open a detailed dialog explaining how that specific metric is calculated, along with its formula.
* **Export as PNG**: Inside the header Export (Download) menu, select "Export as PNG" to download images of the currently visible dashboard cards in a ZIP file.
* **Export as CSV**: Inside the header Export (Download) menu, select "Export as CSV" to download the underlying metric data. *(Note: On Free plans, this is gated and opens an upgrade dialog instead).*
* **Manage reports**: Inside the header "More actions" (⋯) menu, click "Manage reports" to open a modal where you can create, edit, or delete scheduled recurring email/Slack reports.
* **Customize Dashboard (Dashboard settings)**: Inside the header "More actions" (⋯) menu, click "Dashboard settings". This opens a modal where you can toggle which cards are visible, drag them to reorder, or click "Reset" to restore defaults.
* **Resize a card**: Hover over a card's bottom-right corner and drag the resize handle to make the card span multiple columns or rows.
* **Reorder a card**: Hover over a card's top-right corner and use the grip handle (six dots) to drag and drop it into a new position.
* **Toggle Mention Rate (Relative/Absolute)**: On the Mention Rate card, click the toggle to switch between measuring share out of *relevant* responses vs. *all* responses.
* **Toggle AI Search Value (Monthly/Annual)**: On the AI Search Value card, click the toggle to view the dollar amounts as a monthly or annual figure.
* **Toggle Cohorts**: On time-series charts (Mention Rate, Citation Rate, Position over Time), click "Show Cohorts" / "Hide Cohorts" to display vertical dashed lines representing dates when new prompts were added.
* **Download Heatmap CSV**: On the Competitor Heatmap card, click the download icon to export specifically the heatmap's data.
* **Change Heatmap Metric**: On the Competitor Heatmap card, use the toggle to switch the grid between "Mention %" and "Citation %".
**Drilldowns**
* Clicking the **Responses Analyzed** or **Attributed Citations** stat cards navigates to the Responses page (filtered to attributed citations if applicable).
* Clicking the **Sources Tracked** stat card navigates to the Sources page.
* Clicking a cell inside the **Competitor Heatmap** navigates to the Prompts page, pre-filtered to that specific competitor and topic.
* Clicking the **What's Working** card navigates to the full Win Finder analysis page.
## Data shown
The data displayed on Olympus is derived from tracked AI model responses for the active website, competitor brand tracking, and the website's tracked content. Value-based metrics (like AI Search Value and Dollar Value Captured) synthesize this data with real-world Google keyword search volume and Cost-Per-Click (CPC) economics. Traffic impact metrics pull from connected GA4 and Google Search Console integrations.
## Common workflows
**Reviewing AI search visibility**
1. Navigate to Olympus.
2. Adjust the Date Range, Models, or Competitors filters to scope your investigation.
3. Scan the top stat cards and the main Share of Voice, Mention Rate, and Citation Rate cards.
4. Click a card's "ⓘ" info icon to review exactly how a metric was calculated if needed.
**Customizing the dashboard**
1. Click the "More actions" (⋯) menu in the top right and select "Dashboard settings".
2. In the left sidebar of the modal, toggle the switches for the cards you want to show or hide.
3. In the preview area on the right, drag cards to reorder them.
4. Click "Done" to save your layout.
**Setting up a recurring report**
1. Click the "More actions" (⋯) menu in the top right and select "Manage reports".
2. Click the "New report" button.
3. Configure the schedule cadence, recipients, and select the specific charts you want included.
4. Save the report. It will now automatically deliver to the selected recipients.
**Drilling into competitor topic gaps**
1. Scroll down to the "Competitor Heatmap" card.
2. Review the grid to find topics where a competitor's Mention % or Citation % is strong but your brand's is weak.
3. Click that specific cell in the grid.
4. You will be taken to the Prompts page, pre-filtered to see the exact prompts driving that competitor's visibility for that topic.
## Empty, loading, and error states
* **Loading**: While the page first loads, users will see a top loading bar. Individual cards display various skeleton shapes (charts, donuts, radars, lists) while their specific data queries are in flight.
* **Empty (No data yet)**: If the website has not ingested any data at all, the entire dashboard is replaced by an empty state saying "No data yet for this website" with a "Stream Data" button.
* **Empty (Filters exclude data)**: If active filters exclude all data, the dashboard shows "No data matches the selected filters" with a "Clear Filters" button.
* **Empty (Card level)**: If an individual card has no data for the selected filters, its contents blur out and display a "No data" message.
* **Error**: If an individual card's data fails to load, it blurs out and displays "Something went wrong..." with a refresh icon button to retry the query.
## Linked from / links to
* **Linked from**: Users typically arrive here from the primary sidebar navigation, the workspace switcher, or automatically after logging in.
* **Links to**: Stat cards link to the Responses and Sources pages. Heatmap cells link to the Prompts page. The "What's Working" card links to the Win Finder page.
## Common support questions
**Why is the Share of Voice percentage on the AI Search Value card lower than my main Share of Voice chart?**
The main Share of Voice chart counts every brand mention equally across all of your topics, including your own branded queries (where you naturally dominate). The "AI Search Value" card explicitly looks at your *commercial, non-branded topics*, weights each topic by its market value, and rewards appearing prominently (not just being mentioned). Because it focuses strictly on the high-value generic topics where you actually compete, it generally reads lower.
**What does a \$0 mean on the AI Search Value card?**
It might simply mean your brand is not appearing in AI answers yet (0% share of voice). However, it could also mean your website is paused, your website's country isn't supported by the keyword economics service yet, you have no tracked topics, or your tracked topics map to keywords with no addressable market value. In those cases, the card will display a specific message explaining why it cannot calculate a value.
**Why can't I click "Export as CSV"?**
Exporting data to CSV is a premium feature. If you are on a Free plan, clicking "Export as CSV" will prompt you to upgrade your plan. Additionally, export buttons are disabled entirely if the website has no data ingested yet.
**How do I restore the original dashboard layout?**
Click the "More actions" (⋯) menu in the top right, select "Dashboard settings", and click the "Reset" button in the bottom left of the modal. Note that your dashboard layout is saved to your browser (localStorage), meaning if you log in from a new computer or clear your browser data, your layout will revert to the default.
# Oracle
Source: https://docs.athenahq.ai/guides/oracle
Runs and reviews AI-response accuracy checks and fact verification against a brand's knowledge base, surfacing discrepancies for the team to resolve.
`app.athenahq.ai/oracle`
## Purpose
The Oracle page verifies how accurately AI models are talking about a customer's brand. It checks AI responses against the customer's knowledge base to spot inaccuracies, hallucinations, and contradictions. It also allows customers to verify their internal knowledge base facts against external third-party sources.
Customers use this page to measure their brand's AI accuracy over time, identify high-impact AI hallucinations, and resolve discrepancies so they can take action to correct the AI's understanding.
## What's on the page
**Page header**
Shows the title "Oracle". If a run has been completed, it includes a "Run analysis" button to kick off new checks.
**What AI is saying about your brand**
A search box allowing customers to ask questions about their brand across AI models (e.g., "What is AI saying about your pricing, competitors, founders…?"). Submitting a query returns a synthesized summary of AI claims, complete with citation pills (like `[1]`) and a sentiment badge ("Positive", "Negative", "Mixed", or "Neutral").
**Metric cards**
* **Discrepancy rate**: The share of analyzed AI responses that contain at least one claim contradicting the verified facts. Includes a sparkline chart showing the trend over recent runs. Tooltip: "Share of analyzed AI responses with at least one claim that doesn't match your verified facts. Lower is better."
* **Open discrepancies**: The total number of unresolved discrepancies, with a sub-value indicating how many of those are high-impact.
**High-impact discrepancies**
A list of the top unresolved, high-impact discrepancies found in the latest run. Each row shows a severity indicator ("High", "Medium", "Low"), the incorrect AI claim, and the ground truth. A "See all" button opens the full review window.
**Coverage**
* **Accuracy by model**: A chart breaking down AI accuracy across different models (like ChatGPT, Claude, Gemini, Perplexity, DeepSeek, Grok, Copilot, AI Mode, AI Overview). Tooltip: "Click a model to drill into its accuracy over recent runs. Accuracy = 1 − (high-confidence critical wrong claims ÷ total response claims). Variants of the same model (e.g. Claude) are merged."
* **Topics AI gets wrong**: A chart showing which topic categories have the most errors or the highest error rate. Tooltip: "Topic categories where AI gets claims wrong. Toggle Count vs % wrong: Count surfaces topics with the most wrong claims overall; % wrong surfaces topics where the error rate is highest regardless of volume. Click a bar to see the actual wrong claims for that topic."
**Check responses dialog**
Opened when running a new accuracy check. Allows the customer to select a date range to scan. Once a run finishes, this dialog updates to show how many discrepancies were found, offering a "Review discrepancies" button.
**Verify facts dialog**
Opened to validate the internal knowledge base against external sources. Shows a multi-select dropdown to choose specific Pillars to verify.
**Verification sources drawer**
Appears when reviewing a fact-verification run. Shows a table ranking external domains by the number of contradictions found.
* **Domain**: The contradicting source's root domain. Can also display "Knowledge base" for internal inconsistencies, with the tooltip: "Places where your KB topics contradict each other (internal inconsistencies)".
* **Contradictions**: The count of contradictions attributed to this domain.
**Contradictions drawer**
Opened by clicking a domain in the Verification sources drawer. Shows a paginated view of individual contradiction cards comparing the Knowledge base claim to the AI response claim.
**Discrepancy review window**
A full-screen modal opened by clicking "See all" or clicking a specific discrepancy. It provides a split-pane workspace:
* **Left rail**: A list of discrepancies, filterable by Unresolved, Resolved, or Dismissed.
* **Main panel**: Compares "Claim A" and "Claim B", explains "Why this is flagged", and provides a "Research verdict" from deep research. Contains options to mark which claim is correct and add a note.
**Response Details drawer**
A slide-out drawer showing the full text of an AI response, its date, the model used, the prompt type, and whether the target was mentioned.
## What you can do here
* **Search AI claims**: Type a query into the "What AI is saying about your brand" search box and press Enter. Click the `[1]` citation pills to view the underlying AI response.
* **Run a response check**: Click "Run analysis" and select "Check responses". Choose a date range and click "Start".
* **Verify facts**: Click "Run analysis" and select "Verify facts". Choose the Pillars you want to check and click "Start verification".
* **Review discrepancies**: Click "See all" or click on any individual discrepancy row to open the review window.
* **Resolve a discrepancy**: In the review window, select the correct claim ("Claim A" or "Claim B"). You can also click "+ Add a note" to save an explanation for your team.
* **View response**: When viewing a discrepancy or a search citation, click the AI response chip (e.g., "Response 1" or "View response") to open the full Response Details drawer.
* **Open external site**: In a discrepancy card or contradiction view, click the domain link or "Open site" to open the cited third-party source in a new tab.
* **Cancel a running analysis**: When a run is active, a progress overlay appears in the bottom right. Click "Cancel" on this overlay to stop the run.
* **Hide progress overlay**: Click the 'x' icon on the floating progress overlay to dismiss it from your screen without cancelling the background run.
* **Review pending claims**: In the Verify facts dialog, if there are pillars with unreviewed claims, click the "Review them" or "Review" link to navigate to the Knowledge Base review page.
## Data shown
The page displays data generated from analyzing the AI responses collected for your brand against the verified facts configured in your Knowledge Base. It highlights mismatches (discrepancies), measures accuracy rates across models, and identifies external domains that contradict your brand's established facts.
## Common workflows
**Run a brand-accuracy check**
1. Click "Run analysis" in the top right and select "Check responses".
2. Select a date window (like "Last 7 days" or "Last 30 days") or pick custom dates.
3. Click "Start". A floating overlay will track the progress.
4. Once completed, a dialog will summarize the findings. Click "Review discrepancies" to start resolving them.
**Resolve a discrepancy**
1. From the Overview tab, click on a high-impact discrepancy row or click "See all".
2. Read the comparison between Claim A and Claim B, along with the "Why this is flagged" explanation.
3. Review the "Research verdict" for additional context.
4. Click on the correct claim (or leave the recommended one selected) to resolve it.
5. Click "+ Add a note" if you want to leave context for your team.
**Verify knowledge-base facts against external sources**
1. Click "Run analysis" and select "Verify facts".
2. Use the dropdown to select which Pillars you want to verify.
3. Click "Start verification".
4. When finished, open the results to see the Verification sources table. Click any domain to review the specific contradictions.
**Search what AI says about the brand**
1. Locate the "What AI is saying about your brand" search box.
2. Type a specific question (e.g., about pricing or a competitor) and press Enter.
3. Read the AI-generated summary. Click on the numbered citation pills to drill down into the specific AI responses that support the summary.
## Empty, loading, and error states
* **No analysis run yet**: If no analysis has ever been run, the page displays a dashed-border empty state with a shield icon, prompting you to "Run first analysis".
* **Running your first analysis**: While the very first run is in progress, a spinner appears with text explaining that the process typically takes 5–15 minutes.
* **Loading states**: While fetching data, the page shows skeleton placeholders mimicking the shapes of the metric cards, charts, and lists.
* **Check complete**: When an analysis finishes, a dialog appears summarizing how many discrepancies were found.
* **Couldn't verify access**: If there is an issue validating your subscription plan, an error screen appears with a "Retry" button.
* **Locked feature**: If your subscription plan does not include Oracle, a lock screen will appear prompting an upgrade.
## Linked from / links to
* **Linked from**: Typically accessed via the main sidebar navigation under "Oracle".
* **Links to**:
* The "Review them" or "Review" links in the Verify facts dialog take you to the Knowledge Base review page to approve pending claims.
* Links to external domains open third-party websites in a new tab.
## Common support questions
**Why can't I click "Run analysis"?**
Starting, cancelling, or resolving an analysis run requires Write access for Analytics. If you only have View access, the button will be disabled, and hovering over it will show a tooltip explaining the required permissions.
**Why is there a cap on the number of responses scanned?**
To ensure the analysis completes efficiently, a single run analyzes a maximum of 3,000 responses. If your selected date range contains more than this, the system will sample them evenly across all models.
**Why can't I change a discrepancy that says "Both valid" or "Dismissed"?**
Once a discrepancy is resolved as "Both valid" or is "Dismissed", it becomes locked to prevent accidental changes. If you need to update it, click the "Edit" button on the card to unlock the choices.
**What does "Knowledge base" mean in the verification sources list?**
When running a "Verify facts" check, you might see "Knowledge base" listed as a contradicting source. This indicates an internal inconsistency where two approved facts within your own Knowledge Base contradict each other.
# Outreach
Source: https://docs.athenahq.ai/guides/outreach
Triage pages that AI cites, find the author/contact info, draft outreach emails, and track outreach progress through a pipeline.
`app.athenahq.ai/outreach`
## Purpose
The Outreach page is your command center for capitalizing on pages where AI models cite your brand or your competitors. It helps you identify high-value candidate pages, locate author contact information, and draft personalized pitch emails.
By unifying discovery, enrichment, and pipeline tracking into a single view, Outreach lets your team quickly turn raw citations into actionable PR and link-building opportunities. You can triage pages in a list format, generate AI-powered drafts, and track your active communications across a visual kanban board.
## What's on the page
**Page header**
Features the page title, a tooltip explaining the page's purpose, and tabs to toggle between the **Inbox** list and the **Board** pipeline.
**Filter bar**
Allows you to narrow down opportunities using various filters (Date range, Prompt tags, Prompt status, Models, Prompts, Competitors, Source tags, Brand mentioned, Opportunity status, Owned domains, and Search). You can save filter combinations as views and access page-level actions like **Tags** and the **⋯** (More options) menu.
**Inbox tab - Opportunity list**
A scrollable table of pages cited by AI. Selecting checkboxes on rows reveals a floating bulk action bar at the bottom of the screen.
**Opportunity List (Inbox tab) Columns**
* **checkbox**: Select the row for bulk actions. The header checkbox selects or deselects all loaded rows.
* **Page**: Displays the website's favicon, domain, and the specific path of the cited page.
* **Status**: The current pipeline status (New, Todo, In Progress, Done, Rejected) with a corresponding icon. Collapses to just the icon on narrower screens.
* **Citation %**: The percentage of responses that cited this page.
* **Est. impr.**: The estimated monthly impressions for this page.
* **Citations**: The raw number of times AI responses cited this page.
* **Mentioned**: Indicates if your brand was mentioned on the page (Yes, No, or N/A if the page could not be scraped).
* **Competitors**: Displays logos of tracked competitors mentioned on the page, with a '+N' indicator for overflow.
**Inbox tab - Opportunity detail pane**
Appears on the right when an opportunity row is clicked. Displays the page's citation metrics, author information, message draft, and activity history. Allows you to manually edit or use AI to enrich the contact details and draft an email.
**Bulk action bar**
A floating toolbar that appears at the bottom of the screen when one or more rows are selected. It displays the count of selected rows and offers bulk enrichment and status actions.
**Board tab - Kanban board**
A pipeline view grouping outreach contacts by status (Todo, In Progress, Done, Canceled). Each card displays the domain, an assignee avatar, and status badges.
**Export dialog**
Opened from the **⋯** menu, this modal lets you configure and download a CSV of your opportunities.
**Source Tags drawer**
Opened by clicking **Tags**. Allows you to categorize domains or URLs with custom colored labels.
**Source Tags list (drawer) Columns**
* **Type**: The custom tag name displayed as a colored badge.
* **Domains**: The total number of root domains assigned to this tag.
* **URLs**: The total number of specific URLs assigned to this tag.
* **actions**: A delete icon (trash can) that appears when hovering over a row.
**Drilldowns**
* **Clicking an opportunity row**: Opens the opportunity detail pane on the right side of the screen, showing metrics, author info, and drafts for that URL.
* **Clicking a Kanban card**: Switches to the Inbox tab and opens the detail pane for that specific opportunity.
* **View analytics link**: Inside the detail pane, clicking this link navigates to the dedicated Source Analytics page for the cited URL.
* **Tags button**: Opens the Source Tags drawer on the right side of the screen.
* **More options (⋯) > Export as CSV**: Opens a modal to choose the export size and download the CSV data.
## What you can do here
**Manage opportunities (Inbox)**
* **Switch tabs**: Click **Inbox** or **Board** at the top of the page to change views.
* **Sort the list**: Click the **Sort** button in the upper right of the list to sort by Citation %, Est. impressions, Citations, Mentions, or First seen.
* **Select rows for bulk actions**: Check the boxes next to rows to reveal the floating bulk action bar. From here, you can:
* **Find authors**: Runs bulk AI enrichment to find names, emails, and LinkedIn profiles for the selected pages.
* **Draft messages**: Generates personalized outreach emails for the selected pages in bulk.
* **Start**: Moves selected opportunities to the "In Progress" status.
* **Reject**: Moves selected opportunities to "Canceled" (displayed as "Rejected") and removes them from the default active view.
* **Clear selection**: Deselects all rows (or press Esc).
* **Use keyboard shortcuts**: Quickly navigate the inbox using `j`/`k` (or up/down arrows) to move the cursor, `Enter` to open a row, `X` to reject, `S` to start, `A` to find authors, `D` to draft, and `O` to open the URL in a new tab.
**Edit an opportunity (Detail pane)**
* **Change status**: Click the status dropdown (e.g., "New" or "Todo") at the top of the pane to manually change the pipeline stage.
* **Assign a teammate**: Click the unassigned user icon to pick an assignee from your organization.
* **Find author**: Click the **Find author** button to use AI to locate the author's name, email, and LinkedIn profile.
* **Edit author**: Click **Edit** in the Author section to manually enter or fix contact details. Click **Save** when done.
* **Draft message**: Click the **Draft message** button to have AI read the article and write a personalized pitch.
* **Customize generation prompt**: Click the gear icon (**Customize the generation prompt**) next to the Draft button to add your own custom instructions (e.g., "sound casual" or "mention our new feature") before generating the draft.
* **Edit message**: Click **Edit** (or press `⌘E` / `Ctrl+E`) to tweak the AI-generated subject and body. Press `⌘S` / `Ctrl+S` to save.
* **Copy full email**: Press `⌘⇧C` / `Ctrl+Shift+C` to copy the assembled email (To, Subject, and Body) to your clipboard.
* **Open in mail client**: Click the mail button or press `⌘⏎` / `Ctrl+Enter` to open your computer's default email app with the draft pre-filled.
* **Check AI accessibility**: Click the **Scan** button in the AI access section to verify if AI bots can read the page.
**Manage pipeline (Board)**
* **Move cards**: Click and drag an opportunity card from one column to another to update its status (e.g., from "Todo" to "In Progress").
* **Reorder cards**: Drag cards up or down within the same column to prioritize them for your team.
* **Assign from board**: Click the avatar icon on a card to quickly change the assignee without opening the detail pane.
**Manage Source Tags**
* **Create a tag**: Click **Tags** in the filter bar, then **Create a Type**. Provide a name, select a color, choose whether you are tagging Domains or URLs, and add items manually or via a CSV upload.
* **Edit a tag**: Click a tag row in the drawer to add or remove domains/URLs.
* **Delete a tag**: Hover over a tag row and click the trash can icon to permanently remove it.
**Export data**
* **Download CSV**: Click the **⋯** menu in the filter bar and select **Export as CSV**. Note: This is gated by your subscription plan; if your plan does not include data export, clicking this will prompt an upgrade dialog.
## Data shown
* **Opportunities**: The list comprises external web pages that have been cited as sources by AI models in response to your tracked prompts.
* **Metrics**: Citation counts, percentages, and estimated impressions represent how often and how prominently these pages appear in the AI responses we've tracked for you.
* **Author and Drafts**: Author names, emails, and drafted messages are either extracted/generated by AI on demand or entered manually by your team.
* **Brand and Competitor Mentions**: Badges indicate whether your brand or your tracked competitors are explicitly mentioned in the text of the cited page.
## Common workflows
**Triage a new opportunity**
1. Open the Outreach page (it defaults to the Inbox tab).
2. Select or use arrow keys to navigate to a high-value row.
3. Review the citation metrics and competitor mentions in the detail pane on the right.
4. Click **Find author** to let AI locate contact information.
5. Click **Draft message** to generate a personalized email pitch.
6. Review and edit the draft if needed, then click **Save**.
7. Press `⌘⏎` to open the draft in your email client, or copy it to your clipboard.
8. Change the status dropdown to **In Progress** or **Done**.
**Bulk enrich and draft for many pages**
1. Use the filter bar to narrow the opportunity list (e.g., sort by highest Citation %).
2. Check the boxes next to several rows, or use the header checkbox to select all.
3. In the floating bulk action bar at the bottom, click **Find authors**.
4. Wait for the progress toast to complete, then click **Draft messages**.
5. Once finished, click **Start** on the bulk action bar to move all selected items into the "In Progress" pipeline stage.
**Track pipeline progress on the Board**
1. Click the **Board** tab at the top of the page.
2. View your team's active outreach efforts grouped by Todo, In Progress, Done, and Rejected.
3. Click and drag a card to a new column as outreach progresses.
4. Click a card's avatar to assign it to a specific team member.
**Create a custom source tag**
1. Click the **Tags** button in the filter bar to open the drawer.
2. Click **Create a Type**.
3. Enter a Type Name and select a Color.
4. Choose whether to apply the tag to Root Domains or specific URLs.
5. Upload a CSV file or type domains/URLs into the manual entry field.
6. Click **Save**.
## Empty, loading, and error states
* **Empty (Inbox)**: If no pages match your current filters, you'll see "No opportunities match these filters" with a suggestion to widen the date range or clear filters. Note that rejected opportunities are hidden by default; you can view them by changing the Opportunity status filter.
* **Empty (Board)**: If you haven't triaged anything yet, the board shows "Nothing in the pipeline yet" with instructions to start or draft an opportunity in the inbox.
* **Loading**: An animated loader appears in the center of the screen while opportunities or detail metrics are fetching.
* **Error**: If the data fails to load, a message states "Unable to load outreach data. Please try again." along with a **Try again** button.
## Linked from / links to
* **Linked from**: The main app sidebar navigation.
* **Links to**: The source analytics detail page (via the "View analytics" button in the detail pane).
## Common support questions
**How much does finding authors and drafting messages cost?**
Each successful action costs 0.1 credits per row. You are not charged if the AI fails to find an author or fails to generate a message draft.
**Why don't I see an opportunity I rejected earlier?**
When you mark an opportunity as "Rejected" (or "Canceled"), it is removed from the active queue. To see it again, update the "Opportunity status" filter in the filter bar to include "canceled".
**How do I undo a rejected opportunity?**
When you reject an opportunity, a success toast appears with an "Undo" button. Clicking it instantly restores the opportunity to its previous status. Alternatively, you can find the rejected item using the filters and manually change its status back.
**Can I customize the AI email drafts?**
Yes. In the detail pane, click the gear icon (**Customize the generation prompt**) next to the Draft message button. You can add specific instructions (e.g., "mention our new feature" or "sound casual"). These instructions are saved to your browser and will apply to future drafts for that website.
**Why can't I export my outreach data?**
The "Export as CSV" feature requires a subscription plan that includes data export capabilities. If your plan doesn't include this, clicking the button will open an upgrade dialog.
# Pitch Workspace Report
Source: https://docs.athenahq.ai/guides/pitch-workspace
Shows the full AI-visibility report (share of voice, brand mentions, model performance, competitor analysis, citation sources, and underlying AI responses) for the organization's currently active pitch.
`app.athenahq.ai/pitch-workspace`
## Purpose
The Pitch Workspace Report provides a comprehensive, shareable dashboard of how a specific brand performs across major AI search models (like ChatGPT, Claude, Gemini, and Perplexity) based on a configured "pitch."
It gives marketers and agencies a clear view of their AI visibility, showing share of voice, brand mention rates, competitor standing, and exactly what the AI models are saying (including their cited sources). It helps you understand where you are winning in AI search and where competitors are taking the spotlight.
## What's on the page
**Page & Report Header**
* **Page header**: Displays the brand's logo and name, along with a **Copy link** button.
* **Report header**: Shows the title "AI search preview report", a "Powered by AthenaHQ" badge, and the date the report was audited.
* **Landing page CTA**: (Only visible for certain pitch types) A banner offering to "Track this brand across every AI surface" with buttons for **See pricing** and **Book a demo**.
**Metric Cards**
* **Share of voice**: Displays the percentage of mentions the brand receives compared to all tracked brands.
* *Tooltip on the info icon*: "The percentage of mentions your brand receives compared to all brands. Click for details."
* **Brand mentions**: Displays the percentage of AI responses that mention the brand.
* *Tooltip on the info icon*: "Percentage of AI responses that mention your brand. Click for details."
* **Responses analyzed**: Shows the total number of AI responses collected for the report.
* *Tooltip on the info icon*: "Total AI responses collected and analyzed for this report"
* **Models tested**: Shows how many different AI models were queried.
* *Tooltip on the info icon*: "AI models queried while building this report"
**Charts & Breakdowns**
* **Share of voice chart**: A donut chart visualizing how often AI mentions your brand versus your competitors.
* **AI model performance card**: Lists the AI models tested, showing the brand's mention rate for each specific model.
* **Positive brand traits card**: A radar chart showing positive attributes associated with the brand compared to competitors.
* **Negative brand traits card**: A radar chart showing negative attributes associated with the brand compared to competitors.
* **Top citation sources card**: A ranked list of domains most frequently cited by the AI models in these responses.
* **Competitive landscape card**: A ranked list of the brand and its tracked competitors, showing each one's share of all brand mentions.
**Responses Table**
A searchable list of all AI responses collected for the pitch.
* **Model**: Which AI model generated the response (e.g., ChatGPT, Claude, Gemini).
* **Mentioned**: Whether the target brand was mentioned in the response (Yes or No pill).
* **Competitors Mentioned**: Logos and names of competitors mentioned in the response. If none, shows a "No" pill. If there are many, shows a "+N" indicator.
* **Prompt**: The specific prompt variation that was sent to the AI.
* **Response**: A preview of the AI's raw response text (or a **View** button for scraped content).
**Response Details Drawer (Drilldown)**
Clicking any row in the Responses table opens a side panel with full details about that specific AI answer:
* **Date**: When the response was generated.
* **Model**: The AI model that generated it.
* **Prompt Type**: The categorization of the prompt (e.g., Branded, Non-Branded).
* **Mentioned**: Whether your brand was mentioned.
* **Market Position**: The numeric rank of the brand in the response (if applicable).
* **Competitors Mentioned**: A list of competitor names mentioned.
* **Base Prompt & Variation**: The original prompt text and the specific variation sent to the AI.
* **Response**: The full response text. Citations, brand mentions, and competitor mentions are highlighted.
* **Sources**: A list of clickable source links cited by the AI model.
* **Google AI Overview sections**: If the response is from AI Overview, collapsible sections for **Organic Results**, **People Also Ask**, and **Related Searches** will appear, showing the links and snippets Google provided.
## What you can do here
* **Copy the report link**: Click **Copy link** in the top right to copy a public URL for the report to your clipboard. This link can be shared with anyone, even if they don't have an Athena account.
* **Reorder cards**: You can click and drag the top-right corner (grip icon) of the metric cards (the top row) to reorder them among themselves. You can also drag the larger chart and table cards below to rearrange their layout.
* **View metric details**: Click the info icon on the **Share of voice** or **Brand mentions** cards to open a dialog with a detailed explanation of what the metric means and how it is calculated.
* **Search responses**: Type in the **Search responses** box above the table to filter the responses by words found in the prompt or the response text.
* **Load more responses**: Scroll to the bottom of the responses table. It will automatically load more responses if available, or you can click the **Load More** button.
* **View full response details**: Click any row in the responses table to open the response details drawer.
* **Navigate through responses**: While the response detail drawer is open, use the up and down arrow buttons in the top right of the drawer (or the up/down arrow keys on your keyboard) to move to the previous or next response without closing the drawer.
## Data shown
The data shown represents the AI search visibility for the currently active pitch in your organization. It includes the AI responses collected when the pitch was audited, the citations extracted from those responses, and the attributes and competitors configured when the pitch was created.
## Common workflows
1. **Reviewing top-level performance**: Land on the workspace, check the top four metric cards for an immediate pulse on Share of Voice and Brand Mentions, and look at the AI model performance list to see where the brand is strong or weak.
2. **Investigating competitor standing**: Review the Share of Voice donut chart and the Competitive landscape list to see exactly how much of the conversation competitors are taking. Use the Positive/Negative brand traits charts to see what the AI associates with each competitor.
3. **Deep diving into specific AI answers**: Scroll to the Responses table, search for a specific product or feature keyword, and click a row to open the details drawer. Read the full AI answer and click the cited sources to see where the AI got its information.
4. **Sharing the results**: Click the **Copy link** button to get a public URL, then share it with clients or stakeholders so they can view the dashboard without needing to log in.
## Empty, loading, and error states
* **Loading**: While the report data is fetching, the page displays a skeleton outline of the dashboard (grey boxes matching the layout of the cards and charts).
* **Processing**: If the pitch is still being generated (status is "processing" or "draft"), the page shows a "Building your report" screen with a loading spinner. The page will automatically update when the report is ready (usually in 5 to 10 minutes).
* **Failed**: If the pitch generation failed, a "Report processing failed" screen appears with a **Create another pitch** button.
* **Error**: If the report data cannot be loaded due to a system error, a "Couldn't load this report" screen appears with a **Try again** button.
* **Empty traits**: If no positive or negative brand traits were detected in the responses, those specific radar charts are hidden entirely from the page.
* **Empty table**: If no responses match your search query, the table displays "No responses found."
## Linked from / links to
* **Linked from**: The **Pitch Workspace** item in the main sidebar, the pitch workspace dropdown menu, or the pitch creation flow (which redirects here once a pitch is created).
* **Links to**: The **Copy link** button copies a link to the public report page. The **Create another pitch** button (on the failure screen) links to the pitch creation flow.
## Common support questions
* **Why don't I see the Positive or Negative brand traits charts?**
These charts only appear if the AI models specifically mentioned attributes about your brand or competitors. If no attributes were detected during the pitch audit, the charts are hidden.
* **How can I share this report with my client?**
Click the **Copy link** button in the top right corner. This generates a secure, public link that you can share with anyone. They do not need an AthenaHQ account to view the report.
* **What models are included in "AI model performance"?**
This section breaks down mentions across the models queried during the pitch, which can include ChatGPT, Claude, Gemini, Perplexity, Copilot, Grok, DeepSeek, AI Overview, and AI Mode.
* **Why is the page stuck on "Building your report"?**
Pitches typically take 5 to 10 minutes to process. The page will automatically refresh once the AI has finished querying the models and analyzing the responses. You can safely navigate away and come back later.
* **Can I change the order of the cards?**
Yes, as an authenticated user, you can hover over a card to reveal a drag handle in the top right corner. You can drag and drop cards to rearrange them (metric cards reorder with metric cards, and larger charts reorder with other larger charts).
# Content Pitches List (Pitch Workspace → Content)
Source: https://docs.athenahq.ai/guides/pitch-workspace-content
Lists an organization's content pitches: shareable AI-generated rewrite reports created to pitch prospects, with actions to create, open, share, or delete each one.
`app.athenahq.ai/pitch-workspace/content`
## Purpose
This page lists all the content pitches generated by your organization. Content pitches are shareable reports that demonstrate to a prospect how Athena would rewrite a specific article or webpage for AI search optimization.
This page serves as a central hub for your team to view generation progress, manage existing pitches, and grab the public links needed to share these reports with prospects.
## What's on the page
**Header**
* **Page Title & Description:** Displays the "Content" title and a brief description: "Shareable reports that show a prospect how Athena would rewrite a page of theirs for AI search."
* **Create new:** A primary button that opens the setup wizard to start a new content pitch.
**Content Pitch List**
Displays a row for each content pitch created by your organization, sorted by newest first. Each row contains:
* **Prospect Info:** The website's favicon, the prospect name (if provided) or URL, and the source URL below it.
* **Creation Time:** A relative timestamp indicating when the pitch was created (e.g., "2 days ago"). This text is hidden on smaller mobile screens.
* **Status Badge:**
* **Generating:** The pitch is currently being created by Athena.
* **Ready:** The pitch is complete and can be shared.
* **Failed:** An error occurred during generation and the pitch could not be completed.
* **Row Actions:** Icon buttons aligned to the right side of the row for interacting with the pitch.
## What you can do here
* **Create a new pitch:** Click the "Create new" button at the top right to start a new content pitch.
* **Open the internal report:** Click anywhere on a pitch's name or URL to open the internal detail page, which shows the generation progress or the finished rewrite suggestions.
* **Copy public link:** For pitches with a "Ready" status, click the copy icon (two overlapping files) to copy the public-facing URL to your clipboard. A "Link copied" toast notification will appear.
* **Open public report:** For pitches with a "Ready" status, click the external link icon (an arrow pointing out of a box) to open the unauthenticated, shareable report in a new browser tab.
* **Delete a pitch:** Click the trash can icon to delete the pitch.
* *Confirmation flow:* A dialog will appear asking "Take down this content pitch?" with the description "\[Name] is removed from this list and its public share link stops working." Click "Take down" to confirm or "Cancel" to go back.
* *Note:* The delete button only appears if you have permission to delete the pitch (you are the creator or an organization admin).
## Data shown
The list displays the content pitches created by members of your active organization.
## Common workflows
**Create a new content pitch**
1. Click the "Create new" button in the top right corner.
2. You will be taken to a setup wizard where you can paste a prospect's article URL.
3. Upon submission, you will be redirected to the pitch's detail page while it generates.
**Share a completed pitch with a prospect**
1. Wait for a pitch's status badge to show "Ready".
2. Click the copy link icon on the right side of the row to copy the public URL, or click the external link icon to verify the report in a new tab first.
3. Send the copied link to your prospect.
**Take down a content pitch**
1. Locate the pitch you want to remove and click the trash can icon on the right.
2. Review the confirmation dialog.
3. Click "Take down". The pitch will be removed from your list, and its public link will immediately stop working.
## Empty, loading, and error states
* **Empty state:** If your organization hasn't created any content pitches yet, the page displays a document icon and the text "No content pitches yet". Below it, a description reads: "Paste a prospect article and Athena generates inline rewrite suggestions on a public page you can share." A "Create your first content pitch" button is provided.
* **Loading state:** A centered animated loader appears while the page verifies your access or fetches the list of pitches.
* **Error state:** If the list fails to load, a bordered panel appears with the message "Couldn't load content pitches" and "Check your connection and try again." A "Retry" button allows you to re-fetch the list.
## Linked from / links to
* **Linked from:** The "Content" tab in the left-hand navigation rail of the Pitch Workspace.
* **Links to:**
* **Create new:** Opens the content pitch creation wizard (`/pitch-workspace/content/create`).
* **Row click:** Opens the internal detail view for the specific pitch (`/pitch-workspace/content/[id]`).
* **Open public report:** Opens the external, public-facing report in a new browser tab (`/report/content/[id]`).
## Common support questions
**Why is the delete button missing for some pitches?**
You can only delete content pitches that you personally created, or if you hold an organization administrator role. If a coworker created the pitch and you are a viewer, the trash can icon will be hidden.
**Do I need to refresh the page to see when a pitch is finished generating?**
No, the list automatically checks for updates every 5 seconds as long as any pitch is actively generating. The status badge will change to "Ready" or "Failed" on its own.
**What happens if I take down a pitch?**
The pitch is immediately removed from your workspace list, and the public share link is disabled. If a prospect tries to visit the link after you take it down, it will no longer work.
# Create Content Pitch
Source: https://docs.athenahq.ai/guides/pitch-workspace-content-create
Two-step wizard where an agency user pastes a prospect's article URL, has Athena analyze it and draft AI-search prompts, then generates a shareable public 'content pitch' report showing rewrite suggestions.
`app.athenahq.ai/pitch-workspace/content/create`
## Purpose
This page provides a simple, two-step wizard for agency and sales users to generate an Athena "content pitch." A content pitch is a shareable, public report that takes a prospect's existing article or landing page, analyzes it, and demonstrates exactly how Athena would rewrite that content to rank better in AI search engines.
By pasting a target URL, users allow Athena to automatically scrape the page, identify the company name, and draft a list of relevant AI-search discovery prompts. Users can then curate this prompt list before launching the final public report, providing a powerful, hands-free sales tool.
## What's on the page
The page is framed by a header titled **Create content pitch**, with a short explanation: "Paste a prospect page and Athena shows exactly how it would rewrite it to show up in AI answers, as a public report you can share."
**Step 1. Article URL**
* **Article URL**: A text field to paste the prospect's blog post, product page, or landing page link. It includes helper text explaining that this is the exact page you want to pitch improvements for.
* **Analyze page**: A primary button that kicks off the AI analysis, reading the provided URL to extract a company description and draft prompts.
**Step 2. Prospect name & prompts**
* **Prospect name**: A text field pre-filled with the extracted company name (or domain name). The text here will be displayed at the top of the generated public report.
* **Prompts to optimize for**: A list of up to 12 AI search prompts. Athena targets these queries when writing its suggestions. The top right of this section includes a counter (e.g., "8 of 12").
* **Prompt Rows**: Each row displays an editable text box containing a drafted prompt, alongside a trash/close (`×`) icon to remove it.
* **Add your own prompt**: An empty text input at the bottom of the prompt list paired with an **Add** button. This lets you manually type in high-value queries you know the prospect cares about.
* **Back**: A button that returns you to Step 1 if you want to enter a different URL.
* **Generate suggestions**: A primary button that commits your settings and launches the generation of the final public report.
## What you can do here
* **Analyze a page**: Paste a link into the Article URL field and click **Analyze page** (or hit Enter). Athena will scrape the content and automatically suggest up to 8 discovery-style prompts.
* **Edit the prospect name**: In Step 2, click into the Prospect name field to fix or customize the title that will appear on the final report.
* **Edit a generated prompt**: Click into any populated prompt text box and type to refine the AI's suggested query.
* **Remove a prompt**: Click the `×` (Remove prompt) icon next to a row to delete a prompt you don't want to target.
* **Add a custom prompt**: Type a specific question or keyword into the "Add your own prompt" box and click **Add** (or press Enter). You can add prompts until you reach the maximum of 12.
* **Go back**: Click **Back** to return to the URL step. Your analyzed prospect name and drafted prompts will be kept if you return to Step 2 without changing the URL.
* **Create the pitch**: Click **Generate suggestions** to finalize your setup. You will be redirected to a new page where you can watch the suggestions generate.
## Data shown
The **Prospect name** and **Prompts** are dynamically generated by passing the provided URL to Athena's analysis engines. Athena reads the page to understand the company's offering and drafts a set of "discovery" queries, the kinds of broad questions potential customers might ask an AI search engine when looking for that prospect's solution.
## Common workflows
**Create a content pitch from a URL**
1. Paste the prospect's link into the **Article URL** field.
2. Click **Analyze page**.
3. Wait a moment for Athena to read the page and draft AI search prompts.
4. Review and adjust the auto-filled **Prospect name**.
5. Review the auto-generated prompts. Edit any that aren't quite right, or remove ones you don't want.
6. Click **Generate suggestions** to finalize the pitch and view the public report.
**Manually curate targeted prompts**
1. After analyzing a page, review the auto-generated list of prompts.
2. Remove any off-topic prompts by clicking their `×` icon.
3. Click into the **Add your own prompt** field.
4. Type a high-priority keyword or question you know the prospect wants to rank for.
5. Press Enter or click **Add**.
6. Repeat until you are satisfied (up to a maximum of 12 total prompts).
## Empty, loading, and error states
* **Empty state**: If Athena successfully reads the page but cannot extract enough context to draft prompts, a warning toast appears: "No prompts could be generated from the page. Add your own below." The prompt list will be empty, allowing you to build the list manually.
* **Loading**:
* Clicking "Analyze page" disables the URL field to prevent accidental changes, shows a spinner on the button, and displays: "Reading the page and drafting prompts to optimize for. This can take a moment."
* Clicking "Generate suggestions" puts a loading spinner on the button while the pitch is securely created.
* **Errors**:
* If the URL format is invalid, red helper text appears below the input: "Enter a valid URL, like prospect.com/blog/post"
* If the scraper cannot access the page (e.g., it's blocked or down), a toast appears: "We couldn't read that page. Check the URL and retry."
* General failures will trigger toasts reading: "Something went wrong analyzing the page." or "Failed to create the content pitch."
## Linked from / links to
* **Linked from**: Typically accessed via the "New content pitch" button on the Pitch Workspace (Content tab) list page.
* **Links to**: Upon successfully clicking "Generate suggestions", this page redirects directly to the newly created content pitch's detail page, where the rewrite suggestions are processed and displayed.
# Content Pitch Detail
Source: https://docs.athenahq.ai/guides/pitch-workspace-content-id
Lets an org member preview, share, and delete one AI-generated content pitch report exactly as the prospect would see it, with workspace-only management controls layered on top.
`app.athenahq.ai/pitch-workspace/content`
## Purpose
This page exists to let you view, share, and manage a single AI-generated content pitch report. A content pitch analyzes a specific article URL and provides inline rewrite suggestions to help optimize it for AI search engines.
The detail page serves as an internal workspace preview of the report exactly as the prospect will see it. It provides the essential management controls to copy the public sharing link, open the live public report, or permanently take the pitch down once it's no longer needed.
Where this fits in the workflow: after submitting a new content pitch, you are taken here to watch it generate. Once it is ready, you can review the AI's inline suggestions and grab the link to share with your prospect.
## What's on the page
* **Back link ("All reports")**: A link in the top left to return to the full list of content pitch reports.
* **Header**: Shows the prospect's website favicon, the prospect name or article URL, and the date the report was created.
* **Status badge**: Indicates the current state of the report next to the title. Shows "Generating" if the AI is still processing it, "Ready" when it is complete, or "Failed" if the generation encountered an error.
* **Action buttons**: Located in the top right of the header. Includes options to copy the public share link, open the public report in a new tab, and a trash icon to delete the pitch (if you have permission).
* **Target prompts**: If any prompts were selected to focus the AI's suggestions when the pitch was created, they appear as gray badges just below the header.
* **Report body**: Displays the scraped text of the target article, with AI rewrite suggestions appearing as highlighted passages. This is an exact preview of what the prospect will see on the public link. A small note at the top indicates how many inline suggestions are present.
* **Status placeholder card**: If the report does not have usable content yet, the article body is replaced by a message card:
* "Generating suggestions": Shown while the report is actively processing.
* "This report couldn't be generated": Shown if the pitch failed.
* "No content available": Shown if the scraped article text is missing.
## What you can do here
* **Copy link**: Click the "Copy link" button to copy the public, unauthenticated report URL to your clipboard. A "Link copied" success message will appear. You can share this link directly with prospects.
* **Open public report**: Click the "Open public report" button to open the live prospect-facing page in a new browser tab. This lets you preview the exact page the prospect will see (which includes some extra branding not shown in the internal workspace).
* **Delete content pitch**: Click the trash icon to delete the report. A confirmation dialog will ask "Take down this content pitch?". Clicking "Take down" will remove the report from your workspace, permanently disable the public share link, and redirect you back to the main list. *Note: Only the person who created the pitch or an organization administrator will see this button.*
* **Return to list**: Click "All reports" (with the left arrow) to go back to the main Content tab in the Pitch Workspace.
## Data shown
* **Target prompts**: The prompts you selected during creation to focus the AI's rewrite suggestions.
* **Scraped article content**: The readable text extracted from the prospect's URL.
* **Inline suggestions**: AI-generated rewrite suggestions overlaid onto the article text, highlighting areas that could be improved for AI search visibility.
* **Status and Metadata**: The creation date, prospect URL, and generation status coming from your organization's content pitch records.
## Common workflows
**Review and share a generated pitch**
1. Navigate to a content pitch from the workspace list or sidebar dropdown.
2. If the status is "Generating", wait briefly, the page polls for updates automatically.
3. Once the badge says "Ready", review the article and its highlighted inline suggestions.
4. Click "Copy link" to grab the public URL for sending to your prospect, or click "Open public report" to double-check the live prospect view in a new tab.
**Delete a content pitch**
1. Open the pitch detail page.
2. Click the trash icon in the top right (you must be the creator or an organization administrator to see this).
3. Confirm by clicking "Take down" in the "Take down this content pitch?" dialog.
4. The pitch is removed, its public link immediately stops working, and you are taken back to the list of all reports.
**Recover from a failed generation**
1. Open a pitch whose status badge reads "Failed".
2. Read the placeholder card, which advises: "Delete it and create a new one from the article URL."
3. Click the trash icon to delete the broken pitch.
4. Return to the list page and create a new content pitch using the same URL.
## Empty, loading, and error states
* **Loading**: While the report data is fetching, skeleton placeholders appear for the back link, header, title, and the article body.
* **Generating**: If the AI is still writing the report, a card appears reading "Generating suggestions" with the subtext "This usually takes a couple of minutes. The page refreshes automatically."
* **Missing Content**: If the article could not be scraped but the report didn't fail, a card appears reading "No content available" with the subtext "The scraped article is missing for this report."
* **Failed Generation**: If the process errored out, a card reads "This report couldn't be generated" with the subtext "Delete it and create a new one from the article URL."
* **Not Found**: If the report was deleted, taken down, or the URL is incorrect, a card reads "Report not found" with the subtext "It may have been taken down or the link is wrong."
* **General Error**: If the page fails to load due to a network or system issue, a card reads "Couldn't load this report" with the subtext "Try again in a moment."
## Linked from / links to
* **Linked from**:
* The main Pitch Workspace Content list (clicking a specific row).
* The sidebar Pitch Workspace dropdown (clicking a report under the Content tab).
* The "Create" flow (which redirects here automatically once a pitch starts generating).
* **Links to**:
* The public unauthenticated prospect report page (opens in a new tab via "Open public report").
* The main Content Pitch list page (via the "All reports" back link).
## Common support questions
**Why can't I see the delete button?**
The trash icon only appears for the specific user who originally created the pitch, or for organization administrators. Other members can view and share the report but cannot delete it.
**Does viewing this page count as a "view" in our analytics?**
No. This is an internal workspace preview. The "viewed" metrics tracked for pitches only count actual prospect visits to the public share link.
**Can I edit the target prompts shown on the report?**
No, target prompts are locked in when the pitch is created. If you need to focus on different prompts, you will need to create a new content pitch.
**What happens if I delete a pitch after sending the link?**
Deleting the pitch immediately disables the public share link. If the prospect tries to visit it afterward, they will see a "not found" error.
**Why did my pitch fail to generate?**
Generation can fail if the target article blocks our scraper, requires a login, or is otherwise unreadable. When this happens, delete the failed pitch and try creating a new one.
# Pitch Setup
Source: https://docs.athenahq.ai/guides/pitch-workspace-setup
Read-only view of a selected pitch's basic info, identifiers, tracked competitors, and analysis prompts.
`app.athenahq.ai/pitch-workspace/setup`
## Purpose
The Pitch Setup page provides a read-only summary of the configuration for your currently selected pitch. It allows you to quickly review the foundational details of a pitch, including the company's core information, the specific keywords (identifiers) the AI uses to track the brand, the list of competitors being monitored, and the specific prompts configured for analysis.
This page serves as a reference point for your pitch settings, helping you verify that the correct competitors and prompts are in place for your pitch workspace reports.
## What's on the page
The page is divided into four main collapsible sections:
* **Basic Information**: Core details about your pitch and the company. It displays the **Company Name**, **Company URL** (with a clickable external link icon), a brief **Description** of the company, the date it was **Created**, and its current **Status** (e.g., Draft, Processing, Complete).
* **Identifiers**: Shows the names and keywords used to identify the main company and each competitor in AI responses. Identifiers are displayed as pill-shaped badges (indigo for your company, neutral for competitors). If a company has no keywords configured, it will show "No identifiers".
* **Competitors**: Lists the competitors being tracked in this pitch. Each entry shows the competitor's name and a clickable link to their website. If none are set up, it displays "No competitors configured yet".
* **Prompts**: Lists the specific questions or phrases used to analyze competitor mentions. Next to each prompt is a colored badge indicating its type (e.g., Discovery in purple, High Intent in indigo, or other types in a neutral color). If no prompts exist, it shows "No prompts configured yet".
## What you can do here
* **Expand or collapse sections**: Click the title of any section (e.g., "Basic Information", "Competitors") or the chevron arrow to toggle that section open or closed. All sections are expanded by default.
* **Visit company or competitor websites**: Click any linked URL in the "Basic Information" or "Competitors" sections to open that website in a new browser tab.
## Data shown
This page displays the configuration details of the single pitch you currently have selected in your pitch workspace. The information shown reflects the setup provided when the pitch was created or last edited. The page automatically refreshes this data in the background every 30 seconds to capture any recent updates.
## Common workflows
**Reviewing a pitch's configuration**
1. Select a pitch from the pitch switcher menu in your pitch workspace.
2. Navigate to the **Pitch Setup** page.
3. Scroll through the expanded sections to verify that the correct identifiers, competitors, and prompts are attached to the pitch.
4. If you need to check a competitor's site, click their URL in the **Competitors** section to open it in a new tab.
## Empty, loading, and error states
* **Loading**: While the pitch data is initially loading, the screen is completely blank.
* **Empty (No Pitch)**: If you navigate here without a pitch selected, or if the selected pitch has been deleted, a centered message appears reading "No pitch selected".
* **Empty (Sections)**: If a specific section lacks data, it displays fallback text such as "No identifiers", "No competitors configured yet", or "No prompts configured yet".
* **Error**: There is no explicit error message if the pitch data fails to load; it will generally fall back to the "No pitch selected" empty state. If your organization loses access to the pitch feature entirely, the page will be replaced by an upgrade lock screen.
## Linked from / links to
* **Linked from**: You typically reach this page from the navigation menu in the Pitch Workspace after selecting a pitch.
* **Links to**: The company URLs and competitor URLs link externally to those respective websites in a new browser tab.
## Common support questions
**Why can't I edit my pitch details on this page?**
The Pitch Setup page is a read-only summary designed for quick reference. To make changes to your pitch, you will need to use the pitch editing or creation tools located elsewhere in your workspace.
**Why does the page say "No pitch selected"?**
This means you haven't chosen an active pitch to view yet, or the pitch you previously had selected was deleted. You can select a pitch from the pitch switcher dropdown in your navigation menu.
**What do the colored badges next to the prompts mean?**
The badges indicate the categorized intent of the prompt. "Discovery" prompts (general research questions) appear in purple, "High Intent" prompts (ready-to-buy questions) appear in indigo, and other custom types appear in a neutral gray.
**Why aren't my competitor URLs clickable?**
If a competitor URL was entered in a malformed or unsafe format during setup, the system removes the link for security reasons and displays it as plain text instead.
# Pitch Workspace Usage
Source: https://docs.athenahq.ai/guides/pitch-workspace-usage
Shows how many Pitch Workspace reports an organization has used against its plan quota (or confirms unlimited usage) alongside a static explainer of what pitch reports include.
`app.athenahq.ai/pitch-workspace/usage`
## Purpose
This page allows customers to monitor their organization's Pitch Reports usage against their subscription plan's quota. It provides a quick, read-only summary of how many pitches have been created, how many remain, and static guidelines on what each pitch report includes.
## What's on the page
* **Pitch Reports usage card:**
* For plans with limits: Shows a progress bar indicating the percentage of pitch reports used. It displays the exact number of pitches **used** below it on the left, and the number **left** on the right. The progress bar changes color (indigo, purple, orange) as usage nears the limit.
* For plans without limits: Displays **Unlimited**, followed by the total number of pitches created (e.g., "5 pitches created") and a **No limits** label.
* **About Pitch Reports info card:** A static reference card outlining the constraints of a single pitch report. It states:
* "Analyze up to 10 competitors per pitch"
* "Include up to 10 custom prompts"
## What you can do here
This page is entirely read-only. Customers can view their usage and quota, but they cannot take any actions, export data, or edit settings directly from this view. To free up quota, they must return to the main Pitch Workspace to delete existing pitches.
## Data shown
* **Pitch usage:** The total number of pitch reports the customer has created across their organization.
* **Quota details:** The maximum number of pitch reports allowed and the number remaining, based on the organization's current subscription plan and feature access.
## Common workflows
1. **Checking remaining pitch quota:**
* Navigate to the Pitch Workspace.
* Open the **Usage** tab.
* Look at the progress bar to see how many reports are **left** before hitting the plan limit.
2. **Reviewing pitch report constraints:**
* Navigate to the **Usage** tab.
* Check the **About Pitch Reports** card to confirm how many competitors (up to 10) and custom prompts (up to 10) can be included before creating a new pitch.
## Empty, loading, and error states
* **Loading:** Shows pulsing placeholder shapes (a small label bar, a progress bar, and two small text blocks) while the feature access and quota are being verified.
* **Error:** If the usage data fails to load, the page shows an amber warning text: "Couldn't verify pitch quota: please refresh."
* **No Access:** If the customer's organization does not have Pitch Workspace access on their plan, the usage card displays: "Pitch workspace access is not available for your organization." The static **About Pitch Reports** card remains visible.
## Linked from / links to
* **Linked from:** The Pitch Workspace sidebar navigation rail (specifically the **Usage** menu item).
* **Links to:** This page contains no outbound buttons or links.
## Common support questions
* **"Why does my usage say 0 even though I've created pitches on another website?"**
Usage is tracked across the entire organization, not just the single website you are currently viewing. If it displays 0 incorrectly, it may be a temporary sync issue verifying your subscription; try refreshing the page.
* **"What happens if I need more than 10 competitors in a pitch?"**
As noted on the **About Pitch Reports** card, each pitch is strictly limited to 10 competitors. To analyze more, you must create a separate pitch report.
* **"My plan has unlimited pitches, why is there no progress bar?"**
If your organization's plan includes unlimited pitches, the progress bar is hidden. It is replaced with an **Unlimited** badge and a count of how many pitches you've created so far.
# Prompts
Source: https://docs.athenahq.ai/guides/prompts
Central workspace for managing tracked prompts (and their topics), plus tabs for Personas, Locations, and Discover: the core surface for building and organizing what Athena asks AI models on the customer's behalf.
`app.athenahq.ai/prompts`
## Purpose
The Prompts page is the central workspace for managing the questions and searches Athena tracks on your behalf across AI engines. It serves as your command center for organizing prompts into topics, configuring how and where they are run, and tracking their overall performance over time.
From here, you can group prompts into topical clusters, review critical metrics like Share of Voice and mention rates, set geographic and persona targeting, and explore new prompt ideas. It is an essential part of the workflow for marketers monitoring their brand's visibility in AI search.
## What's on the page
### Page Header
The top header displays the "Prompts" title alongside an info icon that launches a guided product tour. Next to it is a tab menu to navigate between **Manage** (the main table), **Personas**, **Locations**, and **Discover**. In the top right, an **Add More** button provides options to add new prompts, topics, locations, or tags.
### Prompts Table (Manage Tab)
The main content area is a spreadsheet-style table grouping your tracked prompts by topic.
**Columns:**
* **Select (checkbox):** Selects individual rows. Clicking the checkbox on a topic row selects all prompts within that topic.
* **Base Prompt:** The text of the tracked prompt. May include a "Paused" badge if the prompt is currently paused, and a "View responses" button to quickly see the AI answers.
* **Countries:** Flags representing the countries where the prompt is configured to run. Clicking this opens a country editor.
* **Mention Gap:** Your brand's mention percentage minus your competitor's mention percentage. Tooltip: *"Mention % - Competitor Mention %"*
* **Citation %:** Tooltip: *"Percentage of responses that include a citation to your brand"*
* **Competitor Citation %:** Tooltip: *"Percentage of responses that include a competitor citation"*
* **Citation Gap:** Your citation percentage minus your competitor's citation percentage. Tooltip: *"Citation % - Competitor Citation %"*
* **Attributed Citation %:** Tooltip: *"Citations from content you created in Action Center"*
* **Mention %:** Tooltip: *"Percentage of responses that mention your brand"*
* **Competitor Mention %:** Tooltip: *"Percentage of responses that mention a competitor"*
* **Est. Impressions:** Tooltip: *"Estimated number of times your brand appears in AI responses (Monthly Queries × Mention %)"*
* **Avg position:** Tooltip: *"Average ranking position in AI responses (lower is better)"*
* **Variations:** Tooltip: *"Number of unique prompt variations"*
* **Monthly queries:** Tooltip: *"Estimated monthly search queries"*
* **Value:** Tooltip: *"Total estimated value of queries"*
* **Est. value captured:** Tooltip: *"Estimated value captured based on mention % and total value"*
* **Tags:** Tags assigned to the prompt.
* **Prompts:** Number of prompts in the topic group.
* **Manage (⋯):** A menu for actions you can take on that specific row.
### "Prompt analytics" side panel
Clicking on a prompt row opens a persistent side panel titled **Prompt analytics**. It displays a mini-dashboard of visibility metrics scoped entirely to that prompt (or topic group, if a topic row is clicked).
For a single prompt, the panel also includes a **Prompt Variations** table with the following columns:
* **Type:** Indicates whether the text is the "Base Prompt" or a "Variation" generated by the AI engines.
* **Prompt text:** The literal text of the base prompt or variation.
### "Uncategorized prompts" bar
A fixed bar that appears at the bottom of the screen if you have active prompts that have not been assigned a topic. It shows the number of uncategorized prompts and gives you quick options to handle them.
### Bulk-selection bar
A fixed bar that slides up from the bottom of the screen whenever you select one or more rows using the table checkboxes. It provides actions that apply to all selected items.
## What you can do here
### Navigation and top-level actions
* **Switch tabs:** Navigate to Personas, Locations, or Discover by clicking the tabs in the top header.
* **Add items:** Click the **Add More** button to open the "Add Prompts" flow, create an "Add Topic" entry, "Add Location", or "Add Tag".
* **Change visible columns:** Click the **Columns** option (under the ⋯ menu in the filter bar) to customize which metrics appear in your table.
* **Export data:** Click **Export as CSV** in the top filter bar's ⋯ menu to download a spreadsheet of the currently visible prompts.
### Row-level actions
Click the **⋯ (More options)** menu on any prompt row to access:
* **Edit:** Opens the **Edit Prompt** panel to change the prompt text (only if it has zero tracked responses), update the topic, apply tags, and select running countries. This panel will also show estimated monthly credit changes before saving.
* **Refresh Volume:** Manually recalculates the search volume and value for this prompt.
* **Pause / Unpause:** Halts or resumes data collection for the prompt.
* **Delete:** Opens the **Delete Prompt** dialog to permanently remove it.
Click the **⋯ (More options)** menu on a **topic group row** to access:
* **Edit Topic:** Opens the **Edit Topic** dialog to rename the topic or update its description.
* **Delete Topic:** Opens the **Delete Topic** dialog. You will be asked whether you want to "Delete Prompts Only" (which deletes the prompts but keeps the empty topic) or "Delete Topic & Prompts" (which permanently destroys both).
### Reorganize prompts
* **Drag and drop:** Click and hold the grab handle (six dots) on any prompt row to drag it into a different topic, or to reorder it within its current topic.
### Categorize new prompts
If the **Uncategorized prompts** bar is visible at the bottom of the screen, you can:
* **View prompts:** Opens a list of the prompts waiting to be filed.
* **Categorize:** Uses AI to automatically sort all uncategorized prompts into relevant topics.
* **Dismiss (Esc):** Hides the bar.
### Bulk actions
Select multiple rows using the checkboxes to reveal the bulk action bar. You can:
* **Stream Data:** Immediately queues a fresh data run for the selected prompts.
* **Write Content:** Opens the content-drafting flow pre-populated with these prompts (maximum of 100).
* **Pause / Unpause:** Halts or resumes tracking for all selected prompts.
* **Delete:** Opens the bulk deletion dialog.
* **Reset (Esc):** Clears your row selection.
* Open the **M (More) menu** on the bulk bar to access:
* **Tags:** Bulk-assign tags via the "Edit prompt tags" dialog.
* **Locations:** Bulk-assign local tracking areas.
* **Countries:** Bulk-assign tracking countries via the "Edit Countries" dialog.
* **Assign topic:** Move all selected items into a single topic.
* **Refresh volume:** Request updated search volume calculations.
* **View in Olympus / View in Brand Visibility:** Jumps to the analytics dashboard pre-filtered to show only your selected prompts.
* **Create view:** Saves the selected prompts as a custom, reusable Saved View.
* **Export as CSV:** Downloads the selected items to a spreadsheet.
## Data shown
The table merges your configured prompts with ongoing performance metrics drawn directly from AI engines (like ChatGPT, Claude, and Perplexity). Search volume estimates come from historical search engine keyword data. Comparisons (such as Mention Gap and Citation Gap) directly contrast your brand's presence against the competitors you configured for your website.
## Common workflows
**Categorizing a newly imported batch of prompts:**
1. After a CSV import or bulk AI generation, look for the **Uncategorized prompts** bar at the bottom of the screen.
2. Click **View prompts** to review what hasn't been filed.
3. Click **Categorize** to automatically assign them to existing topics (or generate new topics for them).
**Reviewing performance changes over time:**
1. Open the **Date range** filter at the top and ensure a comparison period is active.
2. Look at the **Mention Gap** and **Citation Gap** columns to see if you are gaining ground on competitors.
3. Click on a specific prompt row that interests you to open the **Prompt analytics** side panel and view its Share of Voice over time.
**Moving prompts in bulk:**
1. Select the checkboxes next to multiple prompts (or select an entire topic using the group checkbox).
2. In the bulk action bar that appears, click the **M (More)** button.
3. Select **Assign topic**, pick the destination topic from the dropdown, and confirm.
## Empty, loading, and error states
* **Empty:** If you have no data yet, metric columns will display "No data yet". If a topic is entirely empty, it will show as a placeholder row containing "(0)" (unless you have active text/tag filters, in which case empty topics are hidden).
* **Loading:** When first loading the page, you'll see a large animated spinner. While metrics are being calculated in the background, individual cells will show a brief skeleton shimmer effect.
* **Errors:** If an action fails (like moving a prompt, editing a tag, or running categorization), a red toast notification will appear in the corner explaining the failure (e.g., "Failed to update prompt").
## Linked from / links to
* **Linked from:** The main sidebar navigation, the post-onboarding completion screen, guided product tour links, and saved bookmarks for legacy prompt tabs.
* **Links to:** The **Responses** page (via "View responses" buttons), the full Analytics dashboard (via "View in Olympus"), and the other inner tabs (Personas, Locations, Discover).
## Common support questions
**Why can't I edit my prompt's text?**
Once a prompt has been run and collected AI responses, its base text is locked. This ensures your historical visibility metrics remain accurate to the exact text that was run. If you need a completely different prompt, you should pause the old one and create a new one.
**What does "No data yet" mean in my table?**
Your prompts have been saved and scheduled to run, but no AI responses have been collected and analyzed for the specific date range you have selected in your filters.
**How do I download this list?**
Click the **⋯** menu in the top filter bar, or select specific rows and click **Export as CSV** in the bulk action bar. Note that CSV exports may prompt an upgrade dialog if you are on a Free plan.
# Discovery Run Detail (Discover a Run's Suggested Prompts)
Source: https://docs.athenahq.ai/guides/prompts-discover-id
Shows the prompts a single Discover run found, grouped by topic, so a user can review, filter, and start tracking (or remove) the AI-suggested prompts.
`app.athenahq.ai/prompts?tab=discover`
## Purpose
This page displays the AI-suggested prompts generated by a single prompt discovery run. It allows you to review the candidates, group them by topic, filter by intent or funnel stage, and ultimately decide which prompts to actively monitor by adding them to your tracked prompts.
It sits directly in your prompt discovery workflow, once a discovery run completes (or even while it's still processing), you use this view to curate the results.
## What's on the page
**Page header**
Shows a back-link to the main Discover history page and the name of the current run. The run name can be edited inline by clicking the pencil icon.
**Leg progress panel**
If the discovery run is still in progress, a "Discovering prompts..." panel appears at the top. It displays real-time progress bars for each discovery source (leg). It sits above the results if partial candidates have already appeared, or by itself in the center of the page if no prompts have been found yet.
**Discovery candidates table toolbar**
* **Filters button**: Opens a dropdown to filter candidates by Top volume, Source, Funnel, Intent, or Type.
* **Signal chips**: E.g., "Competitor Gap" or "Social Signal". These toggleable chips only appear if the run found prompts carrying specific recommendation signals.
* **Reset**: Clears all active filters (only appears when filters are applied).
* **Export (Download icon)**: Exports the current filtered list of suggestions as a CSV.
* **Search**: A free-text search box that filters the table by prompt text or topic name.
**Discovery candidates table**
Groups the suggested prompts into collapsible topic sections.
* **(checkbox)**: Selects a row for bulk actions. Clicking the checkbox on a topic header row selects every prompt inside that topic.
* **Prompt**: The suggested prompt text.
* On the bold topic header rows, this displays the topic name, the count of prompts inside it, and a pencil icon to rename the topic.
* On individual prompt rows, this shows the text, an optional signal badge (if applicable), and an info icon showing why it was suggested.
* **Source**: How the prompt was discovered. Hovering the header shows: "How this prompt was discovered / Logical: market analysis from your website, segments and products / Brand: AI brand research with custom inputs / GSC: Google Search Console keyword clustering / Social: Reddit threads, YouTube comments and videos / Keyword sources: brand and competitor keywords, Reddit, YouTube"
* **Funnel**: The buyer-journey stage (TOFU, MOFU, or BOFU). Hovering the header shows: "Where the prompt sits in the buyer journey / TOFU: top of funnel, awareness and discovery / MOFU: middle of funnel, evaluation and consideration / BOFU: bottom of funnel, decision and purchase"
* **Intent**: Searcher's goal (Informational, Commercial, Transactional, Navigational). Hovering the header shows: "The searcher's goal behind the prompt / Informational: looking to learn or research / Commercial: comparing products or services / Transactional: ready to buy or take action / Navigational: looking for a specific brand or page"
* **Type**: Keyword category (Head, Mid tail, Long tail). Hovering the header shows: "The keyword category for this prompt / Head: broad, high-volume keywords / Mid tail: moderate specificity and volume / Long tail: specific, lower-volume queries"
* **Volume**: Estimated monthly search volume. (On topic headers, this is the sum of the group).
* **Value**: Estimated keyword value (CPC). (On topic headers, this is the sum of the group).
**Already tracked section**
A collapsible section at the bottom containing prompts the AI suggested but that you are already monitoring.
* Hovering the info icon displays: "These prompts are already covered by your current monitoring. They matched existing prompts with high similarity (85%+), meaning the same search intent is already being captured."
* Rows inside show the suggested prompt and the text of your existing prompt it is "Similar to". These rows cannot be selected.
**Removed section**
A collapsible section for suggestions you actively dismissed from this run.
* Hovering the info icon displays: "Suggestions you removed from this run. They stay out of the suggestion list; restore one to review it again."
* Rows inside show the removed prompt text and a "Restore" button.
## What you can do here
* **Select prompts**: Click individual checkboxes or shift-click to select a range. Click a topic header's checkbox to select all prompts in that group.
* **Start tracking**: After selecting rows, click **Start tracking** in the floating command bar (or press `T`). This opens a confirmation dialog showing how many new prompts will be tracked, how many duplicates are being skipped, and an estimate of the monthly credit cost. Confirming tracks the prompts and shows a success dialog with a "View in Manage" link.
* **Remove suggestions**: After selecting rows, click **Remove** in the floating command bar (or press `Backspace`). This opens a confirmation dialog. Confirming removes them from the main list and drops them into the "Removed" section at the bottom.
* **Clear selection**: Click **Reset** in the command bar (or press `Esc`).
* **Restore a suggestion**: Open the "Removed" section at the bottom and click **Restore** on a row to put it back in your active suggestion list.
* **Rename the run**: Hover over the run name in the top page header and click the pencil icon. Type the new name and press `Enter` (or click away) to save. Press `Esc` to cancel.
* **Rename a topic**: Hover over a bold topic header row and click the pencil icon. If you type the name of an already-existing topic, a dialog will ask if you want to merge the two groups.
* **Export CSV**: Click the download icon in the top right to download your filtered suggestion list.
* **Filter and sort**: Use the "Filters" dropdown to narrow down by Source, Funnel, Intent, Type, or "Top volume". Click table column headers to sort ascending or descending.
* **Resize columns**: Hover over the divider between column headers and drag to resize them.
## Data shown
The page displays the AI-generated prompt recommendations discovered during this specific run for your active website. Suggestions are enriched with estimated volume, value, intent, and funnel data. The system automatically cross-references these suggestions against the prompts you currently track to identify duplicates.
## Common workflows
**Review and track new prompts**
1. Open a discovery run from the Discover tab.
2. Browse or filter the table to find relevant prompts.
3. Check the boxes next to the prompts (or whole topics) you want to monitor.
4. Click **Start tracking** in the floating command bar.
5. Review the credit estimate in the dialog and click **Start tracking** to confirm.
6. Click **View in Manage** on the success screen to see them in your tracked list.
**Clean up unwanted suggestions**
1. Select the checkboxes of prompts that aren't relevant to your brand.
2. Press `Backspace` or click **Remove** in the command bar.
3. Confirm the removal in the dialog. The prompts vanish from your active list and drop into the "Removed" section at the bottom.
## Empty, loading, and error states
* **Loading**: A full-page animated loader displays while the run details are fetching.
* **Empty**: If the run completes but finds zero suggestions, a "No prompts discovered" message appears. If the run crashed or only partially completed, an extra note says, "This run could not finish. Run discovery again later."
* **Error**: If the run ID is invalid or deleted, a simple "Run not found" message appears.
## Linked from / links to
* **Linked from**: The **Prompts > Discover** tab (the history list of discovery runs).
* **Links to**: The **Prompts > Manage** tab (via the "View in Manage" button in the tracking success dialog).
## Common support questions
**What does "Already tracked" mean?**
The AI suggested these prompts, but our system noticed they are extremely similar (85%+ match) to prompts you already actively track. We flag them here so you don't accidentally waste credits tracking duplicates.
**I accidentally removed a prompt. Can I get it back?**
Yes. Scroll to the very bottom of the table and click to expand the "Removed" section. Find the prompt and click the "Restore" button next to it.
**Why are the Start Tracking and Remove buttons disabled?**
You need "Write" access to Prompts to track or remove suggestions. If your role is set to "View" only, these controls will be disabled.
**Why didn't my CSV export work?**
Exporting discovery data requires a paid subscription plan. If your organization is on the Free plan, clicking the export button will prompt you to upgrade instead.
# Public Content Suggestions Report
Source: https://docs.athenahq.ai/guides/report-content-shareId
A public, no-login page where anyone holding the shareable link can read an AI-rewritten version of a prospect's article with Athena's inline 'Before/After/Why' content suggestions highlighted.
`app.athenahq.ai/report/content`
## Purpose
The Public Content Suggestions Report is a public, read-only webpage used by your customers to share AI-generated rewrite suggestions with their prospects or clients. When an Athena user creates a "content pitch" for a prospect's article, they generate a shareable link that leads directly to this page.
Anyone with the link can view the report without logging in or creating an Athena account. The page displays the prospect's original article with inline highlights showing exactly how Athena would rewrite specific passages to improve their visibility in AI search answers.
## What's on the page
* **Sticky Header:** Displays the AthenaHQ logo and "Powered by AthenaHQ" text. On the right side, it contains quick actions for sharing the report.
* **Report Title & Subtitle:** Displays the heading "Content Suggestions Report" along with a description: "How Athena would rewrite \[Prospect Name or URL] to show up in AI answers."
* **Optimizing for these AI prompts:** A section that lists the specific AI search queries (prompts) the report was generated to target. Each prompt is displayed as a small pill-shaped chip. This section only appears if the creator selected target prompts.
* **Article Panel:** The main body of the page. It shows the prospect's full article text, marked with highlighted passages wherever Athena has a rewrite suggestion. A small note at the top explains: "X inline suggestions. Click a highlighted passage to review it."
* **Footer:** A simple sign-off at the bottom reading "AthenaHQ, the AI search optimization platform" along with a link reading "Get this for your site".
### Drilldowns: Floating Suggestion Card
Clicking any highlighted text in the article opens a floating **Before/After/Why** card directly beneath the text:
* **Header:** Shows an Athena avatar, "Athena" as the author, the date the suggestion was generated, and the text "Suggested rewrite".
* **Prompt Badge:** If the suggestion targets a specific prompt, it displays a badge like "Prompt: \[Target Prompt]".
* **Before:** The original text from the article (highlighted in light red).
* **After:** Athena's newly optimized text (highlighted in light green).
* **Why:** A brief explanation of why the change improves AI search visibility (highlighted in light gray).
* **Action Link:** A link at the bottom of the card reading "Athena writes suggestions like this for every page on your site ➔".
## What you can do here
* **Review suggestions:** Click any highlighted passage in the text to open the floating suggestion card. Click anywhere else on the page or press the `Escape` key to close it.
* **Copy link:** Click the "Copy link" button in the top right to copy the report's URL to your clipboard. A "Link copied" confirmation toast will appear.
* **Share:** Click the "Share" button in the top right. If you are on a device that supports native sharing (like a mobile phone), it opens the system's share sheet. Otherwise, it defaults to copying the link to your clipboard.
* **Learn more about AthenaHQ:** Click "Get this for your site" in the footer or "Athena writes suggestions like this for every page on your site" inside a suggestion card to visit the public AthenaHQ marketing website.
## Data shown
All data shown on this page comes directly from the Content Pitch configured by the Athena user. It includes the scraped text of the prospect's original web page, the list of AI prompts the user chose to target, and the actual rewrite suggestions (Before, After, and Why text) generated by Athena.
## Common workflows
**Viewing and reviewing a prospect report:**
1. The prospect opens the shared link provided by the Athena user.
2. The prospect scrolls through the article and looks for highlighted passages.
3. The prospect clicks a highlight to open the floating card and compare the "Before" and "After" text.
4. To dismiss the card and keep reading, the prospect clicks outside of the card.
**Sharing the report with a colleague:**
1. The prospect views the report and decides to forward it to their internal team.
2. They click the "Share" button in the top-right corner.
3. They select their email or messaging app from their device's native share menu, or simply paste the automatically copied link into a message.
## Empty, loading, and error states
* **Loading / Processing:** If the prospect opens the link while Athena is still generating the report, they see skeleton placeholder lines and a card that says: **"Generating suggestions for this page. Usually takes a couple of minutes. This page updates automatically."** The page will automatically load the content once it finishes.
* **Failed Generation:** If the system failed to scrape or generate the report, the page shows a card reading: **"This report couldn't be generated. Ask the person who sent you this link to try creating it again."**
* **No Suggestions Found:** If generation completes but the article is already perfectly optimized, the page shows: **"No suggestions found. Athena reviewed this page and had no rewrite suggestions to make."** The article text may still render below this, but without highlights.
* **Report Unavailable (Deleted/Invalid):** If the Athena user deleted the report, or the link URL is broken, the entire page is replaced with a card reading: **"This report isn't available. The link may have been taken down by its creator. Ask them for a fresh link."**
* **System Error:** If the report exists but Athena's servers temporarily fail to load it, a card reads: **"Couldn't load this report. Something went wrong on our side. Refresh the page to try again."**
## Linked from / links to
* **Linked from:** External emails, messages, or documents where an Athena customer has pasted the share link.
* **Links to:** The AthenaHQ marketing website (`https://www.athenahq.ai`).
## Common support questions
**Can the prospect edit the text or accept the suggestions directly on this page?**
No. The public report is strictly read-only. It is designed as a presentation tool. To actually implement the changes, the prospect would need to update their own website's CMS, or become an Athena customer.
**Does the prospect need to create an Athena account to view the link?**
No. The link is completely public and requires no login. The unique, unguessable string of characters in the URL is what grants them access.
**Will search engines index this page and penalize the prospect for duplicate content?**
No. The public report pages are strictly coded to block search engines from crawling or indexing them (`noindex, nofollow`). They will not show up in Google and will not affect the prospect's SEO.
**Why did my prospect see a "This report isn't available" message?**
This happens if you (the Athena user) deleted the content pitch from your Athena workspace, or if the prospect copied an incomplete/broken URL. You will need to generate a new pitch and send them a fresh link.
# Public AI Search Report
Source: https://docs.athenahq.ai/guides/report-pitchId
Public, shareable read-only AI search performance report for a single pitch/brand, showing share of voice, model performance, brand traits, citation sources, competitor landscape, and underlying AI responses.
`app.athenahq.ai/pitch-workspace`
## Purpose
The Public AI Search Report is a shareable, read-only dashboard that visualizes how a specific brand performs across major AI search engines. It allows Athena customers to securely share AI visibility insights, like share of voice, model performance, and brand traits, with external stakeholders, executives, or clients who do not have an Athena account.
Because this is a public-facing view, it strips away Athena's internal workspace editing tools while keeping all the rich data, charts, and AI response drill-downs fully interactive.
## What's on the page
**Page header**
Displays the brand's logo and name at the top left. On the right, it features a **Copy link** button to easily share the report URL.
**Report header**
Shows the title "AI search preview report", alongside an audit date and a "Powered by AthenaHQ" link.
**Landing Page CTA banner**
If this report was generated via a public marketing landing page, a banner appears reading "Track this brand across every AI surface" with **See pricing** and **Book a demo** action buttons.
**Metric cards row**
Four top-level statistics summarizing the brand's performance:
* **Share of voice**: "The percentage of mentions your brand receives compared to all brands. Click for details."
* **Brand mentions**: "Percentage of AI responses that mention your brand. Click for details."
* **Responses analyzed**: "Total AI responses collected and analyzed for this report"
* **Models tested**: "AI models queried while building this report"
**Share of voice (SOVChartCard)**
A donut chart visualizing "How often AI mentions your brand vs competitors." The legend ranks the primary brand (marked "You") and all tracked competitors by their share percentage and absolute mention count.
**AI model performance (ModelPerformanceCard)**
A bar list breaking down "How often each AI model mentions your brand." It shows an overall mention rate at the top, followed by a breakdown for each AI product (e.g., ChatGPT, Perplexity, Gemini, Claude, AI Overview, Copilot, Grok, DeepSeek, AI Mode).
**Positive & Negative brand traits (BrandTraitsCard)**
Two radar (spider) charts comparing how frequently specific positive or negative attributes are tied to the brand versus "All Competitors". *Note: If a brand has no data for a specific trait type, that entire card disappears from the grid.*
**Top citation sources (CitationSourcesCard)**
A ranked list showing "Domains AI models cite most when answering related prompts," complete with favicons, mention counts, and a visual proportion bar.
**Competitive landscape (CompetitorAnalysisCard)**
A ranked list showing the "Share of all brand mentions, including yours." It displays your brand and competitors, their share percentages, and visual bars.
**Responses table card**
A searchable data table listing every individual AI response collected to build this report.
* **Model**: Which AI model/product produced this response, shown with its product icon.
* **Mentioned**: Whether the tracked brand was mentioned in this AI response ('Yes' or 'No'). 'No' appears in orange if competitors were mentioned instead.
* **Competitors Mentioned**: Logos/avatars of up to 4 competitors mentioned in this response (with a '+N' overflow badge and tooltip listing the rest), or a 'No' pill if none were mentioned.
* **Prompt**: The specific prompt variation text sent to the AI model, with search-query text highlighted.
* **Response**: The raw AI response text (truncated), with search-query text highlighted. Some pre-scrape rows may show a 'View' button instead of text.
**Response Details (Drilldown)**
Clicking any row in the Responses table opens a side drawer detailing that specific AI interaction. It includes:
* **Metadata row 1**: Date, Model, and Prompt Type (e.g., Branded, Non-Branded).
* **Metadata row 2**: Mentioned (Yes/No), Market Position (rank number), and Competitors Mentioned.
* **Prompts**: The Base Prompt and the exact Variation used.
* **Content section**: The full AI response text with highlighting. For Google AI Overview responses, this section may contain expandable widgets for **Organic Results**, **People Also Ask**, and **Related Searches**, or a notice saying "No AI Overview was shown for this query".
* **Sources**: A list of inline citation domains used by the AI.
## What you can do here
* **Copy link**: Click the **Copy link** button in the top right. The icon briefly animates to a checkmark to confirm the public URL is on your clipboard.
* **View metric definitions**: Click the info icon on the **Share of voice** or **Brand mentions** cards to open a dialog explaining the formula, definition, and key insights. Hover over the info icon on **Responses analyzed** or **Models tested** for a quick tooltip.
* **Explore AI responses**: Click any row in the Responses table to open the Response Details drawer.
* **Navigate responses quickly**: While the drawer is open, use the up and down arrow buttons in the top right of the drawer (or the up/down keys on your keyboard) to step through adjacent responses without closing the drawer.
* **Open cited sources**: Inside the response drawer, click any source/citation pill to open that URL in a new browser tab.
* **Search responses**: Type into the "Search responses" input box above the table. This filters the *currently loaded* rows client-side by matching the prompt or response text, highlighting the matches.
* **Load more responses**: Scroll to the bottom of the table to trigger infinite scroll, or click the **Load More** button. *(Note: This is disabled while actively searching).*
* **Expand SERP features**: For Google AI Overview responses in the drawer, click to expand the **Organic Results**, **People Also Ask**, or **Related Searches** sections.
* **Visit AthenaHQ**: Click the "Powered by AthenaHQ" logo to visit the Athena homepage. If the Landing Page CTA banner is visible, click **See pricing** or **Book a demo** to open those external links.
## Data shown
This page displays a read-only snapshot of the AI search performance for a specific brand/pitch. The data includes the brand's configured competitors, the exact prompts used for testing, the AI responses returned from various providers, the brand attributes detected in those responses, and the domains cited by the AI. For Google AI Overview responses, it also includes live search engine result page (SERP) metadata.
## Common workflows
**Share the report**
1. Open the `/report/[pitchId]` link in your browser.
2. Click the **Copy link** button in the top right of the page header.
3. Paste the URL into an email, Slack, or presentation to share the insights with stakeholders.
**Review AI visibility at a glance**
1. Scan the four top metric cards to understand the brand's share of voice, mention rate, and the volume of models/responses analyzed.
2. Review the **Share of voice** donut chart and the **Competitive landscape** list to see exactly where the brand sits in the market.
3. Check the **AI model performance** card to identify which specific AI products favor the brand.
**Investigate a specific AI response**
1. Scroll down to the Responses table.
2. Optionally type a keyword into the "Search responses" box to find specific mentions.
3. Click a row to open the Response Details drawer.
4. Read the full AI output, check the cited sources, and use the arrow keys to quickly review the next response in the list.
## Empty, loading, and error states
* **Loading**: While fetching the data, skeleton placeholders appear for the page title, all metric cards, chart cards, and the responses table. If the pitch itself is still generating, a full-page "Building your report" screen with an animated loader appears, which automatically polls for updates every 5 seconds.
* **Empty**:
* If there is zero mention data, the Share of voice card shows a blurred placeholder with the message "No share of voice data available".
* If a brand has no positive or negative attribute data, the respective Brand Traits radar cards will completely disappear from the layout.
* If a search yields no results in the table, it displays "No responses found."
* **Error**: If the pitch record cannot be found or the network request fails, a full-page "Couldn't load this report" status screen appears with a **Try again** button. If the pitch processing outright failed on Athena's end, a "Report processing failed" screen appears (with a **Create another pitch** button if you are logged in).
## Linked from / links to
* **Linked from**: Usually accessed via a shared link provided by an Athena user (e.g., copied from the internal Pitch Workspace).
* **Links to**: External source/citation URLs referenced within individual AI responses. Links to the Athena homepage ("Powered by AthenaHQ"), and optionally to pricing/demo pages if the landing page banner is active.
## Common support questions
**Why don't I see the drag-and-drop handles to reorganize the report?**
You are viewing the public, shareable version of the report. The drag-and-drop customization features are only available to logged-in Athena users viewing the report from their internal workspace.
**What does "Brand Mention Rate" mean?**
Brand Mention Rate is the percentage of total AI responses collected for this report that included your brand. You can click the info icon on the Brand Mentions card to see the exact formula and key insights.
**Why is the "Positive brand traits" card missing?**
The radar charts for Positive and Negative brand traits will automatically hide themselves if the AI did not generate any associated attributes for the brand or its competitors during this specific scan.
**Why did the "Load More" button disappear from the Responses table?**
The "Load More" button (and infinite scrolling) is temporarily disabled while you have text entered in the "Search responses" box. Searching currently only filters the rows that have already been loaded into your browser.
**What does "No AI Overview was shown for this query" mean?**
This message appears in the Response Details drawer when Google was queried with your prompt, but Google decided not to generate an AI Overview at the top of the search results for that specific phrase.
**Why does the "Create another pitch" button not work for me?**
If you encounter a "Report processing failed" screen and click "Create another pitch", it redirects to an internal Athena app page. If you are an external stakeholder without an Athena account, this link will not work for you.
# Report Builder (Edit Report)
Source: https://docs.athenahq.ai/guides/reports-id
Lets a user edit an existing scheduled report's charts, name, delivery schedule, and recipients, and preview or manually send the report.
## Purpose
The Report Builder page allows customers to edit an existing scheduled report. Here, they can modify which charts are included, adjust shared filters, rearrange the report layout, and turn competitor comparisons on or off. They can also access the report's settings to change its name, delivery schedule, and recipients, or manually trigger an immediate send to all configured recipients.
## What's on the page
### Page header
* **Page Title:** Displays "Edit \{report name}".
* **Action buttons:** Includes buttons for **Settings** and **Send now**. If a recent chart edit failed to save, a **Retry save** button appears.
### Chart palette (left sidebar)
* **Chart types:** A list of supported dashboard charts (e.g., Share of Voice, Mention Rate, Citation Rate, Attributed Citations Growth, Positive Brand Traits, Negative Brand Traits, Position over Time). Each has a toggle switch to include or remove it from the report.
* **Miscellaneous:** Contains a **Competitor lines** toggle. Turning this on adds a competitor-average comparison line to any supported charts in the report.
### Report filter bar
* **Shared Filters:** A filter bar similar to the main dashboard. Adding filters here (like models, prompt status, competitors, personas, locations) applies them to every chart in the report.
* **Saved views:** A dropdown that allows users to quickly apply an existing saved filter view to the report.
* **Clear All:** Appears when filters are active to quickly remove them.
* *Note:* If individual charts in the report have divergent filters configured, the shared filter bar is replaced by a message: "Charts have individual saved filters. Shared filter editing is disabled to avoid overwriting them."
### Report canvas
* **Chart Cards:** A grid displaying a live preview of each chart currently added to the report. The charts reflect the chosen filters and competitor line settings.
* **Empty State:** If no charts are selected, a "No charts yet" message appears, instructing the user to switch on chart types in the sidebar.
### Report settings modal (via Settings button)
* **Build / Send Tabs:** The modal splits configuration into two steps. The **Build** step mirrors the chart palette and canvas from the main page. The **Send** step controls delivery.
* **Name:** A text input to rename the report.
* **Frequency:** Tabs to select **Weekly**, **Monthly**, or **Quarterly**.
* **Schedule Controls:** Dropdowns for **Day of week** (or **Day of month**), **Delivery time** (e.g., 09:00), and **Time zone**.
* **Delivery method:** A dropdown to choose **Email**, **Slack direct message**, or **Slack channel**.
* **Recipients Picker:** Depending on the delivery method, an input to **Add people by email**, **Choose channel**, or **Choose person**.
* **Email preview:** A side panel displaying a live preview of the actual HTML email that will be delivered, based on the current chart selections.
### Send now dialog (via Send now button)
* **Confirmation:** A dialog confirming immediate delivery. It summarizes the number of active eligible recipients and provides a breakdown (e.g., "2 emails, 1 Slack channel").
## What you can do here
* **Add or remove charts:** Toggle switches under **Chart types** in the left sidebar to add or remove specific charts.
* **Reorder charts:** Click and drag the chart preview cards in the main canvas to change the order they appear in the final email.
* **Filter report data:** Use the filter bar to apply global filters (like specific models or locations) to the entire report.
* **Apply saved views:** Use the saved views dropdown to apply pre-configured dashboard filters. *(Note: Unsupported filters like date ranges or text searches are ignored, and a toast will notify you of any skipped filters).*
* **Toggle competitor comparisons:** Switch **Competitor lines** on or off in the sidebar.
* **Edit report schedule and recipients:** Click **Settings**, then go to the **Send** step to change the report's frequency, time zone, or add/remove recipients.
* **Send the report immediately:** Click **Send now** in the top right to instantly deliver the report to all active recipients.
* **Connect Slack:** If no Slack workspace is connected, selecting a Slack delivery method in the settings modal reveals a **Connect** button that takes you to the integrations page.
## Data shown
* **Chart Previews:** Live dashboard data matching the report's active filters and time period (e.g., the last 7 days for a weekly report).
* **Recipients:** The list of configured email addresses and Slack destinations. Visibility depends on permissions: organization admins see everyone, while report creators see only their own email.
## Common workflows
**Adding a chart to the report:**
1. Look at the **Chart types** list in the left sidebar.
2. Find the chart you want to add (e.g., "Mention Rate") and toggle its switch on.
3. The chart preview will instantly appear in the report canvas.
4. Click and drag the chart card to position it in your preferred order.
**Sending a report right now:**
1. Ensure you have finished making any chart or filter edits (the report automatically saves your changes).
2. Click **Send now** in the top right corner.
3. Review the confirmation dialog to see how many people will receive it.
4. Click **Send now** in the dialog to dispatch the emails and Slack messages.
**Adding a Slack channel recipient:**
1. Click **Settings** in the top right to open the modal.
2. Ensure you are on the **Send** step.
3. Change the **Delivery method** to **Slack channel**.
4. Use the **Choose channel** dropdown to select the destination.
5. Click **Schedule** to save your changes.
## Empty, loading, and error states
* **Loading:** Skeleton placeholders appear for the header actions and large gray boxes appear in the canvas while data loads.
* **Empty canvas:** If all charts are toggled off, a "No charts yet" message is displayed with a prompt to enable chart types from the sidebar.
* **Error loading report:** If the report has been deleted or the user loses access, a "Report unavailable." message appears and the user is automatically redirected to the dashboard.
* **Save error:** Chart edits save automatically. If a save fails, a red **Retry save** button appears in the top right.
## Linked from / links to
* **Linked from:** The main **Reports** list page, and occasionally directly from the dashboard after creating a new report.
* **Links to:** The **Connect** button for Slack links to `/settings/integrations?provider=slack-reports`. If a report fails to load, it redirects to the `/olympus` dashboard.
## Common support questions
**Why is the "Send now" button disabled?**
The button is disabled if there are no active, eligible recipients configured to receive the report, or if the report is currently saving a recent change to its charts. You can add recipients by clicking **Settings**.
**Why can't I edit the filters at the top of the report?**
If the charts in this report were configured with their own individual, differing filters, the shared global filter bar is locked. This prevents a global change from accidentally overriding the specific filters you set up for individual charts.
**Why can't I add my colleague's email to the report?**
Unless you are an Organization Admin, you are only permitted to manage your own personal email subscription for a report. Organization Admins have full access to add any email address or Slack channel.
**I applied a saved view, but some filters are missing. Why?**
Reports do not support certain dashboard filters, such as specific date ranges or text-based searches. When you apply a saved view, the report builder automatically skips these unsupported fields and shows a pop-up notice explaining which ones were ignored.
# Responses
Source: https://docs.athenahq.ai/guides/responses
Browse and inspect every individual AI-model response captured for the tracked prompts, with rich filtering, column customization, and a detail drawer.
`app.athenahq.ai/responses`
## Purpose
The Responses page is the core investigative view of your Athena product. It allows you to browse and inspect every individual AI-model response captured for the prompts you are tracking. While dashboards like Olympus show you the big picture, this page lets you read exactly what the AI models said, word-for-word.
Customers rely on this page to dig into the raw data. Whether you need to see exactly why a competitor is being recommended, verify that your brand is being cited accurately, or audit the sentiment of a specific prompt variation, the Responses page provides the granular details.
It features a highly customizable, spreadsheet-like table where you can slice and dice the data using a rich set of filters, toggle specific columns on or off, and export the exact dataset you need for external reporting.
## What's on the page
**Page header**
Displays the "Responses" title. If you navigated here from a specific drilldown (like clicking a stat in the Prompts drawer or the Ads page), a back arrow appears next to the title to return you to your previous view.
**Filter row**
A sticky bar containing your active filters, an "Add filter" button to narrow down the dataset, a Saved Views dropdown, a "Columns" picker, and an "Export as CSV" button. On mobile devices, filters and actions are tucked into a "Filters" button and a "⋯" (More) menu.
**Responses table**
A robust, spreadsheet-style table where each row represents a single answer generated by an AI model. The table supports infinite scrolling via a "Load More" button at the bottom.
**Responses drawer (Drilldown)**
Clicking any row in the table opens a side drawer. This drawer reveals the full response text, prompt details, competitor and source links, attributes, sentiment, and edit controls. Opening the drawer automatically updates the page URL so you can easily link directly to a specific response.
**Export dialog**
Triggered by clicking "Export as CSV", this modal allows you to choose exactly how many responses you want to export to a spreadsheet.
## What you can do here
* **Filter data**: Click "Add filter" to narrow the table by dozens of criteria (Date Range, Models, Prompt Status, Sentiment, Brand Mentioned, Has Sources, Competitors, and more).
* **Search**: Use the "Response search" or "Source Search" filters to find exact keywords within the AI output or cited URLs.
* **Clear filters**: Click "Clear All" to remove all active, non-default filters at once.
* **Customize columns**: Click the "Columns" button (or the "Columns" submenu under the mobile "⋯" menu) to toggle specific data points on or off, and drag to reorder them. Your column layout is saved in your browser storage automatically.
* **Sort and resize columns**: Click any supported column header to toggle ascending/descending sort. Drag the right edge of a column header to resize it, or double-click the edge to automatically fit it to the content.
* **Save your view**: Use the Saved views dropdown to save your current filter configuration, rename it, set it as your default, or share it.
* **Inspect a response**: Click any row in the table to open the Responses drawer for a deeper dive.
* **Navigate quickly**: While the drawer is open, you can use the **Up** and **Down** arrow keys on your keyboard to rapidly navigate to the previous or next response row in the table.
* **Load more data**: Scroll to the bottom of the table and click "Load More" to fetch the next 40 responses.
* **Export as CSV**: Click "Export as CSV" in the toolbar (or mobile "⋯" menu). In the dialog that appears, use the **+** / **-** buttons or the quick-select amounts (1,000, 5,000, 10,000) to adjust the volume. Click "Export all" to pull the entire filtered dataset. Click **Export** to start the download (a progress toast will appear), or **Cancel** to back out.
## Data shown
The table displays the actual responses generated by AI models when answering the prompts you are tracking. It also aggregates the associated brand and competitor logos, derived sentiment analysis, citation checks, and geographic tags applied to those responses. Data updates based on your active schedule and manual prompt runs.
## Common workflows
**Investigate why a competitor is winning a prompt**
1. Open the Responses page (or arrive by clicking an analytic stat in a prompt's drawer).
2. Open the filter menu and set **Brand Mentioned** to "No" and add a **Competitors** filter for your rival.
3. Scan the "Competitors Mentioned" and "Sentiment" columns to see how positively they are portrayed.
4. Click a row to open the drawer, read the full response text, and inspect which sources the AI cited to formulate that answer.
**Audit citation coverage for your brand's content**
1. Add a filter for **Has Been Cited** = "Yes" (or **Has Attributed Citation** = "Yes").
2. Review the "Sources" and "Cited" columns across the table.
3. Click into a row's drawer to inspect the exact URLs the AI model linked back to.
**Export a filtered slice of responses**
1. Apply your desired filters (e.g., specific Date Range, Models, or Competitors).
2. Click **Export as CSV** in the top right of the table.
3. In the Export dialog, adjust how many rows you want to pull (or click "Export all").
4. Click **Export** and wait for the progress toast to complete the download.
## Empty, loading, and error states
* **Empty**: If your filters are too restrictive or no data exists, the table body clears and shows a "No responses found." message.
* **Loading**: While data or filters are initially fetching, an animated loader appears in the center of the table (the column headers remain visible).
* **Error**: General fetching errors are captured by the system in the background. If a CSV export fails, a red error toast appears explaining the failure.
## Linked from / links to
* **Linked from**: Prompt analytics drawers ("View responses" links), Ads page drilldowns, Sankey diagrams, Olympus dashboard metric cards, Content drilldowns, and guided tour links.
* **Links to**: If you arrived via a drilldown (like a specific prompt or the Ads page), a back arrow in the page header will link you back to your exact previous location (e.g., `/prompts` or `/ads`).
## Common support questions
**Why does clicking "Export as CSV" open an upgrade screen?**
Exporting raw response data requires a paid subscription plan. If you are on the Free plan, clicking the export button will prompt you to view our paid plans.
**Where is the Location column? I don't see it in the Columns menu.**
The Location tracking feature is gated by your subscription plan. If your organization does not have the location offering enabled, the column and its filters will not appear.
**Why are some filters missing or ignored when I click through from the Prompts page?**
When you click through to Responses from a specific prompt's analytics drawer, the page strictly scopes the view to that single prompt. Because this is a "complete destination" view, any transient filters you might have stashed from other dashboards (like Olympus) are intentionally discarded so you get an accurate look at just that prompt's data.
**Why is the Personas column blank?**
The Personas column can be toggled on in the Columns menu, but it currently does not render data in the table cells. This is a known limitation.
# Activity Log (Settings › Activity)
Source: https://docs.athenahq.ai/guides/settings-activity
Review and export a chronological audit trail of tracked changes across your organization and websites.
`app.athenahq.ai/settings/activity`
## Purpose
The Activity Log page provides a comprehensive, chronological audit trail of changes made across your organization and its tracked websites. It exists to give administrators and team members full visibility and accountability into workspace actions, helping teams answer questions like "who changed this prompt?" or "when was this user invited?"
Whether you need to troubleshoot an unexpected configuration change, monitor team activity, or export logs for security and compliance reporting, this page centralizes all tracked events. It is a premium feature available on the Enterprise plan.
## What's on the page
### Toolbar band
A control strip positioned just below the page header. The left side houses all filtering controls (date range and specific attribute filters) so you can narrow down the activity you want to see. The right side contains the **Export CSV** button.
### Audit log timeline table
The main area of the page is a scrollable table containing the matching activity records. The events are grouped chronologically by date (e.g., "Today", "Yesterday"). As you scroll to the bottom, the table automatically loads more events. A footer at the very bottom displays your progress, such as "50 of 200 events".
### Event details modal
Clicking a log row opens a dialog containing the technical details of that specific event.
* **Changes**: If an item was modified, this section displays the exact raw data "Before" and "After" the change in a code-like format.
* **Metadata**: Additional system-level context recorded during the event.
## What you can do here
* **Change date range**: Click the date dropdown (which defaults to "All time") to restrict logs to a specific window. You can choose presets like "Last 7 days", "Last 30 days", or "Last 90 days".
* **Filter activity**: Click **Filter** (or **Add filter** if filters are already active) to narrow the list. You can filter by Actor role, Actor, Website, Event categories, Event (using free-text like `user:*`), or Status.
* **Clear all**: When filters are applied, a red **Clear all** button appears. Clicking it removes all active filters at once.
* **Export CSV**: Click **Export CSV** to download a spreadsheet of your current view. Note that exports are capped at 10,000 rows.
* **Collapse/expand date groups**: Click any date header (e.g., "Today, Oct 24, 2023") to hide or reveal all the log entries for that specific day.
* **View event details**: Click anywhere on a specific log row to open the Event details modal and inspect exactly what changed.
* **Upgrade plan**: If your workspace is not on the Enterprise plan, the page will display an "Activity log" card explaining the feature is locked. You can click **Upgrade plan** to be taken to your billing settings.
## Data shown
The Activity Log displays an ongoing record of mutations and actions performed across your Athena workspace, from team member invitations to prompt edits, website deletions, and billing changes.
If you are an organization member, you will see events spanning the entire workspace. If you are an external member invited only to specific websites, your view is restricted solely to events affecting your assigned websites. To protect privacy, actions taken by organization members on resources you do not have access to will anonymize the actor as "Organization member" or "Organization API key".
## Common workflows
**Investigate what happened to a specific resource**
1. Navigate to Settings › Activity.
2. Click **Filter** and select **Event categories** or **Event** to narrow down the action type.
3. Optionally, add a **Website** filter to restrict the search to a specific domain.
4. Scroll through the timeline or adjust the Date range until you find the relevant entry.
5. Click the row to open the Event details modal and view the "Before" and "After" changes.
**Export activity for compliance reporting**
1. Open the Activity page.
2. Use the Date range picker or filters to narrow down the logs you need. Ensure the total number of events is under 10,000.
3. Click the **Export CSV** button in the top right corner.
4. A CSV file named `audit-logs-[date].csv` will download to your computer.
## Empty, loading, and error states
* **Empty state**: If no events match your current filters, the table displays "No activity in this period" with the suggestion "Try adjusting your filters or date range." If your workspace has no recorded activity at all, you will see a simple "No activity available" message.
* **Plan locked**: If your workspace is on a tier below Enterprise, you will see an "Activity log" screen with an icon and an **Upgrade plan** button instead of the timeline.
* **Loading state**: While logs are being fetched, the page displays placeholder skeleton shapes mirroring the table rows. A small "Loading more" spinner appears at the bottom of the table when fetching older events during a scroll.
* **Error state**: If Athena temporarily cannot verify your plan access, a "Couldn't verify access" warning appears alongside a **Retry** button.
## Linked from / links to
* **Linked from**: You can access this page by clicking **Activity** in the Settings sidebar.
* **Links to**: The **Upgrade plan** button (shown on locked tiers) routes directly to your `/settings/billing` page.
## Common support questions
**Why is the "Export CSV" button disabled?**
Exports are strictly limited to 10,000 records. If your current view contains more matching events, the button becomes unclickable. Hovering over it will display a tooltip stating: *"Export is limited to 10,000 records (\[number] match). Narrow the date range or filters."* You must apply filters or shorten your date range to proceed.
**Why can't I click on certain rows in the activity log?**
Rows are only clickable if they contain deeper technical details. If an action didn't generate underlying "Before and After" changes or extra system metadata, the row will not show a right-facing arrow on hover and cannot be clicked.
**Why do I see "Organization member" instead of a person's actual name?**
If you are an external user with access limited to specific websites, Athena masks the identities of workspace members you don't share website access with. This ensures organizational privacy while still letting you see that an action occurred.
**Why doesn't the "Actor role" filter appear for me?**
If you are a website-scoped external member, you do not have permission to view organization-wide role assignments. Consequently, the "Actor role" filter is hidden from your view, and the "Organization" option is removed from the Website filter.
# API & MCP Settings
Source: https://docs.athenahq.ai/guides/settings-api
Lets org/website admins create and manage API keys, view API/MCP/Looker Studio setup instructions, and configure embed (iframe) credentials for embedding the AthenaHQ dashboard elsewhere.
`app.athenahq.ai/settings/api`
## Purpose
Lets organization and website admins create and manage API keys, view API/MCP/Looker Studio setup instructions, and configure embed (iframe) credentials for embedding the AthenaHQ dashboard elsewhere.
## What's on the page
* **API permissions banner**: A dismissible notice explaining that API keys bypass member role and permission restrictions.
* **View-only banner**: A floating pill shown to members who can view API settings but do not have write access.
* **Tabs (API keys / Embed)**: Switches between managing API keys and managing embed domains/tokens. Only shown when the organization also has embed access.
* **API keys panel header**: Shows the total count of keys, a "Guides" dropdown (containing "MCP setup", "Looker Studio setup", and "API documentation"), and a "Create API Key" button.
* **API Keys table**: Lists all API keys for the organization or website scope.
* **Name**: The user-assigned label for the API key.
* **Key**: Masked key prefix shown as a code chip. The full secret is never re-displayed.
* **Websites**: Which websites the key can access. Displays an "All Websites" badge, "None", or up to 4 website logos plus a "+N" overflow count with a tooltip listing the rest.
* **Created**: Date the API key was created.
* **Created By**: Email of the user who created the key.
* **(actions)**: A ⋯ (kebab) menu with "Edit" and "Delete" actions. Disabled unless the current user has permission to mutate that specific key.
* **Locked API upsell**: If your organization is on the Free plan or lacks API access, a splash screen is shown instead of the API keys panel. It displays a "Get API access" (or "Subscribe") button for admins, or a "Contact Team" button for non-admins.
* **Embed tab: Allowed domains**: Lists domains permitted to embed the Athena dashboard via iframe, with an "Add Domain" flow.
* **Domain**: The `https://` (or `http://` for localhost) domain permitted to embed the dashboard, alongside the date it was added.
* **(actions)**: A ⋯ menu with a "Delete" action.
* **Embed tab: Embed tokens**: Lists embed auth tokens used to authenticate requests.
* **Name**: Token label.
* **Status**: Badge reading "Active" (indigo) or "Paused" (orange).
* **Last used**: Date of last use, or "Never used".
* **Created**: Creation date (appears when hovering over the row).
* **(actions)**: A ⋯ menu with "Pause" (or "Unpause") and "Delete" actions.
* **Embed tab: How to embed Athena**: An accordion section containing the iframe snippet, parameter reference, and a backend JWT-signing code example.
## What you can do here
* **Dismiss the API permissions banner**: Click the "X" (Dismiss) button to hide the banner permanently.
* **Create an API key**: Click "Create API Key" to open a dialog. You can name the key, choose the access scope ("All websites" or "Specific websites"), and select websites. On submit, the generated secret is shown exactly once.
* **Edit an API key**: Inside the ⋯ menu on a key row, click "Edit" to rename the key or change its website access scope.
* **Delete an API key**: Inside the ⋯ menu on a key row, click "Delete". This requires confirmation ("Are you sure you want to delete '\'? This action cannot be undone.").
* **View MCP setup**: Inside the "Guides" dropdown (or the empty state shortcut card), click "MCP setup". This opens a dialog with the Claude.ai connector URL and a generic MCP client config to copy.
* **View Looker Studio setup**: Inside the "Guides" dropdown (or the empty state shortcut card), click "Looker Studio setup". This opens a dialog with connection instructions.
* **View API documentation**: Inside the "Guides" dropdown (or the empty state shortcut card), click "API documentation" to open the docs in a new tab.
* **Upgrade to unlock API access**: If the feature is locked, click "Get API access" or "Subscribe" to view a live prorated price quote and start the checkout process.
* **Contact Team**: If you are not an admin and the API is locked, click "Contact Team" to open a scheduling widget.
* **Switch tabs**: Click "API keys" or "Embed" to switch between the two panels.
* **Add an embed domain**: On the Embed tab, click "Add Domain". Enter the domain, optionally generate a token, and copy the provided credentials.
* **Delete an embed domain**: Inside the ⋯ menu on a domain row, click "Delete". This requires confirmation ("Are you sure you want to delete \? This will prevent embeds from this domain from loading.").
* **Create an embed token**: On the Embed tab, click "Create Token". Enter a name and copy the generated secret/JWT secret/iframe snippet.
* **Pause / Unpause an embed token**: Inside the ⋯ menu on a token row, click "Pause" or "Unpause" to toggle its ability to authenticate embed requests.
* **Delete an embed token**: Inside the ⋯ menu on a token row, click "Delete". This requires confirmation ("Are you sure you want to delete the token '\'? This action cannot be undone.").
* **Copy credentials**: Use the copy buttons provided in the dialogs and the "How to embed Athena" accordion to copy tokens, secrets, or URLs.
* **View embed instructions**: Click the "How to embed Athena" accordion to expand iframe usage instructions.
## Data shown
* Your organization's API keys (scoped to the entire organization or specific websites).
* The websites accessible to you and your organization.
* Website logos corresponding to the websites an API key can access.
* Your organization's embed-allowed domains and embed auth tokens.
* A live billing quote if you are purchasing API access.
## Common workflows
**Create and copy a new API key**
1. Click "Create API Key".
2. Enter a name.
3. Choose "All websites" or "Specific websites" (organization admins only; website members are scoped automatically).
4. Select websites if scoped.
5. Click "Create key".
6. Copy the one-time secret shown in the success dialog.
7. Click "Done".
**Set up an MCP or Looker Studio integration**
1. Open the "Guides" dropdown (or click the shortcut card if you have no keys).
2. Choose "MCP setup" or "Looker Studio setup".
3. Follow the copyable connection URL/config or step-by-step instructions.
4. (If using a generic MCP client) create an API key first and paste it into the configuration.
**Upgrade to unlock API access**
1. Navigate to the API settings page and see the locked API upsell.
2. If you are an admin: click "Get API access", review the live price quote, and click "Subscribe".
3. If you are a non-admin: click "Contact Team" to schedule a call.
4. On success, the API keys panel replaces the upsell.
**Embed the Athena dashboard on a partner site**
1. Switch to the "Embed" tab.
2. Click "Add Domain" and enter the target domain.
3. Continue to generate a token for that domain.
4. Copy the embed token, JWT secret, and iframe snippet.
5. Implement backend JWT signing per the shown Node.js example.
6. Paste the iframe snippet into the partner site.
**Revoke a compromised or unused API key**
1. Locate the key row in the API Keys table.
2. Open the ⋯ (kebab) menu.
3. Click "Delete".
4. Confirm deletion in the dialog.
## Empty, loading, and error states
* **Empty**:
* API keys: Shows a key icon, "Create your first API key" heading, description, "Create API Key" button, and shortcut cards for MCP, Looker Studio, and API docs.
* Domains: Shows a globe icon and "No domains added yet".
* Tokens: Shows a key icon and "No tokens created yet".
* **Loading**: Shows a centered spinning loader while organization, website, or permission data resolves.
* **Error**: Loading and updating errors surface as toast notifications at the bottom of the screen (e.g., "Failed to add domain", "Failed to create token", "Failed to update API key").
## Linked from / links to
* **Linked from**: Settings navigation (Settings > API) and the direct URL `/settings/api`.
* **Links to**:
* AthenaHQ API documentation (external site, docs.athenahq.ai).
* Cal.com scheduling widget (Contact Team).
* Stripe checkout (if purchasing API access and no card is on file).
## Common support questions
**Why can't I see the "Create API Key" button?**
You may not have the necessary write permissions for the API category. A "View-only" banner will appear at the bottom of the screen if you only have view access.
**Where is the Embed tab?**
The Embed tab is completely hidden (not just locked) if your organization's subscription plan does not include the embeddable dashboard feature, even if API access is unlocked.
**I forgot my API key or embed token secret. Can I see it again?**
No, for security reasons, generated API keys, embed tokens, and JWT secrets are shown exactly once at creation time. If you lose one, you must delete it and create a new one.
**Why does the API keys page show an upgrade screen?**
API and MCP access are paid features. If your organization is on the Free plan or lacks the API entitlement, the entire page is replaced by the upsell screen instead of your keys.
**How do I restrict an API key to specific websites?**
When creating or editing an API key, select "Specific websites" under the "Access scope" section, then check the boxes next to the websites you want the key to access. Note that external website members can only create keys scoped to websites where they hold API write permissions.
# Settings – Billing
Source: https://docs.athenahq.ai/guides/settings-billing
Lets a website member or organization admin view and manage their AthenaHQ subscription plan, credit balances/usage, invoices, and website/group billing allocations.
`app.athenahq.ai/settings/billing`
## Purpose
The Billing page is the central hub for managing your AthenaHQ subscriptions, credit balances, and payment history. It allows you to monitor exactly how and where your credits are being used, purchase additional capacity, and access your invoice records.
Because AthenaHQ supports both organization-wide subscriptions and granular, per-website access, this page adapts to your specific role. Organization administrators see a comprehensive view of all websites, group pools, and aggregated usage. External collaborators or website-specific members see a simplified view focused strictly on the single website they have access to.
## What's on the page
### Loading & Access States
* **Loading state:** A centered animated spinner appears while your membership details and billing records are retrieved.
* **View-only banner:** If you lack billing admin privileges, a floating "View-only · Billing" pill appears. Hovering over it explains that you need to ask an org admin for write access to make changes.
### Website Billing View (For Website-Only Members)
If you are an external collaborator invited only to a specific website, you see a focused, single-website view:
* **Subscription & Credits card:** Displays your current plan name, status badges (e.g., Trial, Past due), current billing cycle dates, and a progress bar showing remaining credits. Also includes an **Add credits** or **Manage credits** button.
* **Subscription management card:** Includes options to open the **Billing portal**, **Renew plan** (if canceled), **Cancel downgrade** (if a downgrade is scheduled), and **View plans** or **Plans & add-ons**.
* **Plan selection (if no active plan):** If the website has no subscription yet, this replaces the top cards, showing the full Free, Starter, and Enterprise plan comparison so you can pick a plan.
* **Invoices section:** Shows a month-filterable table of the current website's recent paid invoices.
### Organization Billing View (For Org Admins & Members)
If you are a member of the broader organization, you see an aggregated view:
* **Billing hero card:** A combined overview at the top of the page. The left side summarizes the organization's subscription (Plan name, status, **View plans**, **Billing portal**). The right side shows the shared organization credit pool (balance, progress bar, **Buy add-on** or **Add credits**, and sometimes **Lock credits**).
* **Tabs navigation:** Switches the lower half of the page between **Usage**, **Websites & groups**, and **Invoices**.
### Usage Tab
* **Credits used bar chart:** A day-by-day visual breakdown of organization-wide credit consumption over the selected time range.
* **By website table:** Breaks down total credits used in the selected range by specific website or group pool.
* **Credit log table:** An event-level log of individual actions that consumed credits, filterable by website.
### Websites & groups Tab
* **Search and Filters:** Lets you search by name/URL or toggle the view between **All**, **Websites**, and **Groups**.
* **Entities table:** Lists every organization website and billing-enabled group. Pinned at the top is your "Current website" and any groups it belongs to. Shows the entity's name, plan, and credit balance.
### Invoices Tab (Organization)
* **Monthly accordions:** Paid invoices are grouped by month. Clicking a month expands it to show the full list of invoices and a running total for that period.
### Tables
* **Recent invoices table (Website view):**
* **Date:** Invoice creation date.
* **Amount:** Total invoice amount in its currency.
* **Plan:** Product(s) billed on the invoice.
* **Status:** Payment status (e.g., Paid, Pending).
* **Invoice:** A link button to open the hosted Stripe invoice in a new tab.
* **Organization invoices table (Org view):**
* **Date:** Invoice creation date.
* **Amount:** Total invoice amount in its currency.
* **Status:** Payment status (e.g., Paid, Pending).
* **Invoice:** A link button to open the hosted Stripe invoice in a new tab.
* **Websites & groups table:**
* **Website or group:** The name and URL (for websites) or a "Group" badge (for groups), along with their logo or icon.
* **Plan:** The current subscription plan badge and any status warnings (like Trial, Past due, Expired, or Scheduled).
* **Credits:** Remaining versus total credits, visualized with a progress bar and next-reset date, or an "Unlimited" badge.
* **(Actions):** An unlabeled column containing a kebab menu (⋯) for websites, or a quick-link arrow for groups.
* **By website table (Usage tab):**
* **Website/Group name:** The name of the entity. Features a "Group pool" badge if it's a group, or "Deleted website or group" if the entity was removed.
* **Credits Used:** The total credits consumed by that entity during the selected range.
* **Credit log table (Usage tab):**
* **Time (UTC):** Timestamp of the credit event.
* **Website:** The originating website name, "Deleted website", or "Not recorded".
* **Action:** What consumed the credit (e.g., a specific workflow action).
* **Credits:** The number of credits charged for that specific event.
## Data shown
* **Subscription data:** Your current plan name, status, billing cycle dates, and price, synced directly from Stripe or your partner billing provider.
* **Credit balances and usage:** Real-time remaining balances and historical usage logs sourced from AthenaHQ's internal credit ledger.
* **Invoices:** Your official paid invoice history from Stripe.
* **Websites & Groups:** The list of all properties and billing groups you have access to within the organization.
## Common workflows
**Purchase additional credits**
1. Locate the credits progress bar and click **Add credits** (or **Manage credits**).
2. Select whether you want a **Monthly** recurring package or a **One-time** purchase.
3. Choose whether to apply the credits to **This website** or the **Whole organization**.
4. Use the `+` and `-` buttons to adjust the quantity of credit packages, reviewing the total cost preview.
5. Click **Buy \[N] credits** or **Add \[N] credits/month**.
6. Complete the Stripe checkout process in the new window (or wait for the success message if your account supports direct charging).
**Export organization credit usage**
1. Ensure you are on the Organization Billing view, and click the **Usage** tab.
2. Use the dropdown in the top right to select your desired date range (e.g., Last 30 days).
3. Click the **Export CSV** button next to the date range.
4. A CSV file will download containing the daily totals, per-website breakdown, and the full itemized event log.
**Delete a website**
1. In the Organization Billing view, click the **Websites & groups** tab.
2. Find the website you want to remove and click the three-dot (⋯) menu on the far right of its row.
3. Select **Delete website** (it will be red).
4. Confirm the deletion in the pop-up dialog.
## Empty, loading, and error states
* **Loading:** When you first visit, a centered spinner appears while membership details load. Skeletons (grey pulsing boxes) act as placeholders for the subscription summary, credit balances, invoices, and charts while their specific data is fetched.
* **Empty states:**
* If you have no plan: "This website is not currently on a plan."
* If you have no invoices: "No invoices yet. Invoices will appear here after your first payment."
* In the usage tab: "No credit usage found for this range." or "No credit events in this range."
* In the entities table: "No websites or groups match your search" or "No websites or groups found."
* **Errors:**
* If the credit dialog fails to load: "Billing details could not be loaded. Close the dialog and try again."
* If the usage log fails: "Failed to load the credit log. Refresh to try again."
* General data fetching failures will display in red text (e.g., "Failed to load credit usage data").
## Common support questions
**Why is the "Delete website" button greyed out?**
You cannot delete a website if it is the only website remaining in your organization. Additionally, if the website carries its own active or trialing subscription, you must cancel that subscription first before the system will allow you to delete it. A tooltip will appear explaining exactly why the button is locked.
**What does "Not recorded" mean in my credit log?**
Older credit events from before our system tracked granular, per-action attribution will show up as "Not recorded" under the Website or Action columns. These events still legitimately count toward your total usage.
**Why can't I see the 'Lock credits' button?**
The "Lock credits" feature is only available if your organization uses a shared credit pool. If your organization already distributes credits individually (or if you are managed by a partner), this option is hidden.
# Domain Access Settings
Source: https://docs.athenahq.ai/guides/settings-domains
Lets organization admins configure email-domain-based auto-join rules that grant new users automatic access to the whole organization or to a specific subset of websites. Lives on the Sign-in & access settings page.
`app.athenahq.ai/settings/security`
## Purpose
Organization admins can configure email-domain-based auto-join rules here. This lets new users who sign in with a verified matching email domain automatically join either the whole organization or a specific subset of websites, without needing individual invitations.
## What's on the page
The page is grouped into two main sections:
**Organization access**
Shows rules that grant new users access to the entire organization.
* **Domain row**: Shows the configured email domain (e.g., `@acme.com`).
* **Status badge**: Shows a green `Verified` badge if the domain is approved, or a clickable yellow `Verify DNS` badge if it still needs DNS setup.
* **Default role**: The role assigned to users who join via this domain (e.g., Viewer, Admin, or a custom role).
* **Edit icon (pencil)**: Opens a dialog to change the default role or remove the domain.
**Website access**
Shows rules that grant new users access only to specific websites.
* **Domain row**: The email domain.
* **Status badge**: `Verified` or `Verify DNS`.
* **Default role**: The role assigned to users on the granted websites.
* **Edit icon (pencil)**: Opens a dialog to change which websites the domain grants access to, change the default role, or remove the domain grant.
* **Website list**: Under each domain, lists the specific websites (with their logo and name) that users from this domain will automatically join.
**Dialogs**
* **Add Email Domain dialog**: Has an "Email Domain" input and a "Default Role" dropdown for org-wide access.
* **Add website access domain dialog**: Has an "Email domain" input, a "Websites" multi-select dropdown, and a "Default role" dropdown.
* **Verify domain ownership dialog**: Shows DNS TXT record details (`Type`, `Host / Name`, `Value`) and hints/links to the detected DNS provider.
* **Edit domain dialog (Organization)**: Lets you change the "Default role" or click "Remove domain".
* **Edit @domain dialog (Website)**: Lets you change the "Websites" multi-select, change the "Default role", or click "Remove domain".
## What you can do here
* **Add an organization access domain**: Click **Add Domain** in the "Organization access" section. Fill in the domain and select a default role. If the domain isn't automatically verified, you will be prompted to verify it via DNS.
* **Add a website access domain**: Click **Add Domain** in the "Website access" section. Enter the domain, select one or more websites, choose a default role, and save.
* **Verify a domain via DNS**: Click the **Verify DNS** badge on an unverified domain. Click on the `Type`, `Host / Name`, or `Value` fields to copy them to your clipboard. Add them to your DNS provider, then click **Verify** in the dialog.
* **Open DNS provider links**: Inside the verify dialog, you can click "Open dashboard" or "TXT record guide" to open your detected DNS provider in a new tab.
* **Edit an organization domain**: Click the pencil icon next to an org-tier domain. Change the default role and click **Save**.
* **Edit a website domain**: Click the pencil icon next to a website-tier domain group. Change the selected websites or default role and click **Save**.
* **Remove an organization domain**: Click the pencil icon next to an org-tier domain, then click **Remove domain**. This stops new joins, but existing members keep their access.
* **Remove a website domain**: Click the pencil icon next to a website-tier domain, then click **Remove domain**. This actively revokes the memberships this domain granted on the selected websites.
* **Cancel**: Click **Cancel** on any dialog to close it without saving changes.
## Data shown
* **Organization access domains**: The email domains configured to grant organization-wide access.
* **Website access domains**: The email domains configured to grant access to specific websites, along with the list of those websites.
* **Custom roles**: If your organization has custom roles configured, they appear in the default role dropdowns.
## Common workflows
1. **Add an organization-wide auto-join domain**
* Click "Add Domain" in the Organization access section.
* Enter the email domain (e.g. `example.com`).
* Select a default role from the dropdown.
* Click "Add Domain" to submit.
* If the domain doesn't match an existing verified member's email, the Verify domain ownership dialog opens automatically.
* Add the shown TXT record to the domain's DNS and click Verify.
2. **Grant a subset of websites to an email domain**
* Click "Add Domain" in the Website access section.
* Enter the email domain.
* Select one or more websites from the multi-select (searchable) list.
* Select a default role.
* Click "Add Domain" to submit.
* Verify via DNS if prompted.
3. **Edit an existing website-access domain's website list or role**
* Click the pencil/edit icon next to a domain group under Website access.
* Adjust the selected websites in the multi-select and/or change the Default role.
* Click "Save" to apply, or click "Remove domain" to delete the grant entirely.
4. **Verify a pending domain via DNS**
* Click the "Verify DNS" badge on an unverified domain (either section).
* Copy the Type, Host / Name, and Value TXT record fields shown.
* Add the TXT record in the domain's DNS provider (optionally follow the auto-detected provider's dashboard/docs links).
* Return to the dialog and click "Verify".
5. **Remove an org-tier auto-join domain**
* Click the pencil/edit icon on the domain row under Organization access.
* Click "Remove domain" in the Edit dialog.
* Confirm the domain disappears from the list (existing members keep their access; only future auto-joins stop).
## Empty, loading, and error states
* **Empty**: If no domains are configured for a section, it shows "No domains configured."
* **Loading**: A centered animated loader spinner is shown while the active organization is resolving. Skeletons show while the domain lists load. Action buttons show spinners while saving.
* **Error**: Toast error messages appear for action failures (e.g. "Failed to add domain", "Failed to update domain", "Failed to remove domain", "Failed to verify domain", or "An error occurred while...").
## Linked from / links to
* **Linked from**: Settings navigation sidebar (Settings > Domain access).
* **Links to**: The DNS verification dialog provides external links to your detected DNS provider's dashboard and TXT record guide.
## Common support questions
* **Why was my domain automatically verified without a DNS record?**
If an existing member in your organization already has a verified email address matching that domain, or if the organization already proved ownership of it elsewhere, Athena trusts the domain automatically.
* **Why can't I set a default role higher than Viewer?**
Only organization Admins can set a default role above Viewer. If you have a custom role that lets you manage settings but you aren't a full Admin, you can add domains but must leave the default role as Viewer. You will see a message saying "Only admins can set a default join role above Viewer."
* **What happens when I remove a domain?**
Removing an Organization access domain stops future users from automatically joining, but existing users keep their access. Removing a Website access domain completely revokes the access for users who joined those websites via the domain grant.
* **Why is the Save button disabled when editing a website domain?**
If you deselect all websites, you must explicitly click the red "Remove domain" button instead of saving an empty list.
# Settings → General (Organization Details)
Source: https://docs.athenahq.ai/guides/settings-general
Lets an organization member view core org details, manage SSO/SCIM provisioning settings, and (if owner) delete the organization, plus discover other org settings via quick links.
`app.athenahq.ai/settings/general`
## Purpose
The General Settings page acts as the primary hub for managing high-level organization details. It allows customers to view and edit their workspace's name, see when it was created, and verify their current organizational role.
For enterprise customers, this page houses the configurations for Single Sign-On (SSO) and SCIM (System for Cross-domain Identity Management) provisioning. Here, administrators can dictate the default role assigned to new SSO users and manage the API tokens required to sync user accounts from their identity provider.
Additionally, this page provides quick links to other administrative areas (like billing, domain access, and user management) and contains the "Danger Zone" where the organization owner can permanently delete the entire workspace.
## What you can do here
* **Edit**: Opens the "Edit organization" dialog to rename the workspace. Disabled if you lack permission.
* **Manage quick links**: Clicking "Users", "Domain access", "Billing", or "Activity Log" takes you to those specific settings pages.
* **Default role for new users selector**: Clicking the dropdown allows admins to pick a new default role (Standard or Custom) for incoming SSO users.
* **Generate SCIM token / Rotate SCIM token**: Opens a dialog to create a new SCIM API token. You can type an optional name into the "Token label (optional)" field and click "Generate token" or "Rotate token".
* **Click to copy**: After generating a token, clicking the code block copies the token to your clipboard.
* **Done**: Closes the SCIM dialog after you have copied your token.
* **How to set up SCIM in your identity provider**: Expands or collapses the step-by-step setup guide.
* **Danger Zone**: Clicking the Danger Zone row expands the panel to reveal the "Delete" button.
* **Delete**: Opens the "Delete Organization" confirmation dialog. You must manually type the organization name into the "Type \[Name] to confirm" field, then click "Delete Organization".
## Data shown
The organization name, creation date, and your role badge pull from the active workspace profile. The SCIM and SSO configurations are pulled directly from your organization's configured identity provider settings. The dropdown for SSO roles dynamically populates with standard system roles and any custom roles your organization has created.
## Common workflows
**1. Renaming the organization**
1. Click **Edit** in the top right of the Organization Details card.
2. In the dialog, type the new name into the "Organization Name" field.
3. Click **Save**.
4. A success message appears and the new name updates immediately.
**2. Setting up SCIM provisioning**
1. Locate the SCIM provisioning card (only visible if SSO is configured).
2. Click **Generate SCIM token**.
3. Enter an optional label (e.g., "Okta production") and click **Generate token**.
4. Click the displayed token to copy it to your clipboard. Click **Done**.
5. Click **How to set up SCIM in your identity provider** to expand the panel and follow the instructions to complete the setup in your system.
**3. Rotating an existing SCIM token**
1. In the SCIM provisioning card, click **Rotate SCIM token**.
2. Note the warning that the old token will be immediately revoked.
3. Click **Rotate token**.
4. Copy your new token and update it in your identity provider.
**4. Deleting the organization**
1. Scroll to the bottom and click the **Danger Zone** header to expand it.
2. Click **Delete** next to "Delete Organization".
3. Type the exact organization name into the confirmation box.
4. Click the red **Delete Organization** button.
5. You will be redirected to the home page.
## Empty, loading, and error states
* **Loading**: An animated spinner appears in the center of the page while the workspace data is initially fetching.
* **Empty**: If no active organization can be resolved, the page renders blank. If SCIM is not set up, the token status badge will read "Not configured".
* **Errors**: Attempting to save a name, rotate a token, or delete the org will surface a red error toast (e.g., "Failed to update organization name") if the action fails. The SCIM token status may briefly display "Loading…" if the connection is slow.
## Linked from / links to
* **Linked from**: The Settings sidebar navigation (the "General" tab).
* **Links to**: The quick links navigate to `/settings/users`, `/settings/domains`, `/settings/billing`, and `/settings/activity`. A successful organization deletion links back to the root application home page.
## Common support questions
**Why can't I edit the organization name?**
The "Edit" button requires specific organization management permissions. If the button is greyed out, you can hover over it to see what you are missing. You will need to ask an administrator to grant you access.
**Why is the SSO default role dropdown disabled for me?**
Only organization administrators and owners can change the SSO default role. Because this setting automatically grants access to every new person who joins via SSO, it is strictly protected. Hovering over the disabled dropdown will display the tooltip: "Only org admins can change the SSO default role, since it grants that role to every new SSO member."
**Why don't I see the SSO or SCIM sections at all?**
These sections are entirely hidden unless your organization has an active Single Sign-On (SSO) integration set up. If you are interested in SSO, please contact support or your account manager.
**I lost my SCIM token, can I see it again?**
No. For security reasons, SCIM tokens are only displayed once immediately after they are generated. If you lose the token, you must click "Rotate SCIM token" to generate a new one (which will instantly revoke the old token).
**Why is the Danger Zone Delete button disabled?**
Only the absolute owner of the organization can permanently delete the workspace. Hovering over the button will display the tooltip: "Only the organization owner can delete the organization." Regular administrators cannot perform this action.
# Integrations
Source: https://docs.athenahq.ai/guides/settings-integrations
Connect, configure, and disconnect third-party integrations (analytics, CMS/publishing platforms, and reporting/collaboration tools) for the active website.
`app.athenahq.ai/settings/integrations`
## Purpose
The Integrations page allows customers to connect, configure, and manage third-party tools that work alongside Athena. By connecting these platforms, customers can pull in traffic and keyword data to measure their search impact, automatically publish AI-generated content directly to their CMS, and route automated reports or answers to their team's communication tools.
This page acts as the central hub for all external connections tied to the customer's currently active website, with the exception of the Slack bot, which is configured organization-wide.
## What's on the page
Depending on the user's plan and permissions, they may see a few different banners at the top of the page:
* **View-only banner**: A floating pill at the bottom of the screen indicating that the user lacks write access for integrations. They can view connection statuses but cannot make changes.
* **Shopify app-install banner**: If the user is returning from installing Athena in the Shopify App Store, a banner asks them to "Finish connecting Shopify" with a button to confirm the website.
The main page is divided into three collapsible sections. If an integration is connected, it sorts to the beginning of its respective section.
**Measure & attribute**
Tools for tracking website traffic, search impressions, and keyword performance.
* **Google Analytics 4**: Attributes AI Search traffic, revenue, and conversions.
* **Google Search Console**: Monitors branded search impressions and clicks.
* **Google Ads**: Imports keyword data for smarter prompt generation.
**Reporting & collaboration**
Tools for delivering data and insights to the customer's team.
* **Looker Studio**: Instructions for connecting Athena data to custom dashboards.
* **Slack reports**: Configures weekly report delivery to Slack channels or DMs.
* **Slack bot**: An organization-wide tool (Enterprise plans only) that answers customer product questions directly in Slack channels.
**Integration Drawers (Drilldowns)**
Clicking any tile opens a side drawer tailored to that platform:
* **Disconnected state**: Shows requirements, a connect form (API keys, space IDs, site URLs), or a button to open an OAuth popup (Google, Slack, WordPress.com).
* **Connected state**: Displays the active account/property, related metadata (like synced CMS categories, content types, or collections), and actions to change settings or disconnect.
* **Looker Studio**: This tile is unique, it does not connect directly via a button. Instead, it opens a static instructions drawer explaining how to configure Looker Studio using Athena's data connector.
## What you can do here
* **Connect via OAuth**: For Google tools, Slack, and WordPress.com, clicking the connect button opens a secure authorization popup. Once authorized, the user selects their specific property or account from a dropdown to finalize the link.
* **Connect via API Credentials**: For tools like Webflow, Wix, Sanity, Contentful, Framer, and Payload, the user enters their credentials (API keys, space/project IDs, site URLs) into the drawer's form. The drawer often includes a "Step-by-step instructions" section explaining exactly where to find these in the third-party tool.
* **Switch Properties or Accounts**: If a user is connected to Google Analytics, Search Console, or Google Ads, they can use the dropdown in the drawer to switch the active property/customer account without having to re-authenticate.
* **Sync CMS Data**: Inside connected CMS drawers, users can click the refresh icon (tooltip: "Sync collections", "Sync content types", etc.) to manually pull in their latest CMS categories, document types, or collections. This ensures Athena knows where it can publish content.
* **Update Credentials**: CMS integrations allow users to click "Update credentials" to securely rotate their API tokens or change their target server URL without severing existing published content links.
* **Manage Slack Bot Channels**: Inside the Slack bot drawer, users can use a multi-select picker to add tracked channels (which auto-joins public channels), or manually add private shared channels by pasting a channel ID. Once added, users can toggle individual channels as "Enabled" or "Disabled", or click "Remove" to stop tracking them.
* **Disconnect an Integration**: Every active drawer has a "Disconnect" button. Clicking it asks for confirmation (e.g., "Confirm disconnect"). This is a destructive action that removes the credentials and clears any linked content schedules.
## Data shown
The page displays connection statuses derived directly from Athena's database of securely stored credentials. When a drawer is opened, Athena makes live, real-time requests to the respective third-party API (e.g., Google, Shopify, Webflow) to fetch available properties, verify token validity, and display synced CMS structures like blog categories or available fields.
## Common workflows
**Connecting Google Analytics 4**
1. Click the **Google Analytics 4** tile under "Measure & attribute".
2. Click **Connect Google Analytics** inside the drawer.
3. A Google popup appears. The user signs in and grants permissions.
4. Once the popup closes, the drawer displays a list of available GA4 properties.
5. Select the correct property from the dropdown. The tile now reads "Connected".
**Connecting a CMS (e.g., WordPress)**
1. Click the **WordPress** tile under "Create & publish".
2. Enter the website's URL and click **Detect connection method**.
3. Athena checks if the site uses Jetpack/WordPress.com (which requires OAuth) or standard self-hosted WordPress (which requires an Application Password).
4. Follow the resulting prompt: either click **Connect with OAuth** or enter a Username and Application Password, then click **Connect**.
5. The drawer updates to show the site's details and synced blog categories.
**Managing Slack Bot channels**
1. Click the **Slack bot** tile (requires organization member access).
2. If unconnected, click **Connect Slack** and authorize the workspace.
3. Under "Add channels", search and select the desired channels, then click **Add channel(s)**.
4. The channels appear in the "Tracked channels" list below, where they can be toggled on/off or removed.
## Empty, loading, and error states
* **Empty (No Website)**: If the user hasn't selected a website in their workspace switcher, the page displays a simple box: "Select a website to manage integrations."
* **Loading**: While checking permissions and connection statuses, the page displays a skeleton outline of the 3-section grid with grey placeholder tiles.
* **Page-level Error**: If the entire integrations system fails to load, a box appears reading, "Something went wrong. The Integrations page failed to load..." with "Try again" and "Reload" buttons.
* **Panel/Tile Error**: If a specific drawer fails to load, it displays, "We couldn't load this integration panel. Refresh the page or try again." If a tile fails its background status check, it shows a red "Couldn't load status" message directly on the card.
## Linked from / links to
* **Linked from**: The Settings sidebar nav (Integrations tab), deep links that automatically open specific drawers (e.g., `?provider=ga4`), or redirects from the Shopify App Store.
* **Links to**: External OAuth authorization popups (Google, Slack, WordPress), third-party dashboards (e.g., "Open in Webflow", "Open Google Analytics"), and the Athena subscription upgrade dialog (if the user is on a free plan).
## Common support questions
**Why does the page tell me to upgrade my plan?**
Integrations are a paid feature. If an organization is on the Free plan, attempting to access this page will show a lock screen indicating that Integrations require a paid plan, along with a "View plans" button.
**Why is the Slack Bot tile disabled for me?**
The Slack Bot is an organization-wide integration, whereas most other integrations are website-specific. If a user is an external member who was only invited to a specific website (not the parent organization), they will see a message stating, "Only organization members can manage org-wide integrations."
**Why did my WordPress connection say "Popup blocked" or "Timed out"?**
When trying to use WordPress OAuth, the browser might block the authorization window, or the customer's server might be blocking external connections to their `xmlrpc.php` file. If OAuth continually times out, they can click "Use an application password instead" to try the manual credential method.
**I see a "View-only" banner at the bottom. How do I connect tools?**
The user lacks the "Integrations: Write" permission for that website. They can click tiles to see what is currently connected, but all buttons to add, modify, or disconnect tools will be disabled. They must ask an organization administrator to update their role.
# Settings – Profile
Source: https://docs.athenahq.ai/guides/settings-profile
Lets a signed-in user manage their personal name/avatar, view their role, choose a sidebar preset, and delete their account.
`app.athenahq.ai/settings/profile`
## Purpose
The Profile settings page is where a user manages their personal identity within the Athena product. It allows them to set their name and profile picture, view their current role and email address, and tailor their navigation experience by choosing a sidebar layout preset.
For users who wish to permanently leave the platform, this page also houses the account deletion controls.
## What's on the page
**Personal information**
This section handles the user's basic identity.
* **Profile picture**: A clickable circular avatar area showing the user's current photo, their initials, or an "Add photo" prompt. Clicking this opens the **Profile picture** dialog.
* **First name** & **Last name**: Text fields for the user's name.
* **Email**: A read-only field displaying the email address the user signs in with.
* **Role**: A read-only field displaying the user's permission level for the current active website (e.g., "Viewer" or "Admin"). Explanatory text below notes that only organization admins can change roles in the People section.
**Sidebar**
* **Sidebar preset**: A dropdown menu that allows the user to change their default left-hand navigation layout. Options include General, Content Marketer, SEO, Executive, PR, and Custom. Text below explains that presets update the default layout, but items can still be customized directly from the sidebar.
**Danger Zone**
A collapsed-by-default section for destructive actions.
* **Delete account**: When the section is expanded, a card appears with a button to permanently delete the user's account and all associated personal data.
**Profile picture dialog**
Opened by clicking the avatar circle. It contains a 3D-flipping card with two tabs:
* **Regular**: Shows the user's standard uploaded photo. Includes options to "Upload photo" or, if they are signed in via Google, "Import from Google". Also includes a small "X" icon to delete the photo.
* **Greek**: Shows an AI-generated portrait of the user styled as a marble Greek statue. Includes a button to "Create Greek avatar" (or regenerate it) and an "X" icon to delete it.
**Delete your account dialog**
Opened by clicking "Delete account". Contains a warning message, a text input that requires the user to type "DELETE", and a destructive "Delete account" button that remains disabled until the confirmation text is typed.
## What you can do here
* **Change name**: Type in the First name or Last name fields. Changes are saved automatically when the user clicks or tabs out of the field (on blur).
* **Upload or change profile picture**: Click the avatar circle to open the Profile picture dialog, then use the "Upload photo" or "Import from Google" buttons.
* **Remove profile picture**: In the Profile picture dialog, hover over the current photo and click the "X" icon in the top right.
* **Generate Greek avatar**: In the Profile picture dialog, switch to the Greek tab and click "Create Greek avatar" or the rotate icon to generate a marble statue version of the profile picture.
* **Change sidebar preset**: Open the Sidebar preset dropdown and select a new role-based layout. The navigation sidebar will instantly update to reflect the new layout priorities.
* **Delete account**: Click the Danger Zone toggle to expand it, click the red "Delete account" button, type "DELETE" in the prompt, and click the final "Delete account" button. This permanently deletes the user's account and signs them out.
## Data shown
* The First name, Last name, and Email fields pull from the user's global account profile.
* The Role field reflects the user's effective permission level for the organization or website they are currently viewing.
* The Sidebar preset dropdown reflects the last saved navigation layout choice.
* The Profile picture area displays images saved to the user's account storage.
## Common workflows
**1. Updating your profile picture**
1. Click the circular avatar placeholder (or your current photo) under "Personal information".
2. The "Profile picture" dialog opens.
3. Click "Upload photo" to choose a file from your computer, or "Import from Google" if you signed in with a Google account.
4. Once the upload finishes, the app saves the photo and automatically flips to the "Greek" tab to generate an AI marble variant. You can close the dialog if you just wanted the standard photo.
**2. Changing your sidebar layout**
1. Scroll down to the "Sidebar" section.
2. Click the "Sidebar preset" dropdown menu.
3. Select a preset that matches your role (e.g., "SEO" or "Content Marketer").
4. A success toast appears, and the left-hand navigation sidebar immediately updates its visible items and order to match your choice.
**3. Deleting your account**
1. Scroll to the bottom of the page and click "Danger Zone" to expand it.
2. Click the red "Delete account" button.
3. A confirmation dialog appears. Type `DELETE` into the text box.
4. Click the red "Delete account" button in the dialog to finalize the deletion. You will be signed out and redirected to the login screen.
## Empty, loading, and error states
* **Empty avatar**: If a user hasn't uploaded a photo, the avatar circle displays their initials on a gray background, and an animated arrow points to it reading "Add your photo".
* **Loading**: If the page's data takes longer than 5 seconds to load, a telemetry event is fired for monitoring, but no disruptive full-page spinners block the view. During avatar generation or upload, a small spinner replaces the image area.
* **Errors**: If saving a name change or updating a sidebar preset fails, a red error toast appears at the top of the screen (e.g., "Failed to update profile" or "Failed to update preferences"). Avatar upload limits (like file size or type) trigger immediate error toasts.
## Linked from / links to
* **Linked from**: The main Settings navigation menu (under "Profile"). The legacy `/account` route also redirects here.
* **Links to**: The "Delete account" flow redirects the user to the `/login` screen after successful deletion.
## Common support questions
**How do I change my email address?**
The email field on this page is read-only. Email addresses are tied to your authentication method and cannot currently be changed directly from this settings page.
**Why is my Role field grayed out?**
The Role field displays your current permission level, but you cannot change your own role. Roles can only be changed by organization administrators in the Settings > Users (People) section.
**I just uploaded a photo, why did it switch to a Greek statue?**
As a fun feature, successfully uploading a standard profile picture automatically triggers the generation of an AI "Greek" variant. If you prefer not to use it, you can simply close the dialog, or click the "X" on the Greek tab to remove it; your standard photo is already saved.
**What does changing the Sidebar preset do?**
It updates the default order and visibility of the items in your left-hand navigation menu to prioritize the tools most useful for that specific job function. You can still manually pin, hide, or reorder individual items in the sidebar itself after picking a preset.
# Settings → Users (Team & Access)
Source: https://docs.athenahq.ai/guides/settings-users
Manage everyone who has access to the organization, its websites, and groups: invite, view, change roles, move between org/website scope, and revoke access.
`app.athenahq.ai/settings/users`
## Purpose
The Users page is your central hub for managing team access across your organization. It allows you to view all active members and pending invitations, control exactly what each person can see or do, and organize access by specific websites or groups.
From here, you can invite new coworkers, manage custom permission levels (roles), restrict a user to specific websites, or promote them to an organization-wide administrator.
## What's on the page
### Filters & Search
At the top of the roster, you can search for members or invites by name, email, or website URL. You can also narrow the list using several dropdown filters:
* **Type:** Filters members by their scope: Organization, Website, or Group (if your organization uses groups).
* **Role:** Filters by assigned role, including default system roles and your organization's custom roles.
* **Status:** Filters rows by Active, Pending, Delivered, Bounced, or Expired.
* **Website:** Filters to members or invites granted access to a specific website.
* **Group:** Filters to members or invites granted access to a specific group.
### People table
This unified roster displays active members alongside pending invitations. It is grouped into sections (e.g., organization members, website members, group members).
* **Member:** The user's avatar (or initial), full name, and email address.
* **Role:** The permission level assigned to the user or invitee. For active members, this is a dropdown menu you can use to change their role instantly. If the user is the organization owner, it displays an "Owner" badge. Hovering over the Owner badge shows the tooltip: "Owner role cannot be changed directly".
* **Access:** The scope of what the user can see. This displays "All websites" for organization-wide members, a specific website (or stack of website logos) for website-only members, or "Group: \[Name]" for group members.
* **Joined:** For active members, this shows the date they were added. For invitations, it shows a status badge (Pending, Delivered, Bounced, or Expired).
* **⋯ (Overflow menu):** A button revealing additional management actions for that specific user or invitation.
### Member details side panel
Clicking "View details" on a member opens a slide-over panel summarizing their profile. It displays:
* **Name and Email:** The user's display name and email address. You can click the pencil icon next to their name to edit it.
* **Role:** The user's current role, with a dropdown to assign a new one.
* **Member since:** The exact date the user joined.
* **Access:** A summary of the websites they can view.
* **User ID:** The member's unique internal identifier (can be clicked to copy to your clipboard).
* **Market landscapes & Groups:** Lists any specific market landscapes or groups the user belongs to.
* **Recent activity:** For administrators, this lists the recent audit log actions performed by the user.
### Roles dialog
Clicking the "Roles" button at the top of the page opens a dialog where you define what members can see and do across each area of AthenaHQ. It is split into **System roles** (built-in, view-only defaults like Admin and Viewer) and **Custom roles** (tailored permission sets you can create, edit, and delete on certain subscription plans).
## What you can do here
### Invite users
Clicking the primary invite button opens a dialog to send new invitations. You can:
* **Choose the scope:** Select whether to invite the user to your "Organization", a specific "Website", or a "Group".
* **Assign an email and role:** Type their email and pick a role from the dropdown.
* **Import CSV:** Click "Import CSV" to bulk-add invitees. Your CSV must have an 'Email' column and can optionally include a 'Role' column matching one of your active role names.
* **Add another:** Click "Add another" to add a blank row and invite multiple people at once.
### Manage roles
Inside the "Roles" dialog:
* **Create a custom role:** Click "Create role" (or "+ Create new role") to define a tailored mix of access. Note: Custom roles require an Enterprise or Agency plan.
* **Copy permissions:** When creating or editing a custom role, use the "Copy from:" dropdown to duplicate the permission grid of an existing role.
* **View or Edit permissions:** Click "View" on a system role or "Edit" on a custom role to see the per-category permission grid (e.g., Prompts, Analytics, Billing).
* **Delete a custom role:** Click "Delete" to permanently remove a custom role. You will be asked to confirm: "Delete "\"? Members and invites must not be using this role. This can't be undone."
### Manage individual members
Clicking the **⋯** menu on a member's row lets you:
* **View details:** Opens the "Member details" side panel.
* **Promote to owner:** Opens a confirmation dialog to transfer full ownership to that user (the current owner will become an admin). The confirmation reads: "Are you sure you want to transfer ownership to \? You will lose owner privileges and become an admin. This action cannot be undone."
* **Restrict to specific websites:** Opens the "Move to website member" dialog, allowing you to demote an organization member down to specific website access.
* **Grant access to all websites:** Opens the "Move to organization member" dialog, elevating a website-only member to full organization access.
* **Remove / Leave organization / Leave website:** Removes the user from their current scope. If clicking your own name, this appears as "Leave". The confirmation reads: "Are you sure you want to remove \ from the organization? This action cannot be undone."
* **Remove from group / Leave group:** Revokes access to a specific group.
### Manage pending invitations
Clicking the **⋯** menu on a pending invite row lets you:
* **Revoke invite:** Immediately cancels the pending invitation so it can no longer be accepted.
### Manage users in bulk
Hover over a user's avatar on the far left of the table to reveal a checkbox. Check the box to enter multi-select mode. Once multiple rows are selected, a floating bar appears at the bottom of the screen allowing you to:
* **Change role:** Assign a new role to every selected member at once.
* **Remove:** Bulk-remove the selected members and/or revoke the selected invitations simultaneously.
## Data shown
This page displays all active team members and pending email invitations across your entire organization, including those restricted to specific websites or groups. It also displays all built-in and custom roles configured for your team. The "Recent activity" section in the member details panel pulls directly from your organization's audit logs.
## Common workflows
### Inviting new team members
1. Click the primary invite button at the top right of the page.
2. Choose the access scope: Organization, Website, or Group.
3. (If Website or Group is selected) use the dropdown to select the specific websites or groups they should access.
4. Enter the user's email address and select their role.
5. Click "Add another" to queue up more users, or click "Import CSV" to upload a spreadsheet of emails.
6. Click the primary button at the bottom of the dialog to send the invitations.
### Creating a custom permission role
1. Click the "Roles" button at the top of the page.
2. Under the "Custom roles" section, click "Create role".
3. Type a descriptive name for the role (e.g., "Content Writer").
4. In the Permissions grid, select either "View", "Write", or "No access" for each feature category (Content, Prompts, Analytics, etc.). To save time, you can use the "Copy from:" dropdown to start with an existing role's permissions.
5. Click "Create role" to save it. It will now be available in the role dropdown for any member or invite.
### Restricting an organization member to specific websites
1. Find the organization-wide member in the roster and click the **⋯** menu on their row.
2. Click "Restrict to specific websites".
3. In the confirmation dialog, select the specific websites they should retain access to.
4. Select the role they should have on those websites.
5. Click "Move to website".
## Empty, loading, and error states
* **Loading:** While team data is loading, the roster displays placeholder gray bars (skeletons) for avatars, names, and roles, fading out toward the bottom of the list to indicate more data is loading.
* **Empty:** If you apply filters or searches that match no users, the table will simply display no rows.
* **Errors:** If an action fails (e.g., trying to remove the last admin, or a network failure when saving a role), a red error toast will appear at the bottom of the screen with a specific explanation like "Cannot remove the last admin" or "Failed to assign role."
## Linked from / links to
* **Linked from:** This page is accessed primarily via the "Users" link in the Settings navigation sidebar. It can also be reached via deep links that pre-filter the table to specific groups or websites.
* **Links to:** The "Add Domain" dialog (used to set up automatic joining for corporate emails) connects to the Domain access settings underlying logic. Market landscape details shown in the member details panel link mentally to the Market Landscape features.
# Shopping Insights
Source: https://docs.athenahq.ai/guides/shopping
Show how the tracked website's products appear in AI shopping/product-carousel results, benchmarked against competitors.
`app.athenahq.ai/shopping`
## Purpose
The Shopping Insights page helps customers understand how their products and their competitors' products surface in AI shopping answers (such as product carousels in ChatGPT or AI Mode). It allows marketers to track their brand's visibility, monitor ranking positions, and compare pricing data against the rest of the market.
By analyzing where products appear and how they rank, customers can identify which retailers are performing best in AI answers and spot competitors who might be dominating high-intent product searches. This page acts as a dedicated dashboard for bottom-of-the-funnel e-commerce performance.
## What's on the page
* **Page header**: Displays the "Shopping Insights" title and a brief tooltip explaining the page.
* **Filter bar**: A row of dropdowns to filter the data by "Views", "Models", "Date Range", "Competitors", "Prompt Tags", and "Brand Identifiers". Also includes an "Add filter" button.
* **AI shopping visibility (Hero)**: A large stat showing the percentage of AI shopping answers that feature the customer's products, along with a sparkline trend chart. Includes a head-to-head "You vs the field" comparison showing your "Avg position" and "Avg price" against competitors.
* **Stat tiles**: Four quick metrics summing up the selected date range:
* **Shopping answers**: Total AI answers containing shopping results.
* **Your appearances**: How many times your products appeared.
* **Competitor appearances**: How many times competitor products appeared.
* **Tracked offers**: Total individual product offers found, along with the overall average price.
* **On the shelf**: A horizontally scrolling carousel of product cards showing the top products ranked by how often they appear. Users can toggle between "Yours" and "Competitors". Each card shows the product image, appearance count ("X× seen"), rating, product name, retailer name, and average position.
* **Rank distribution**: A horizontal bar chart showing who occupies each position (#1 through #10) in shopping results. Includes the tooltip: "Bar length reflects how many products land at each rank; the indigo/orange split is yours vs competitors."
* **Appearances over time**: A line chart showing daily product appearances over the selected date range, comparing "Your products" (indigo) and "Competitors" (orange).
* **Competitor leaderboard**: A table ranking competitor brands by how many products they place in shopping results.
* **#**: The competitor's rank on the leaderboard (1-8).
* **Competitor**: The brand name of the competitor.
* **Products**: The number of competitor products appearing, with a proportional bar. Tooltip: "Competitors ranked by how many products they place in shopping results."
* **Avg pos**: The average shopping result position for that competitor's products.
* **Answers**: The number of shopping answers featuring that competitor.
* **Top retailers**: A table showing where products are stocked in AI answers. Tooltip: "Retailers ranked by how often they carry a listed product, counted from each product's seller offers. Toggle between retailers carrying your products and those carrying competitors'."
* **Retailer**: The merchant or store name.
* **Listings**: A bar showing the breakdown of your products vs. competitor products at this retailer. Hovering reveals the exact count for each.
* **Avg pos**: The average position of products listed by this retailer for the active toggle (Yours or Competitors).
* **Answers**: The number of shopping answers featuring products from this retailer.
## What you can do here
* **View shopping answers**: Click the "View shopping answers" link in the hero or the "Shopping answers" stat tile to navigate to the Responses page, automatically filtered to show only answers containing shopping products.
* **Toggle product ownership**: Use the "Yours" and "Competitors" buttons on the "On the shelf" and "Top retailers" sections to flip the view between your brand's data and the competition.
* **Visit product links**: Click any product card in the "On the shelf" section to open that product's external web page in a new tab.
* **Manage prompts**: If no shopping data has been collected yet, click "Manage prompts" to go to the Prompts page and add more product-focused or buying-intent queries.
* **Upgrade plan**: If on a Free plan, click "View plans" in the locked gate to open the pricing dialog and upgrade.
* **Save and manage views**: Using the "Views" dropdown in the filter bar, customers can click "Save as view" to store their current filters. Inside the dropdown's `...` (kebab) menu on a saved view, they can click "Edit" (to rename/change icon), "Update filters" (to overwrite the view with the current on-screen filters), "Set as default", "Remove default", "Export as CSV", or "Delete" (requires confirmation).
* **Clear filters**: Click "Clear All" in the filter bar to reset all non-default filters.
## Data shown
The data is generated from AI shopping responses (like ChatGPT product carousels) collected for the customer's tracked prompts. It pulls from the underlying product listings and seller offers to determine prices, merchant names, product ratings, and rankings. The data is separated into "yours" and "competitors" based on the customer's tracked domains and configured brand identifiers.
## Common workflows
1. **Analyze brand visibility in shopping results**
* Navigate to the Shopping Insights page.
* Check the "AI shopping visibility" percentage to see your overall share of voice.
* Review the "You vs the field" section to see if your average price and position are competitive.
2. **Identify top-performing competitors**
* Look at the "Competitor leaderboard" table to see which brands are placing the most products.
* Toggle the "On the shelf" section to "Competitors" to inspect exactly which rival products are surfacing most often.
3. **Discover key retailers**
* Scroll down to the "Top retailers" table.
* Toggle between "Yours" and "Competitors" to see which merchants (like Amazon or specialized stores) are stocking the products that AI engines prefer to recommend.
4. **Drill down into individual answers**
* Click "View shopping answers" near the top.
* Review the actual AI responses to understand the full context of how these product carousels are presented to users.
## Empty, loading, and error states
* **Empty (No data collected yet)**: If the website has never received any shopping responses, a "No shopping data yet" card appears with a mock AI response illustration and a "Manage prompts" button to encourage tracking more buying-intent queries.
* **Empty (No data for current filters)**: If the site has shopping data but none matches the current date range or filters, a "No AI shopping data yet" card appears with a shopping bag icon.
* **Loading**: While data is fetching, skeleton placeholders mimic the layout of the hero, stat tiles, shelf, and charts.
* **Error**: If the data fails to load, a "Couldn't load shopping data" card is shown with a red warning icon and a "Try again" button.
## Linked from / links to
* **Linked from**: The main sidebar navigation ("Shopping"). Can also be indirectly reached from the Prompts page after setting up tracked queries.
* **Links to**:
* The Responses page (via "View shopping answers" or the "Shopping answers" stat tile).
* External product pages (via clicking items on the product shelf).
* The Prompts page (via "Manage prompts" in the empty state).
* The billing/plans dialog (via "View plans" on the free plan lock).
## Common support questions
* **Why is my page empty even though I have prompts tracked?**
*Answer:* AI engines only return shopping carousels for certain high-intent product queries. If your tracked prompts don't trigger these specific shopping results, this page won't have data. Adding more specific product or buying-intent prompts may help.
* **What is the difference between the two empty states?**
*Answer:* "No shopping data yet" means your account has *never* seen a shopping response for any of your prompts. "No AI shopping data yet" means you have received them in the past, but there are zero matches for your currently selected dates or filters.
* **Why are some product images missing?**
*Answer:* The system attempts to scrape product images on demand if they aren't provided directly by the AI. Sometimes this scrape fails or is delayed, resulting in a "No image" placeholder.
* **Why does "Avg pos" or "Avg price" show a dash (-)?**
*Answer:* If the AI provided the product but did not include a specific ranking position or price in its response data, we cannot calculate an average, so a dash is displayed.
* **Why do the "Yours" / "Competitors" toggles change on their own?**
*Answer:* If you select "Yours" but you have zero products appearing in that specific view, the toggle will automatically flip to "Competitors" so you aren't staring at an empty section.
# Sources
Source: https://docs.athenahq.ai/guides/sources
Lets customers see which domains/URLs AI models cite for their brand, broken down by domain or page and filterable by model/prompt/social platform, with drill-down, tagging, and export tools.
`app.athenahq.ai/sources`
## Purpose
The Sources page allows customers to see exactly which websites, competitor blogs, or social media platforms AI models are citing when answering their tracked prompts. It acts as a backlink and citation analysis tool tailored specifically for Generative Engine Optimization (GEO).
By browsing this page, marketers can identify which domains hold the most influence over AI answers in their industry. This helps them uncover prime targets for PR outreach, affiliate partnerships, and content syndication, as well as monitor exactly what competitors and third-party reviewers are saying about their brand.
## What's on the page
**Page header**\
Displays the page title alongside a small info icon (`(i)`) that launches an interactive walkthrough of the page. On desktop, it includes two sets of tab switchers: **Domain** vs. **Page**, and **All** vs. **Social**.
**Social platform chip bar**\
Visible only when the **Social** tab is selected. This row of buttons lets customers filter the table down to a single social platform (like YouTube, Reddit, X, Facebook, LinkedIn, etc.). It includes a **More (N)** / **Less** toggle to show or hide platforms that currently have no data for the selected filters.
**Filter bar & Saved views**\
A comprehensive row of dropdowns to narrow the visible citation data. Customers can filter by AI models, specific prompts, date ranges, competitors, personas, locations, and source types. Customers can also save their current filter combinations using the saved views controls.
**Bulk action command bar**\
Appears floating at the bottom of the screen when one or more rows are selected (only available in the **Page** tab). It provides bulk actions to assign source types, trigger rescans, or clear the selection.
**Sources data table**\
The main spreadsheet-style view containing the citation data. It can group data by top-level domains or show specific page URLs.
Columns include:
* **Name / URL**: The domain (in Domain mode) or full page URL (in Page mode) that was cited by an AI model. Includes a favicon and badges indicating the source type.
* **Spark**: An inline sparkline chart showing the daily citation and mention trend over the selected date range. (Domain mode only).
* **Type**: Badges classifying the source as owned, competitor, partner, or third-party, along with any custom tags the customer has applied.
* **Citation %**: The percentage of AI responses within the current filters that cited this specific domain or URL. The tooltip reads "citation %".
* **Responses Influenced**: The raw number (and percentage) of tracked responses this source affected. The tooltip reads "responses influenced".
* **Estimated Impressions**: The estimated volume of impressions captured via this source's citations. The tooltip reads "impressions captured".
* **Mentions**: The number of times the customer's brand was actively mentioned in responses citing this URL. (Page mode only).
* **Competitors Mentioned**: Lists which specific competitors, if any, were mentioned alongside this cited source. (Page mode only).
* **Brand Mention %**: The percentage of citing responses that actively mentioned the customer's brand. (Domain mode only).
* **Competitor Mention %**: The percentage of citing responses that actively mentioned a competitor. (Domain mode only).
* **URLs**: The number of distinct URLs belonging to this domain that were cited by AI models. The tooltip reads "URLs". (Domain mode only).
* **First Seen**: The date this URL was first observed as a citation. The tooltip reads "first seen". (Hidden by default, Page mode only).
* **Rescan**: An icon button used to trigger a fresh scan of this specific URL's content. (Page mode only).
**Source Detail Drilldown**\
Clicking on a domain or URL name in the table opens a slide-in drawer on the right side of the screen. This drawer displays deeper analytics for the selected source, including breadcrumb navigation to move between the domain-level overview and specific URL-level details without leaving the page.
## What you can do here
* **Start tour**: Clicking the info icon in the header launches an interactive walkthrough highlighting the tabs, table, and filters.
* **Switch views**: Click **Domain** or **Page** to toggle how citations are grouped. Click **All** or **Social** to isolate social media networks.
* **Filter by social network**: In the Social tab, click a platform chip (e.g., YouTube, Reddit, X) to view only citations from that network. Click **More** to see networks with no current data.
* **Filter data**: Use the filter bar to isolate citations from specific AI models, date ranges, competitors, or prompts.
* **Sort and resize columns**: Click any column header with sort arrows to sort the table ascending or descending. Click and drag the invisible handle between column headers to resize them, or double-click to auto-fit the column to its widest content.
* **Open source in new tab**: Cmd/ctrl-click on a domain/URL name or the inline analytics icon to open the detailed source analytics page in a new browser tab.
* **Manage Columns**: Click the **Columns** button (the view options popover) to hide, show, or drag-and-drop reorder the table columns.
* **Export data**: Click the **Export** button in the table toolbar (or via a row's overflow menu) to open the Export dialog. Here, you can adjust the row count using the **+** / **-** stepper or quick-select buttons (1000, 5000, All), then click **Export** to download a CSV. *Note: If a customer is on a free plan, clicking Export will instead open an upgrade dialog.*
* **Select rows**: In Page mode, click the checkbox on any row to select it. Shift-click to select a large block of rows at once.
* **Bulk Assign Type**: With rows selected, click **Assign Type** in the bulk action bar to open a dialog where you can override the source classification (owned, competitor, third-party, partner) for all selected URLs.
* **Bulk Rescan**: With rows selected, click **Rescan** to queue a fresh content scrape for the chosen URLs.
* **Clear selection**: Click **Clear** in the bulk action bar to deselect all rows.
* **Single-row Rescan**: Click the rescan icon in the Rescan column to refresh that individual URL's content.
* **Edit single source type**: Click the three-dot kebab menu on a row to open the types menu and override the source's classification or manage custom tags.
* **Expand domain row**: Click the chevron on a domain row (Domain mode) to expand it and view the specific subdomains or URLs driving its metrics.
* **Navigate the detail drawer**: When the slide-in drawer is open, click the breadcrumbs (domain / path / query) at the top to navigate up or down the URL hierarchy. Press Esc or click outside to close the drawer.
## Data shown
The data displayed on this page is compiled by aggregating AI model responses to the customer's tracked prompts. It counts every time a domain or URL is cited as a source by an AI model. The sparklines and metrics update dynamically based on the active date range and applied filters. Overrides (like marking a third-party site as a "partner") are drawn from the customer's specific workspace settings.
## Common workflows
**Investigating top-citing domains for the brand**
1. Ensure the **Domain** tab and **All** tab are selected in the header.
2. Adjust the date range and select specific models or competitors in the filter bar.
3. Click the **Citation %** or **Responses Influenced** column header to sort the highest-impact domains to the top.
4. Click a domain name to slide open its detail drawer for deeper insights, or cmd/ctrl-click to open the full domain report in a new tab.
**Bulk-classifying and rescanning URLs**
1. Switch the header toggle to the **Page** tab to view individual URLs.
2. Use the search box or filters to locate a specific batch of URLs (e.g., untagged blog posts).
3. Click the checkbox on the first URL, then shift-click the checkbox on the last URL to select the entire range.
4. In the floating bulk action bar at the bottom, click **Assign Type** to categorize them, or **Rescan** to refresh their content.
5. Click **Clear** when finished.
**Reviewing social media citations**
1. Click the **Social** tab in the top right of the page header.
2. Click a specific platform chip (like **YouTube** or **Reddit**) to isolate citations from that network.
3. Review the filtered URLs in the table below to see which specific posts or videos AI models are linking to.
4. If a platform is missing, click **More** to view disabled chips for platforms that currently have no citations matching the active filters.
**Exporting a CSV of source data**
1. Set the desired table grouping (Domain or Page) and apply any necessary filters.
2. Click the **Export** button located in the table's top right toolbar.
3. In the dialog, use the stepper or the quick-select buttons to choose how many rows to include.
4. Click **Export** and wait for the download-progress toast notification to complete.
## Empty, loading, and error states
* **Loading**: An animated loader appears while the workspace, filters, or initial data are fetched. Skeleton placeholder rows are shown when scrolling down to fetch the next page of results.
* **Empty**: If no sources match the active filters, search query, or selected social platform, the table renders empty.
* **Error**: Toast notifications will appear in the bottom corner if a CSV export, bulk rescan, or bulk tag assignment fails. If the social availability check fails, the social platform chips will silently default to showing no data.
## Linked from / links to
**Linked from:**
* The **Sources** link in the left-hand main navigation sidebar.
* Product tour deep links (e.g., onboarding flows).
* Drill-down links from citation visualization charts (Sankey diagrams) on other analytics pages.
**Links to:**
* The in-page Source detail drawer (which slides in over the table).
* Dedicated Domain and Source Analytics pages (opened in a new tab via cmd/ctrl-click).
* CSV file downloads.
* The subscription upgrade dialog (if a free-plan customer attempts to export).
## Common support questions
**Why can't I see the "Competitors Mentioned" column?**
That column (along with "Mentions" and certain filters) is only available when the table is grouped by **Page**. If you are on the **Domain** tab, switch to the **Page** tab to see URL-specific mention data.
**Why is the Export button not downloading a file?**
Data exports are a premium feature. If you are on a free plan, clicking Export will safely intercept the action and open a dialog inviting you to view paid plans instead.
**Why are some social platforms grayed out?**
Social platforms are grayed out and hidden behind the **More** button if AI models haven't cited them for any of your tracked prompts within your currently selected date range and filters.
**Why is the Rescan button disabled?**
Rescanning requires specific workspace permissions. If you are a viewer or lack the required role, the rescan icons and bulk rescan actions will be visible but disabled. Rescans are also disabled if a scan is already actively pending for those URLs.
**I selected "X" but I want to see Twitter links too. Do I need to search twice?**
No. The system automatically treats `x.com` and `twitter.com` as the exact same platform. Selecting either chip will pull in citations for both domain variants.
# Source URL Analytics
Source: https://docs.athenahq.ai/guides/sources-analytics-source_url
Deep-dive inspector for a single cited URL (or YouTube video), showing its responses, URL parameter variants, and (for YouTube) creator/timestamp breakdowns
`app.athenahq.ai/sources/analytics`
## Purpose
This page provides a deep dive into a single specific URL (or YouTube video) that was cited by AI engines as a source. It allows you to see exactly which AI responses cited this page, track its citation rate over time, and understand how different URL variations (like tracking tags or anchors) affect its visibility.
For YouTube URLs, this page includes specialized analytics, breaking down citations by the YouTube channel/creator and analyzing the specific video timestamps (e.g., `?t=30`) that AI models link to.
## What's on the page
### Page header
The top navigation path displays the breadcrumb (e.g., `Sources / [domain] / [URL]`). The URL itself is a clickable link that opens the actual webpage in a new browser tab.
### Contextual filter row
A sticky bar of filters (such as Date Range, Models, Competitors, Sentiment, Prompt Tags) allowing you to narrow down the data shown for this specific URL. It also includes options to save your filter views.
### Citation Trend card
A collapsible card titled **Citation Rate Over Time**. It displays a line chart showing the percentage of AI responses that cited this URL over the selected timeframe. When collapsed, it shows a quick summary of the latest rate.
### Lens tabs
A set of tabs to switch between different analytical views of the URL data. Each tab has its own search box and export controls.
* **Responses**: Shows every individual AI response that cited this URL.
* **Parameters**: Breaks down the different URL variations (such as query strings or fragments) that were cited.
* **Creators**: (Only visible for YouTube URLs) Groups citations by the YouTube channel/creator.
* **Timestamps**: (Only visible for YouTube URLs) Shows how often the video was cited with specific timestamp parameters.
### Responses table
Lists individual AI responses that cite this specific URL.
* **Date**: When the response was generated.
* **Model**: Which AI model/engine produced the response (e.g., ChatGPT, Perplexity).
* **Mentioned**: Whether your tracked brand was mentioned in this response.
* **Competitors Mentioned**: Logos and names of competitor brands mentioned in the response.
* **Sources**: Whether the response included any displayable cited sources.
* **Cited**: Whether your tracked brand's own domain was cited as a source.
* **Attributed Citation**: Whether the citation was flagged as coming from Athena-influenced content.
* **Market Position**: Numeric rank of the brand's mention position in the response.
* **Sentiment**: Positive, Neutral, or Negative sentiment toward the brand in the response.
* **Prompt Type**: Whether the underlying prompt is Non-Branded (discovery) or Branded (high intent).
* **Prompt**: Text of the base prompt that generated the response.
* **Prompt Variation**: The specific fan-out variation text of the prompt used, if any.
* **Country**: Country associated with the response/prompt.
* **Location**: Location tag(s) associated with the response (only shown if your org has location-based offerings).
* **Response**: Full text of the AI response, with your search terms highlighted.
* **Personas**: Personas associated with the prompt.
* **Attributes**: Any custom attributes assigned to the response.
### Parameters table
Lists normalized query-parameter or fragment variants of this URL.
* **URL**: The full URL including its specific query string or fragment suffix.
* **Responses**: Number of responses citing this exact parameterized URL.
* **Share**: Percentage share of responses this parameter variant represents.
### Creators table (YouTube only)
Groups citations by YouTube channel.
* **Creator**: YouTube channel/creator name, linking out to their channel.
* **Total Citations**: Total citation count across all of this creator's videos. *(Tooltip: "Total number of citations across all videos from this creator")*
* **Avg Citation %**: Average citation percentage across the creator's videos. *(Tooltip: "Average citation percentage across all videos")*
* **Videos**: Number of distinct videos from this creator that were cited.
**Creator video sub-table (expanded row)**
Visible when you click the chevron next to a creator's name.
* **Video**: Video title (or URL path) with a link to view analytics for that specific video.
* **Citations**: Number of citations for this specific video.
* **Citation %**: Citation percentage for this specific video.
* **First Seen**: Date this video citation was first observed.
### Timestamped YouTube sources table (YouTube only)
Lists individual timestamped citation links for the video.
* **YouTube title**: Video title with a link to view analytics.
* **Prompt**: Prompt text that produced the citation.
* **Timestamp**: The `t=` timestamp parameter value on the cited link, or "—" if none.
* **Citations**: Number of citations for this row.
* **Citation %**: Citation percentage for this row.
## What you can do here
* **Navigate back**: Click the back arrow in the breadcrumb to return to the domain's Sources page.
* **Open external URL**: Click the URL in the breadcrumb, or any external link in the tables, to open it in a new browser tab.
* **Export to CSV**: Click the download icon in the toolbar (next to the search box) or inside the `⋯` menu to export the active table. For YouTube Creators and Timestamps, this opens a dialog to select how many rows to export.
* **Search**: Use the search box above the table to filter the active lens (e.g., search response text or parameter strings).
* **Customize columns**: Click the **Columns** button (or inside the `⋯` menu on mobile) to toggle the visibility of columns in the Responses table.
* **Sort data**: Click on sortable column headers (like Date, Model, or Citations) to reorder the table.
* **Load More**: Click the **Load More** button at the bottom of a table to fetch the next set of rows.
* **View response details**: Click any row in the Responses table to open a side drawer showing the full response text, prompt details, competitors, and sources.
* **Drill down into a parameter**: Click a row in the Parameters table to open a new Source URL Analytics page scoped exactly to that specific URL variation.
* **Drill down into a video**: Click a video row in the Creators lens or Timestamps lens to view analytics for that specific canonical YouTube URL.
* **Expand/collapse creators**: Click the chevron next to a creator's name to view their individual videos. Click the chevron in the column header to expand or collapse all creators at once.
* **Toggle trend chart**: Click the "Citation Rate Over Time" header to expand or collapse the line chart. This preference is saved for your user.
* **Reset filters**: Click **Clear All** in the filter bar to return to default views.
## Data shown
This page displays tracking data for a specific webpage or video cited by AI models. The data comes from the AI responses your account tracks, filtered to show only instances where this exact URL (or its variants) appeared as a source. For YouTube URLs, the system also gathers public video metadata (like titles and channel names) to enrich the tables.
## Common workflows
**Investigating parameter variations**
1. Select the **Parameters** tab.
2. Review the list to see if AI models are appending tracking parameters (like `?utm_source`) or section links (like `#pricing`) when citing your page.
3. Click a specific parameter row to drill down. You will be taken to a view showing only the AI responses that cited that exact URL variation.
**Exporting YouTube timestamp data**
1. For a cited YouTube video, click the **Timestamps** tab.
2. Review the charts to see which AI models link to specific moments in the video.
3. Click the download icon to open the export dialog.
4. Select the number of rows you want to download and click **Export** to generate a CSV file.
## Empty, loading, and error states
* **Empty**: If no data matches your filters, you will see messages like "No citation data available" (for the trend chart), "No URL query parameters for this source", "No responses found", "No YouTube videos found for this source", or "No timestamped YouTube sources found".
* **Loading**: An animated loader appears while data is fetching. Filter rows may show placeholder skeleton blocks while loading dynamic options.
* **Error**: If the trend chart fails to load, it will display "Couldn't load citation data." along with a **Retry** button. Other table fetch failures will silently result in an empty state.
## Linked from / links to
* **Linked from**: The domain-level Sources page (by clicking a URL row), YouTube Creator Breakdown video rows, or YouTube Timestamps table rows.
* **Links to**: The parent Sources domain page (via the back arrow), external browser tabs for the cited URLs, and to other Source URL Analytics pages when drilling into parameter variations or specific videos.
## Common support questions
**Why can't I see the Parameters tab anymore?**\
If you clicked on a specific parameter row to drill down, you are now viewing an inspector scoped to that exact URL variation. The Parameters tab is hidden because you are already at the most specific level. Click the back arrow to return to the base URL.
**Why are there gaps in the Citation Rate Over Time chart?**\
The chart intentionally drops days where there were zero total responses generated across your account. Rather than plotting these days as 0% (which would artificially dip the line), the chart leaves a gap to smooth the trend across the days when AI responses were actually measured.
**Why did my YouTube link change to `youtube.com/watch?v=...`?**\
YouTube URLs (such as `youtu.be`, mobile links, or `youtube.com/shorts`) are automatically standardized to the main `watch?v=` format so that all citations for the same video are grouped together accurately.
**What happens when I click Export?**\
If you are on a plan that includes data exports, it will download a CSV file. If your plan does not include exports, the button will open an upgrade dialog instead.
# Source Domain Analytics (Sources drill-down)
Source: https://docs.athenahq.ai/guides/sources-root_domain
Deep-dive view for a single cited root domain, showing which URLs/prompts/responses cite it, its citation trend, and (for YouTube) creator/timestamp breakdowns.
`app.athenahq.ai/sources`
## Purpose
The Source Domain Analytics page provides a deep-dive view into a specific root domain (like `example.com` or `youtube.com`) that AI models have cited as a source. It shows you exactly which individual URLs on that domain are driving visibility, which prompts triggered those citations, and what the AI said. For YouTube domains, it additionally breaks down citations by creator channel and timestamp usage.
## What's on the page
* **Page header**: Displays a back arrow returning to the main Sources page, and a breadcrumb reading "Sources / \[domain]". The domain name is clickable and will open the live website in a new tab.
* **Filter row**: A sticky bar that lets you filter all the data on the page by date range, AI models, prompts, personas, locations, countries, prompt tags, prompt status, and attributes. It also includes "Source Mentions Brand" and "Source Mentions Competitor" filters, plus a Saved Views dropdown.
* **Citation Rate Over Time card**: A collapsible panel showing a line/area chart of the percentage of responses citing this domain over time. When collapsed, it shows a summary of the latest rate.
* **Lens tabs + toolbar**: A set of tabs to switch between different views of the domain's data (URLs, Prompts, Responses, and optionally Creators and Timestamps). Each tab has its own search box (e.g., "Search URLs…") and a download/export icon button.
* **URLs lens (URL Breakdown table)**: A table of every specific page on this domain that was cited by the AI.
* **Prompts lens (Prompt Breakdown table)**: A hierarchical table showing which topic groups and specific prompts drove citations to this domain.
* **Responses lens**: A table showing the actual AI responses that cited this domain.
* **Creators lens** *(YouTube domains only)*: A table grouping cited videos by their YouTube channel/creator.
* **Timestamps lens** *(YouTube domains only)*: A table and set of charts showing how often the AI linked to a specific moment in a video using a timestamp.
* **YouTube Timestamp Charts** *(YouTube domains only)*: Two charts located in the Timestamps tab: "Timestamped YouTube Citations by Model" (a horizontal stacked bar chart) and "Videos with Timestamps" (a donut chart).
### URL Breakdown table columns
* **(Checkbox)**: Lets you select rows for a bulk rescan. You can shift-click to select a range of rows.
* **URL**: The cited webpage. For YouTube videos or URLs with tracking parameters, variations are collapsed into a single row with an "Expand variants" arrow. A "View Analytics" icon appears on hover.
* **Source Mentions Brand**: Indicates whether your brand is mentioned in the text of this URL. Shows "Yes", "No", or "N/A" (if the page couldn't be scraped). Hovering over "N/A" explains that the presence is unknown.
* **Source Mentions Competitor**: Shows logos for any tracked competitors mentioned on this URL. Also shows "N/A" if the scrape failed.
* **First Seen**: The date this specific URL was first cited.
* **Citation %**: The percentage of all responses (matching your filters) that cited this URL.
* **Domain %**: The percentage of this specific domain's total citations that came from this URL.
* **Citations**: The total number of times this URL was cited.
* **(Actions)**: A hidden "⋯" menu at the end of the row containing a "Rescan" action.
### Prompt Breakdown table columns
* **Prompt**: The name of the topic group (which can be expanded) or the specific prompt text.
* **Tags**: Badges showing the prompt's type and custom tags. Clicking them opens the "Edit prompt tags" dialog.
* **Citation %**: The percentage of responses to this prompt that cited the domain.
* **Citations**: The number of times this domain was cited in responses to this prompt.
### Creator Breakdown table columns (YouTube only)
* **Creator**: The name of the YouTube channel. It links to the channel if known, and features an expand arrow to reveal individual videos.
* **Total Citations**: Total number of citations across all videos from this creator.
* **Avg Citation %**: Average citation percentage across all videos from this creator.
* **Videos**: The count of distinct videos cited from this creator.
* *(Expanded sub-table)* **Video**: The title of the specific video (linked), with a "View Analytics" shortcut.
* *(Expanded sub-table)* **Citations**: The citation count for the video.
* *(Expanded sub-table)* **Citation %**: The citation percentage for the video.
* *(Expanded sub-table)* **First Seen**: The date the video was first cited.
### YouTube Timestamps table columns (YouTube only)
* **YouTube title**: The title of the cited video (linked) with a "View Analytics" shortcut.
* **Prompt**: The text of the prompt that triggered this citation.
* **Timestamp**: The extracted timestamp parameter (e.g., `t=123`), or "—" if none exists.
* **Citations**: The citation count for this specific timestamped link.
* **Citation %**: The citation percentage for this specific timestamped link.
## What you can do here
* **Drill down into URL analytics**: Click any URL row in the URLs table, or any video row in the Creators/Timestamps tables, to open the deep-dive analytics drawer for that exact page. You can also Cmd/Ctrl-click to open the analytics page in a new tab.
* **Reveal hidden URL variations**: Click the "Expand variants" arrow next to a URL to see the raw tracking links (like `?utm_source=...`) or alternate formats (like `youtu.be` vs `youtube.com`) that the AI generated. Athena groups these so your stats aren't artificially split.
* **Expand topic and creator groupings**: Click a topic row in the Prompts tab, or a creator row in the Creators tab, to reveal the individual prompts or videos inside that group. You can also click the chevron in the column header to expand or collapse all groups at once.
* **Edit prompt tags**: In the Prompts tab, click the tags in a row (or the "Set tags" text) to open the "Edit prompt tags" dialog. Here you can classify the prompt type and apply custom tags.
* **Search the table**: Type into the search box above the table (e.g., "Search URLs…") to filter the currently active tab.
* **Export data**: Click the download/export icon button next to the search box. For the URLs, Prompts, Creators, and Timestamps tabs, this opens a dialog allowing you to choose how many rows to export (with a quick-select quantity selector and an "Export all" option) before downloading a CSV. For the Responses tab, clicking the export button immediately initiates the CSV download.
* **Rescan a single URL**: Click the "⋯" menu at the far right of a URL row and select "Rescan" to check the live page again for brand and competitor mentions. Alternatively, click the "N/A" badge in the mention columns to trigger a retry.
* **Bulk rescan URLs**: Check the boxes next to multiple URLs. A command bar will appear at the bottom of the screen. Click "Rescan" to queue all selected pages for rescanning, or "Clear" to drop your selection.
* **Load more data**: Scroll to the bottom of the URLs table, or click the "Load More" button at the bottom of the Creators or Timestamps tables, to fetch the next page of results.
## Data shown
* The page displays citation data from your tracked AI models, specifically filtered down to times those models linked to the root domain you are inspecting.
* Mention data ("Source Mentions Brand" and "Source Mentions Competitor") is derived from Athena actively visiting the cited URLs and reading the live content to see if your brand or tracked competitors are present.
* YouTube metadata (titles, channel names) is pulled from public YouTube information for the cited videos.
## Common workflows
1. **Identify the most impactful pages on a domain**
* Open the domain analytics page for a heavily cited source.
* Ensure you are on the **URLs** tab.
* Click the **Citations** or **Citation %** column header to sort descending.
* Review the top URLs. Click any row to open the URL inspector and see exactly which responses generated those citations.
2. **Find broken or unscrapable links to rescan**
* On the **URLs** tab, click the **Source Mentions Brand** column to sort the table, bringing the "N/A" results together.
* Use the checkboxes to select multiple URLs that failed to scrape.
* Click **Rescan** in the command bar at the bottom of the screen to queue them for another attempt.
3. **Export a list of top YouTube creators citing your brand**
* Open the analytics page for `youtube.com`.
* Click the **Creators** tab.
* Click the export icon button next to the search bar.
* In the "Export Creator Breakdown" dialog, choose your desired export limit (e.g., 100, 500, or All).
* Click **Export** to download the CSV.
## Empty, loading, and error states
* **Empty**: If no data matches your criteria, you will see a tab-specific message such as "No citation data found for this period", "No URLs match “...”", "No prompts found.", "No YouTube videos found for this source", or "No timestamped YouTube sources found."
* **Loading**: While data is fetching, an animated spinner appears in the trend card and the tables.
* **Error**: If a network request fails, you will see a message like "Couldn't load citation data." or "Couldn't load prompt data." alongside a "Retry" button to attempt the fetch again. If an error occurs while loading a subsequent page of infinite-scroll results, the table keeps the already-loaded rows visible instead of collapsing into an error state.
## Linked from / links to
* **Linked from**: The main Sources page (by clicking on a root domain in the table).
* **Links to**:
* The live, external website (by clicking the domain name in the header, or clicking specific links in the tables).
* The deep-dive URL Analytics drawer or page (by clicking a URL row or the "View Analytics" icon).
## Common support questions
* **Why do some URLs have a small arrow I can click to expand?**
AI models often cite the exact same webpage using slightly different links (for example, by adding tracking codes like `?utm_source=chatgpt.com`, or using `youtu.be` instead of `youtube.com`). Athena intelligently groups these messy variations together into a single canonical row so your citation metrics aren't artificially split. Clicking the arrow lets you see the raw, exact links the AI actually output.
* **What does "N/A" mean in the Mention columns?**
"N/A" means Athena attempted to read the live webpage to check for your brand or competitors, but couldn't access the content. This typically happens if the website blocks scrapers, returns an error, or requires a login. You can click the N/A badge to try rescanning the page.
* **Where did the general "Competitors" filter go?**
On this specific drill-down page, the general "Competitors" response filter is hidden from the top bar. This is intentional: applying it would accidentally hide all the legitimate "N/A" (scrape failed) rows from the URL table. You should use the "Source Mentions Competitor" filter instead.
* **Why can't I click the Rescan button?**
Rescanning URLs requires specific feature access on your subscription plan. If you lack the required permissions, the Rescan buttons will be visible but disabled.
* **Why did I get a popup about upgrading when I clicked Export?**
Data exports are a premium feature. If you are on a Free plan, clicking the export button will open a dialog prompting you to view available plans instead of downloading the file.
# Sources Visualization
Source: https://docs.athenahq.ai/guides/sources-visualization
Shows an interactive Sankey diagram of which web sources LLMs cite when mentioning the brand or its competitors, so users can find high-value sources, competitor intel, and content gaps.
`app.athenahq.ai/sources/visualization`
## Purpose
The Sources Visualization page provides an interactive chart that maps out exactly where AI models (like ChatGPT and Perplexity) are getting their information when they talk about your brand or your competitors.
By visualizing the connections between web sources and brand mentions, you can easily spot which domains are driving the most value for you, uncover sources that are heavily feeding competitor recommendations, and identify content gaps where high-traffic domains mention competitors but leave you out.
## What's on the page
### Page Header
Shows the title "Sources Visualization" along with an info icon. Hovering over the info icon displays the following explanation:
* **More About Source Attribution:** This graph shows where LLMs get their information from when they mention your brand and competitors. Thicker connections = more responses where an LLM mentioned the brand (RIGHT) and cited a source (LEFT) that mentions the brand.
* **LLM Citations Deep Dive:** When an LLM mentions your brand, it is from finding a source that mentions your brand. This is finding those deep sources, and pointing you to them.
* **Competitor intel:** See which sources drive competitor recommendations.
* **Content gaps:** Find high-traffic sources that mention competitors but not you.
* **Click any connection to see the actual LLM responses**
### Top Sources Chart
An interactive visualization (often called a Sankey diagram) that maps the flow of citations.
* **Left-side nodes (Indigo):** The web sources (domains) that AI models cited.
* **Right-side nodes:** The entities being mentioned by the AI. Your brand appears in green, while tracked competitors appear in orange.
* **Connections (Lines):** The flowing lines represent responses where the AI cited the source on the left and mentioned the brand/competitor on the right. Thicker lines mean a higher volume of responses.
## What you can do here
* **Magnify the chart:** Toggle the **Magnify** switch above the chart to enable a fisheye effect. When enabled, moving your mouse over the chart smoothly enlarges the nodes and links nearest to your cursor, making it easier to read dense clusters of data.
* **Focus on a specific node:** Click on any node (a source on the left or a brand/competitor on the right) to enter focus mode. The chart will filter down to show *only* the connections flowing into or out of that specific node.
* **Reset the view:** When focused on a single node, a **Reset view** button appears above the chart. Clicking this (or clicking the node again) restores the full chart.
* **View node details (Hover):** Hover over any node to see a tooltip displaying the domain/brand name, the total number of citations it has, and its percentage share of the total.
* **View connection details (Hover):** Hover over the line connecting a source to a brand. A tooltip will appear showing the exact number of responses making that connection, the percentage share, and a breakdown of the flow (e.g., "① LLM cited \[Source] as a source" and "② \[Source] & the LLM mention \[Brand]").
* **Drill down into responses (Click):** Click on any connection line to drill down. This navigates you to the standard **Sources** page, automatically applying filters so you can read the actual AI responses that cited that source and mentioned that brand/competitor.
* **Add and adjust filters:** Use the **Add filter** menu to refine the chart by Date Range, Models, Topics & Prompts, Competitors, Personas, Locations, Countries, Prompt Tags, Prompt Status, Mentioned, Source Tag, Attributes, and Brand Identifiers.
* **Manage saved views:** Click the **Views** dropdown to:
* **Save as view:** Save your current filter configuration.
* **Load a view:** Click an existing view to apply its filters.
* **Edit:** (Inside the ⋯ menu) Rename the view or change its icon.
* **Update filters:** (Inside the ⋯ menu) Overwrite the saved view with whatever filters are currently active on your screen.
* **Set as default / Remove default:** (Inside the ⋯ menu) Choose which view loads automatically when you visit the page.
* **Export as CSV:** (Inside the ⋯ menu) Download a CSV file of the prompts that match the view's filters.
* **Delete:** (Inside the ⋯ menu) Permanently remove the view (requires confirmation).
* **Use mobile filters:** On smaller screens, click the **Filters** button to open a drawer containing all available filter fields for touch-friendly editing.
## Data shown
The visualization is built from the AI responses collected for your tracked prompts across your selected models (such as ChatGPT, Claude, and Gemini) and date range. It aggregates citation and mention data, mapping the web domains cited by the AI to mentions of your brand and your configured competitors.
## Common workflows
**Find top sources driving brand mentions**
1. Ensure the chart is showing data for your desired date range and models.
2. Look at the left side of the chart for the tallest (thickest) source nodes, which indicate the highest citation volume.
3. Hover over the lines connecting these top sources to your brand's green node on the right to see exactly how many responses they share.
4. Click the connection line to drill down and read the specific AI responses.
**Investigate competitor-driving sources**
1. Use the filter bar to add a **Competitors** filter, narrowing down the right-side nodes to specific rivals.
2. Scan the chart for thick orange lines connecting a left-side source to a competitor node.
3. Click the connection to view the underlying responses, helping you understand why that source is heavily recommending them.
**Focus on a single source or brand node**
1. Click on a specific node in the chart (for example, a high-traffic source domain you want to analyze).
2. The chart will immediately filter out unrelated data, isolating only the connections flowing in and out of that selected node.
3. When you are done investigating, click the **Reset view** button above the chart to return to the global view.
**Save a current filter combination as a view**
1. Add and adjust your desired filters (e.g., specific models, a certain competitor, and a custom date range).
2. Click the **Views** dropdown in the top left.
3. Click **Save as view**, type in a memorable name, and select an icon.
4. Click **Save**. The view is now stored in the dropdown for quick access later.
## Empty, loading, and error states
* **Loading:** While the chart data, website details, or competitor lists are being fetched, a spinning animated loader is displayed in the center of the chart area.
* **Empty:** If there is no data available for your current filter combination, if you have no competitors configured, or if the system is waiting for data to process, the chart area displays a dimmed, blurred-out placeholder graphic. This is intentionally blurred to indicate that no real data matches the current criteria.
## Linked from / links to
* **Linked from:** The main navigation menu (under the Sources section as the "Sources Visualization" tab), and from the standard Sources page (if a user clicks back after a drilldown).
* **Links to:** The standard **Sources** page (when clicking a chart connection to drill down into the specific AI responses).
## Common support questions
**What does the thickness of the connection mean?**
The thickness of a line represents the volume of AI responses. A thicker line means the AI cited that specific source and mentioned that specific brand/competitor together more frequently.
**Why is the chart blurry or dimmed out?**
The chart appears blurred and dimmed when there is no data to display for your current filters, or if you don't have any competitors set up yet. Try broadening your date range or removing some filters.
**How do I see the actual AI responses?**
Click on any of the flowing lines connecting a source to a brand. This will take you to the standard Sources page, automatically filtered to show the exact responses that make up that connection.
**What does the Magnify toggle do?**
The Magnify toggle turns on a fisheye lens effect. When enabled, the parts of the chart closest to your mouse cursor will smoothly expand, making it much easier to read the labels and see individual lines in areas where the chart is tightly packed.
# Integrations
Source: https://docs.athenahq.ai/integrations
Connect analytics, CMS, dashboarding, and reporting tools to Athena
This article explains every integration available in Athena: what it does once you connect it, what credentials or permissions you'll need, and exactly where in the app you'll see the results.
If you're looking for setup instructions for a specific integration, open **Settings > Integrations** in Athena and click the relevant tile - each panel has inline step-by-step guidance and a link to the provider's docs.
***
## How integrations work in Athena
Most Athena integrations are scoped to a single website. If your organization has more than one website connected to Athena, each website has its own set of integration connections (e.g. each website connects its own GA4 property). The exception is the Athena **Slack bot** for Enterprise plans, which is configured once per organization.
All integrations are managed from one place: **Settings > Integrations**. Integrations are grouped into five sections that mirror what they enable:
* **Measure & Attribute** - Google Analytics 4 and Google Search Console. These connect site traffic and search visibility data to Athena's analytics surfaces.
* **Create & Publish** - Shopify, Webflow, Wix, Framer, WordPress, Payload CMS. These let you publish content created in Athena directly to your live site.
* **Monitor & Visualize** - Looker Studio. For building custom dashboards in your BI tool.
* **Reports** - Slack reports. For sending scheduled Athena reports to a Slack channel or DM.
* **Organization** - The Athena Slack bot for Enterprise plans.
Admin-level access is required to connect, edit, or disconnect any integration. Viewer-level users will see the tiles but won't be able to manage them.
***
## Google Analytics 4 (GA4)
### What it does
Once you connect a GA4 property to Athena, your traffic data flows into Athena's analytics views. Athena uses GA4 read-only - it never writes to your GA4 property or changes anything on the Google side.
### What you'll need
* A Google account with access to the GA4 property you want to connect.
* Read access to the property.
### How to connect
1. Open **Settings > Integrations**.
2. Click the **Google Analytics 4** tile.
3. Click **Connect Google Analytics** and authorize through the Google OAuth popup.
4. If your account only has access to one property, Athena auto-selects it. Otherwise, pick the right property from the searchable dropdown.
To switch the active property later, open the GA4 panel and pick a different property - the change applies immediately. Use the refresh icon at the top of the panel to re-fetch the list of properties from Google.
### Where you'll see the results
There is no standalone GA4 dashboard in Athena. Your GA4 data appears where it adds context to your AI-search work, and Ask Athena is where you query the property directly:
* **Ask Athena.** The assistant queries your connected property directly, so you can ask for any combination of GA4 dimensions and metrics in chat: sessions by `sessionSource` or `sessionMedium`, page views by `pagePath`, bounce rate by country or device, key events (conversions), period-over-period comparisons, or live data from the last 30 minutes. This is where you isolate AI-search referrals - ask for sessions by `sessionSource` and look for `chat.openai.com`, `perplexity.ai`, or `gemini.google.com`.
* **Content Hub (left sidebar > Content).** Set the *Metrics* column dropdown to **Site analytics** to see Traffic, Bounce rate, Engagement rate, Avg duration, and **AI traffic** per row. Click a row's Metrics cell to open its Metrics Drawer, which charts those GA4 values over time. The aggregate view at the bottom of the sheet shows the same breakdown averaged across your published rows.
* **Importing content from GA4.** When you add rows to the Content Hub, the GA4 import reads your property's top pages by traffic so you can pick which URLs to track.
* **Win Finder.** Wins can chart GA4 sessions for a content URL next to its AI-visibility metrics, so you can see the traffic movement behind a win. The What's Working card on Olympus opens the same view.
**Looking for the old Traffic page?** It was retired in July 2026. The metrics it showed are available per content URL in the Content Hub, and broader breakdowns (traffic sources and referrers, top pages, devices, geography, events and conversions) are available by asking Ask Athena - for example, "sessions by sessionSource over the last 28 days". The interactive user-journey flow is no longer available.
### If something goes wrong
* **"GA4 connection expired":** your GA4 OAuth token has expired. You'll see this when Athena tries to read the property - for example when importing content from GA4 - and the Site analytics metrics stop updating in the Content Hub. Open **Settings > Integrations**, click the **Google Analytics 4** tile, and click **Connect Google Analytics** again to refresh.
* **Property dropdown is empty:** your Google account doesn't have access to any GA4 properties, or the OAuth scope was denied. Confirm in Google Analytics that you can see the property, then reconnect.
***
## Google Search Console (GSC)
### What it does
Once connected, Athena reads your GSC property's queries, impressions, and clicks. This data powers Athena's prompt discovery and the organic-search metrics shown throughout the product. Like GA4, GSC is read-only - Athena never writes to GSC.
### What you'll need
* A Google account with access to a verified GSC property (Domain or URL-prefix).
### How to connect
1. Open **Settings > Integrations**.
2. Click the **Google Search Console** tile.
3. Click **Connect Search Console** and authorize through the Google OAuth popup.
4. Pick the right site from the searchable dropdown. Sites are labeled as either *Domain* or *URL-prefix* matching how they're set up in GSC.
If you're not sure whether the property exists, use the **Open GSC** button in the panel to jump straight to Search Console in a new tab.
### Where you'll see the results
* **Discover (left sidebar > Prompts > Discover).** When you run discovery, GSC powers the **Search Console** source - Athena clusters your top-performing search queries and proposes prompts you can accept into your tracked set. Discovered prompts that came from this source are tagged with a *GSC* source badge in the results. Without a GSC connection, the Search Console source appears disabled in the Run discovery drawer with a connect link.
* **Content Hub (left sidebar > Content).** Set the *Metrics* column dropdown to **Organic search** to see Clicks, Impressions, and CTR per row. The row's Metrics Drawer also shows GSC trend charts over time.
### If something goes wrong
* **No properties listed after connecting:** verify in GSC that your Google account is a verified user on at least one property. Then re-open the panel and click the refresh icon at the top.
* **GSC data missing from a row in the Content Hub:** GSC data takes a short while to backfill after the first connection. If a row's GSC metrics never appear, check that the page's URL matches a URL GSC tracks for the connected property.
***
## Google Ads
### What it does
Connecting Google Ads links your Google Ads account to your Athena website and stores which Ads customer account is selected. This is currently a **connect-only** integration: at this time no Athena feature (Discover, Olympus, Content Hub, Win Finder) reads keyword, search-term, or campaign data from your connected Ads account. The connection is in place so that Ads-aware features can use it once they ship. We'll update this article as new Ads-powered surfaces go live.
### What you'll need
* A Google account with access to one or more Google Ads customer accounts.
### How to connect
1. Open **Settings > Integrations**.
2. Click the **Google Ads** tile.
3. Click **Connect Google Ads** and authorize through the Google OAuth popup.
4. Pick the right Ads customer account from the searchable dropdown. Manager (MCC) accounts are labeled as such.
You can switch accounts at any time using the dropdown in the panel.
### Where you'll see the results
* **Settings > Integrations > Google Ads panel.** Shows connection status, the active Ads customer account, and the account-switch dropdown.
***
## Shopify
### What it does
The Shopify integration enables two things:
1. **Publishing from Athena.** Articles you create in Athena's Content Hub can be published directly to your Shopify blog.
2. **Catalog Optimization.** Athena imports your Shopify products so you can generate and publish optimized titles, descriptions, metadata, and FAQs.
### What you'll need
* Permission to install apps on the Shopify store.
* Permission to manage integrations for the Athena website you want to connect.
* An Enterprise or Agency plan to use Catalog Optimization.
### How to connect
1. In Athena, open **Settings > Integrations** and click the **Shopify** tile.
2. Click **Open Shopify App Store**.
3. Install **AthenaHQ Commerce** on the target Shopify store and approve the requested permissions.
4. After Shopify returns you to Athena, confirm that the intended website is selected and click **Connect Shopify**.
5. Choose a **Default Blog** from the Shopify panel. New posts publish to this blog by default.
### Where you'll see the results
* **Settings > Integrations > Shopify panel.** Shows the connected store name, primary domain, last verified date, the **Default Blog** dropdown, and any missing-scope warnings.
* **Action Center > Catalog Optimization.** Import products, generate optimized drafts, and publish approved product changes.
* **Content Hub > open a content row > Publish dialog > Shopify tab.** Configure blog, title, slug, author, and draft-vs-production status, then click **Publish** or **Update**. After publishing, a success dialog shows the new URL with a *View Article* button.
### If something goes wrong
* **"Missing scopes" warning in the Shopify panel:** open **AthenaHQ Commerce** from Shopify admin to reconnect and approve the requested permissions.
* **"Article not found" (404) when updating a Shopify post:** the article was deleted from Shopify outside of Athena. Use the **Publish as new** option in the Athena editor instead of trying to update.
***
## Webflow
### What it does
Connecting Webflow lets you publish articles from Athena's Content Hub directly to your Webflow CMS. Athena reads your CMS collection schemas so it understands which fields each collection expects (title, body, slug, summary, author, etc.) and pre-fills them on publish. You can review and override any field before publishing.
### What you'll need
* A Webflow site you own or have edit access to.
* A Webflow Site Token (Webflow's API token model - not OAuth) with the scopes **Sites: Read** and **CMS: Read & Write**.
Tokens expire after **365 days of inactivity**, so long-running sites may need to regenerate and reconnect once a year.
### How to connect
1. In Webflow, go to **webflow\.com/dashboard** and generate a Site Token with the scopes above. (Webflow's own docs: [Site Token](https://developers.webflow.com/data/v2.0.0/docs/data-clients/get-a-site-token).)
2. In Athena, open **Settings > Integrations** and click the **Webflow** tile.
3. Paste the token into **Step 1 - Add your Webflow token** and click **Verify token**.
4. In **Step 2 - Select your site**, pick which Webflow site to connect and click **Save connection**.
After connecting, Athena syncs your CMS collections and shows them in a collapsible list inside the panel, including each field's name, slug, and type. Use the refresh icon at the top of the panel to re-sync if you add or change collections in Webflow.
### Where you'll see the results
* **Settings > Integrations > Webflow panel.** Shows the connected site name and domain, the last verified date, and the full list of synced CMS collections with their field schemas.
* **Content Hub > open a content row > Publish dialog > Webflow tab.** Pick a collection, review the auto-mapped fields (title, content, slug, summary, author), choose draft vs. live, and click **Publish**. After publishing, a success dialog shows the new URL and a *View Post* button; you can also use the pencil icon in the success dialog to manually edit the recorded published URL.
### If something goes wrong
* **"Token expired"** or repeated authentication errors: your Site Token has hit its 365-day inactivity window. Generate a new Site Token in Webflow with the same scopes and paste it into the panel.
* **A collection field isn't mapping correctly:** Athena uses a pattern-based matcher (looking for slugs like `title`, `body`, `content`, `slug`, `summary`, `author`). For collections with unusual field slugs, you can override the mapping manually in the publish dialog before clicking Publish.
* **Webflow "validation error" or "data conflict" on publish:** the article body or metadata didn't match Webflow's collection schema (e.g. required field missing, slug already taken). The toast message from Webflow tells you which field - fix it in the publish dialog and try again.
***
## Wix
### What it does
Connecting Wix lets you publish blog posts and drafts from Athena directly into your Wix site. Once connected, Athena reads your Wix blog categories and member list so you can attribute posts to a specific Wix site member when publishing.
### What you'll need
* The **Site ID** of your Wix site. You can find this in the dashboard URL - it's the segment after `/dashboard/`.
* A **Wix API key** with the *Wix Blog* and *Read Members* permissions. Manage API keys at [manage.wix.com/account/api-keys](https://manage.wix.com/account/api-keys).
* A Wix site member to publish *as*.
### How to connect
1. In Athena, open **Settings > Integrations** and click the **Wix** tile.
2. Enter your Site ID and API key.
3. Click **Load site members** to populate the *Publish as* dropdown from your Wix Members.
4. Pick a member and click **Connect Wix**.
### Where you'll see the results
* **Settings > Integrations > Wix panel.** Shows Site URL, Site ID, Member ID, an indicator that the API key is stored securely, category count, recent drafts list, and a list of up to 10 Wix categories.
* **Content Hub > open a content row > Publish dialog > Wix tab.** Pick a category, configure title/slug/etc., and publish.
To rotate the API key or change the publishing member later, click **Edit settings** in the Wix panel.
***
## Framer
### What it does
Connecting Framer lets you publish content to your Framer CMS collections from Athena.
### What you'll need
* The Framer **project URL or ID**. Use the editor URL (e.g. `framer.com/projects/Site--abc123`) or just the project ID - **do not use** the published `.framer.website` URL.
* A Framer **API key**, generated in **Site Settings > General > API Keys** within Framer.
### How to connect
1. In Athena, open **Settings > Integrations** and click the **Framer** tile.
2. Enter the project URL or ID and the API key.
3. Click **Verify connection**, then **Save connection** once verification succeeds.
### Where you'll see the results
* **Settings > Integrations > Framer panel.** Shows the connected project, the project URL, and a collapsible list of Framer CMS collections with each field's name, ID, and type.
* **Content Hub > open a content row > Publish dialog > Framer tab.** Pick a collection and publish.
Use the refresh icon at the top of the panel to re-sync collections if you add or change them in Framer.
***
## WordPress
### What it does
Connecting WordPress lets you publish new posts and update existing ones in your WordPress site from Athena. Both **self-hosted WordPress** (using application passwords) and **WordPress.com / Jetpack-connected sites** (using OAuth) are supported. Athena automatically detects which connection method your site uses.
### What you'll need
* The URL of your WordPress site (e.g. `example.com`).
* If self-hosted: a WordPress user account and an **application password** for that user. Generate one in **Users > Profile > Application Passwords** within the WordPress admin.
* If WordPress.com / Jetpack: ability to authorize Athena via WordPress.com OAuth.
### How to connect
1. In Athena, open **Settings > Integrations** and click the **WordPress** tile.
2. Enter your site URL and click **Detect connection method**.
3. If a self-hosted site is detected: enter your username and the application password, then click **Connect**.
4. If WordPress.com OAuth is detected: click **Connect with OAuth** and authorize Athena in the popup.
### Where you'll see the results
* **Settings > Integrations > WordPress panel.** Shows site name, an *OAuth* or *App password* badge depending on the connection type, site URL, the username (for app password connections), post count, and a list of up to 10 WordPress categories with post counts.
* **Content Hub > open a content row > Publish dialog > WordPress tab.** Pick a post status (draft, pending, publish), category, and publish.
Use the refresh icon at the top of the panel to re-sync posts and categories from WordPress.
### If something goes wrong
* **"OAuth not configured"** amber notice on the WordPress.com flow: Athena's WordPress.com OAuth credentials aren't configured for your instance. Contact Athena support - the workaround is to use application passwords for that site instead.
* **"Authentication failed"** with a self-hosted site: confirm the application password is correct (it's the long generated string, not your normal WordPress login password) and that the user has permission to publish to the site.
***
## Payload CMS
### What it does
Connecting Payload lets you publish content from Athena into a self-hosted Payload CMS deployment. Athena reads your Payload collections so it knows which collections you can publish to and what permissions are available.
### What you'll need
* The root URL of your Payload deployment (e.g. `cms.example.com`) - **not** the `/admin` or `/api` path.
* A Payload **API key**, generated from a Payload users collection that has `auth: { useAPIKey: true }` enabled. Inside Payload, enable API keys on that collection, create a user with the right role, and copy the generated key.
### How to connect
1. In Athena, open **Settings > Integrations** and click the **Payload CMS** tile.
2. Enter your Payload server URL and API key.
3. Click **Verify connection**. Once it succeeds, click **Save connection**.
You can mask/unmask the API key field with the eye icon while entering it.
### Where you'll see the results
* **Settings > Integrations > Payload CMS panel.** Shows the connected server URL, a list of **Publishable collections** with their read/create/update permission badges, and a separate list of **System collections** (Payload's built-in and first-party plugin collections, which are hidden from Athena's publish dialog).
* **Content Hub > open a content row > Publish dialog > Payload tab.** Pick a publishable collection and publish.
***
## Looker Studio
### What it does
The Looker Studio integration lets you build dashboards in your Looker Studio account that pull from Athena's data through a community connector. Once set up, your Looker Studio dashboards update automatically with Athena's brand-visibility data alongside any other data sources you use.
Unlike most Athena integrations, Looker Studio is **set up outside Athena**. Clicking the tile in Athena opens a step-by-step instructions drawer rather than an OAuth flow.
### What you'll need
* An Athena API key (generate one when prompted during setup).
* A Looker Studio account.
### How to connect
1. In Athena, open **Settings > Integrations** and click the **Looker Studio** tile to open the setup instructions.
2. Follow the steps in the drawer to generate an Athena API key and add the Athena community connector to Looker Studio.
3. Build your dashboards in Looker Studio using the connector.
### Where you'll see the results
* The dashboards themselves live in **Looker Studio**, not inside Athena. The Looker Studio tile in Athena always shows a *Setup guide* button rather than a connected/disconnected state - that's normal.
***
## Slack reports
### What it does
Connecting Slack lets Athena deliver scheduled reports (PDFs) directly into Slack channels or DMs. Reports are built in the Reports area of Athena and can include any of Athena's charts, scoped with filters. Each report has its own cadence (weekly, monthly, or quarterly) and its own list of recipients.
The Slack reports integration is per-website. If your organization has multiple websites in Athena, each website has its own Slack workspace connection.
### What you'll need
* A Slack workspace and permission to authorize an app in it.
### How to connect
1. In Athena, open **Settings > Integrations** and click the **Slack reports** tile.
2. Click **Connect Slack** and authorize via the Slack OAuth popup.
After connecting, configure which channels or DMs receive each report from the **Reports** area:
1. Go to **Reports** in the left sidebar and open or create a report.
2. Click **Settings**.
3. Under **Recipients**, change the channel-type dropdown from **Email** to **Slack channel** or **Slack DM**, then pick the channel/user and click **Add**.
4. Save the report.
You can also click **Send now** in the Report Builder to dispatch the report immediately and confirm Slack delivery is working - a confirmation dialog shows how many recipients (split by channel type) will receive it.
### Where you'll see the results
* **Settings > Integrations > Slack reports panel.** Shows the connected Slack workspace name and the date you connected it.
* **Reports > any report > Settings > Recipients.** Lists every email, Slack channel, and Slack DM recipient configured for that report.
* **Slack itself.** On the scheduled cadence, each report is delivered as a PDF attachment in the configured channels and DMs.
***
## Slack bot (Enterprise)
### What it does
The Athena Slack bot lives in your Slack workspace and answers brand-visibility questions in tracked channels (e.g. someone tags `@Athena` and asks about share of voice or recent citations). The bot is **org-wide** - installed once per organization, not per website - and is available on **Enterprise plans only**.
### What you'll need
* An Enterprise plan.
* A Slack workspace and permission to install an app in it.
### How to connect
1. In Athena, open **Settings > Integrations** and click the **Slack bot** tile.
2. Click **Connect Slack** and authorize via the Slack OAuth popup.
3. In Slack, invite **@Athena** to any channel you want the bot to respond in.
4. Back in Athena's Slack bot panel, use the **Add a channel** dropdown to pick that channel from the list and add it to the tracked-channels list.
For Slack Connect (shared channels), the dropdown won't show the channel directly. Use the **Add by channel ID** option instead - right-click the channel in Slack > Copy link > the ID looks like `C01ABCD2EFG`. You can also add optional notes (e.g. a customer name) when adding a channel by ID.
### Managing tracked channels
The Slack bot panel lists every tracked channel with:
* The channel ID and optional notes
* An **Enabled / Disabled** toggle (the bot only responds in enabled channels)
* A **Remove** button to stop tracking the channel entirely
Disconnecting the Slack workspace preserves your channel rules - if you reconnect later, your tracked-channels configuration is still there.
### Where you'll see the results
* **Settings > Integrations > Slack bot panel.** Connection status, the tracked-channels list, and per-channel enable/disable controls.
* **Your Slack workspace.** Mentions of `@Athena` in tracked channels.
***
## Frequently asked questions
### I'm a viewer in my org - why can't I connect anything?
Connecting, editing, or disconnecting integrations requires Admin access. Tiles will appear dimmed for viewer users, and panels won't open. Ask an Admin on your team to manage integrations on your behalf.
### My OAuth popup closed before I finished authorizing. What happened?
If the popup closes mid-authorization, Athena shows the error *"The authorization window closed before we finished. Try again and keep the popup open until consent is complete."* Just click **Connect** again and complete the consent flow in the popup.
### How do I switch the GA4 property / GSC site / Google Ads account on my connected integration?
Open the relevant integration panel from **Settings > Integrations**. Each Google integration panel has a searchable dropdown that lets you change the active property/site/account, plus a refresh icon at the top to re-fetch the list of available options from Google. The change applies immediately.
### How do I disconnect an integration?
Click the integration's tile, then click **Disconnect** at the bottom of the panel. Athena uses a two-step disconnect - after the first click, a *Cancel / Confirm disconnect* pair appears; click **Confirm disconnect** to actually remove the connection. This applies to every integration in Athena and is intentional to prevent accidental disconnects.
### Do Google integrations ever write back to Google?
No. GA4 and GSC are read-only data connections. Google Ads is currently connect-only: Athena stores the selected Ads account but does not read campaign, keyword, or search-term data yet. Athena never writes back to Google Analytics, Search Console, or Ads.
### Are integrations per-website or shared across my organization?
Almost every integration is **per-website** - switching websites in Athena changes which connections you see, because each website has its own analytics, CMS, and Slack-reports connections.
The only exception is the **Slack bot** (Enterprise only), which is installed once per organization and tracks channels at the org level.
### What happens to my report recipients if I disconnect Slack reports?
Disconnecting Slack reports removes the Slack workspace connection but does not delete your configured Slack recipients on each report. The recipient lists remain - they just won't deliver until you reconnect a Slack workspace.
### What happens to my tracked Slack bot channels if I disconnect?
Disconnecting the Slack bot preserves your channel rules. If you reconnect the same workspace later, your tracked-channels list is restored.
### My Webflow token isn't working anymore - why?
Webflow Site Tokens expire after **365 days of inactivity**. If you haven't published from Athena to Webflow in over a year, you may need to generate a new Site Token in your Webflow dashboard (with the same Sites: Read and CMS: Read & Write scopes) and reconnect.
### How do I reconnect AthenaHQ Commerce?
Open **AthenaHQ Commerce** from Shopify admin. Shopify returns you to Athena, where you can confirm the intended website and reconnect the store.
### How do I add the Athena Slack bot to a private or Slack Connect channel?
The Slack bot's channel picker only shows channels that `@Athena` is already a member of. For private channels, invite `@Athena` from inside Slack first; the channel will then appear in the **Add a channel** dropdown in Athena. For Slack Connect (shared) channels, the picker won't show them at all - use the **Add by channel ID** manual entry: right-click the channel in Slack > *Copy link* > the channel ID looks like `C01ABCD2EFG`.
### Can I deep-link directly to a specific integration's panel?
Yes. Use `Settings > Integrations` with a `?provider=` query parameter (e.g. `?provider=ga4`, `?provider=gsc`, `?provider=webflow`). The matching panel opens automatically on page load. Viewer users won't have the panel open even via deep link, because they don't have permission to manage integrations.
***
If you can't find the answer to your question here, reach out to your Athena account team or contact support - we're happy to walk through any integration with you live.
# Knowledge Base
Source: https://docs.athenahq.ai/knowledge-base
Give Athena verified facts about your business for accurate research and content generation
The Knowledge Base is where you tell Athena the verified facts about your business - your pricing, products, policies, positioning - so that everything Athena writes about you stays consistent and accurate. Once it's set up, Athena draws from the Knowledge Base whenever it researches, generates, optimizes, or fact-checks your content.
**Note:** The Knowledge Base is included in some plans and not others. If your plan doesn't include it, you'll see a *Feature locked* screen when you try to open it. Reach out to your Athena account team if you'd like access.
***
## What the Knowledge Base does
Think of the Knowledge Base as the source of truth Athena consults whenever it needs to know something specific about your business. It does three things:
* **Stores verified facts.** Statements like "Our Pro plan starts at \$99/month" live in the Knowledge Base as source-backed entries, grouped under pillars.
* **Tracks your internal pages.** It maintains a list of pages on your own domain so Athena knows what content of yours already exists and can recommend internal links when writing or optimizing content.
* **Measures content coverage.** It shows you how well your existing content already covers each pillar, so you can see where to invest in new articles.
Every fact in the Knowledge Base traces back to a source - Athena doesn't make things up. It only uses claims that you've added directly or that came out of a source you provided.
***
## How it's organized
There are two things in the Knowledge Base:
* **Pillars** - subject areas your brand wants to be the authority on (for example, *Pricing*, *Integrations*, *Onboarding*, a specific product category, or your *Return policy*). Each pillar groups together the related facts Athena has learned. You can create pillars yourself, or let Athena discover them automatically.
* **Internal links** - pages on your own domain that Athena should know about when generating or optimizing content. Adding more of your own pages here means Athena has more places to link to internally.
Each pillar has its own detail view where you can see the claims attached to it, the internal pages associated with it, and a synthesized summary document Athena builds from those claims.
***
## Finding the Knowledge Base
The Knowledge Base is its own left-sidebar item - click **Knowledge Base** in the sidebar to open it.
Inside, you'll see two tabs:
* **Pillars** - every pillar Athena knows about for your site, with a *Content coverage* bar showing how well your existing content covers each one.
* **Internal links** - every page on your own domain that's been added to the Knowledge Base.
In the top right of the page you'll find two controls:
* **Verify facts** - runs a validation analysis (see *Verifying facts against the outside world* below).
* **Add knowledge** - the entry point for adding new pillars, new claims, or new internal links.
***
## Setting it up
The fastest way to bootstrap a Knowledge Base from nothing is to let Athena do the initial research for you.
1. Open **Knowledge Base** from the sidebar.
2. Click **Add knowledge** > **Discover pillars**.
3. Confirm the research run.
Athena will analyze your site, propose a set of pillars relevant to your business, research each one, and start populating it with claims. This runs in the background; pillars appear in your Pillars tab as they're discovered, and claims continue to populate over the following minutes.
That's the only step required to get started - once pillars begin appearing, the Knowledge Base is live and Athena will start drawing from it.
***
## Adding more knowledge over time
Everything you can add lives under the **Add knowledge** dropdown, organized into two groups:
**Pillars**
* **Create pillar** - define a new subject area Athena didn't auto-discover. Give it a name and a short description.
* **Discover pillars** - let Athena auto-discover pillars relevant to your site (the same flow used during initial setup).
**Knowledge**
* **Add URLs** - paste URLs or crawl a domain. Athena adds the pages to your internal link bank and also extracts claims from them.
* **Upload document** - extract claims from a PDF, DOCX, or pasted text.
* **Extract from Content Hub** - pull claims from articles you've already published.
You can also add claims directly to a specific pillar by opening that pillar and using the *Add knowledge* options inside its detail view - anything you ingest from inside a pillar is automatically attached to it.
***
## Verifying facts against the outside world
The **Verify facts** button at the top of the Knowledge Base kicks off a validation analysis. Athena takes your pillars and checks them against the AI responses that Oracle has already collected and lists the third-party sources that contradict them.
This is useful as a periodic sanity check - for example, when a policy or pricing detail changes and you want to confirm that what's in your Knowledge Base still matches what's actually out there. Results land in the Oracle area of the app, where you can step through any discrepancies and decide what to update.
***
## How Athena uses the Knowledge Base
Once your Knowledge Base has some content in it, it shows up across the rest of Athena:
* **When Athena optimizes a piece of content.** The optimize view tells you exactly which pillars, claims, and internal links Athena pulled from while suggesting edits - each suggestion can show the supporting claim and its confidence.
* **When Athena drafts or edits content.** AI-attributed claims in the article body appear as highlights - clicking one shows the source and the pillar it came from in the right sidebar.
* **In suggestion citations.** Each AI suggestion that depends on a claim shows the claim, its pillar, and a link to the source.
* **In Oracle.** Oracle compares what AI search engines say about your brand against your Knowledge Base and flags discrepancies - your Knowledge Base is the source of truth it's checking against.
* **In Athena Agent columns in the Content Hub.** When you set up an Athena Agent column, you can toggle on the *Fact Bank* option to make the column pull from the Knowledge Base.
The short version: anywhere Athena needs to make a factual claim about your business, it reaches into the Knowledge Base first.
***
## Using the Knowledge Base through the API
The Knowledge Base is also accessible programmatically, over the REST API and as MCP tools:
* [Search Brand Facts](/api-reference/knowledge-base/search-brand-facts) — semantic search over approved facts (`search_brand_facts` on MCP).
* [Get Brand Facts](/api-reference/knowledge-base/get-brand-facts) — paged fact listing with filters (`get_brand_facts`).
* [Get Pillars](/api-reference/knowledge-base/get-pillars) — pillar catalog with fact counts (`get_pillars`).
* [Get Pillar Document](/api-reference/knowledge-base/get-pillar-document) — a pillar's synthesized markdown document (`get_pillar_document`).
* [Add Brand Facts](/api-reference/knowledge-base/add-brand-facts) — bulk fact ingestion through the full pipeline, with a per-fact outcome report (`add_brand_facts`). Requires a website-admin key.
* [Update Brand Fact](/api-reference/knowledge-base/update-brand-fact) - update one fact's text, source URL, or confidence (`update_brand_fact`). Requires a website-admin key.
* [Delete Brand Facts](/api-reference/knowledge-base/delete-brand-facts) - permanently delete 1-50 facts, no undo (`delete_brand_facts`). Requires a website-admin key; on OAuth connections, the admin role.
* [Create Pillar](/api-reference/knowledge-base/create-pillar) - get-or-create a pillar by name (`create_pillar`). Requires a website-admin key.
* [Update Pillar](/api-reference/knowledge-base/update-pillar) - rename a pillar, edit its description, or publish/archive it (`update_pillar`). Requires a website-admin key.
* [Delete Pillars](/api-reference/knowledge-base/delete-pillars) - permanently delete 1-20 pillars and every fact filed under them, no undo (`delete_pillars`). Requires a website-admin key; on OAuth connections, the admin role.
* [Merge Pillars](/api-reference/knowledge-base/merge-pillars) - fold source pillars into a published target, then delete the sources (`merge_pillars`). Requires a website-admin key.
* [Move Brand Facts](/api-reference/knowledge-base/move-brand-facts) - file 1-50 facts under a published pillar, including unfiled facts (`move_brand_facts`). Requires a website-admin key.
These endpoints require the Knowledge Base to be enabled for your organization; when it isn't, they return a `403`.
***
## Content coverage
Each pillar in the Pillars tab has a **Content coverage** bar. It shows what percentage of that pillar's facts are reflected in articles you've already published. A higher bar means you have content covering most of what Athena knows about that pillar; a lower bar (or a dash) means you've got facts in your Knowledge Base that no published article currently covers - usually a content gap worth filling.
Coverage updates as Athena indexes new content. It's a guide for spotting where to invest in writing next.
***
## Frequently asked questions
### Do I have to set up the Knowledge Base manually?
No. The fastest path is **Add knowledge > Discover pillars**, which has Athena research your site and propose pillars, claims, and supporting evidence on its own. You can refine and add to it from there.
### Where does the Knowledge Base get its facts from?
Athena extracts facts from a few different places: web research it runs on your site, documents or URLs you upload, articles already in your Content Hub, and AI search responses that mention your brand. Every claim records its source so you can see where it came from.
### What's the difference between an internal link in the Knowledge Base and an article in the Content Hub?
The Content Hub is where you track and measure the performance of pages you care about (your blog posts, key landing pages, etc.). The Knowledge Base's internal links are a broader set of pages on your own domain that Athena should be aware of when writing or optimizing content - they don't have to also be in the Content Hub.
### Why does my content coverage show a dash (-)?
A dash means there's no coverage data yet for that pillar - usually because the pillar doesn't have any claims yet, you don't have matching Content Hub articles, or coverage analysis hasn't run yet. It'll fill in as Athena indexes more content.
### How do I delete a pillar?
Open the Pillars tab, select the pillar with the checkbox, and use the action bar that appears at the bottom of the page to delete it. Deleting a pillar also deletes the claims attached to it.
### What does "Verify facts" do?
It runs a validation analysis that checks your pillars against external web sources (and against each other, for internal consistency). Athena surfaces any contradictions it finds in the Oracle area of the app, where you can review and decide what to update.
### How does the Knowledge Base interact with Oracle?
Oracle uses the Knowledge Base as the ground truth for fact-checking. When Oracle scans AI search responses for discrepancies, it's comparing them against what you've told Athena is true via the Knowledge Base. The richer your Knowledge Base, the more Oracle has to work with.
### My plan doesn't include the Knowledge Base - what can I still do?
You'll see a *Feature locked* screen when you open the Knowledge Base, and a few related features (like the Fact Bank toggle on Athena Agent columns) will be hidden. The rest of Athena continues to work normally. Reach out to your Athena account team if you'd like to add the Knowledge Base to your plan.
***
If you have a question that isn't covered here, reach out to your Athena account team or contact support - we're happy to walk through Knowledge Base setup or any specific workflow live.
# Oracle
Source: https://docs.athenahq.ai/oracle
Find and fix inaccurate AI search statements about your brand
Oracle is Athena's accuracy workspace. It looks at how AI search engines (ChatGPT, Perplexity, Claude, Gemini, Google AI Overview, Copilot, Grok, and others) describe your brand, compares those statements against your verified facts, and surfaces every discrepancy it finds. From there, you can review each one, decide which version is correct, and even generate ready-to-publish content drafts that address the most important issues.
You'll find Oracle in the left sidebar.
***
## What you can do here
Oracle is a single overview page. It shows:
* **Accuracy snapshot** - discrepancy rate, open issues, and coverage trends.
* **Top high-impact discrepancies** - the most important issues to review first.
* **Validation** - external sources that contradict your verified facts after you run Verify facts.
* **Coverage** - how complete your Pillars are relative to the topics AI is actually discussing.
A **Run analysis** button in the header lets you kick off two kinds of analyses on demand:
* **Check responses** - scans AI responses already collected for your site and flags claims that don't match your Pillars.
* **Verify facts** - picks selected Pillars and looks for external sources (e.g. third-party websites, AI responses) that contradict them.
The Pillars and facts Oracle uses as its source of truth live in the **Pillars** tab of **Knowledge Base**. Oracle-generated remediation drafts are reviewed from **Content > Content Hub** as in-progress drafts.
***
## How to get started
1. Make sure the **Pillars** tab in Knowledge Base has at least the topics you care about. Athena uses your Pillars as the ground truth for every discrepancy check, so the quality of Oracle's findings depends on what's in there. If you haven't set up Pillars yet, start with the [Knowledge Base / Pillars article](./knowledge-base).
2. Open **Oracle** in the sidebar.
3. Click **Run analysis > Check responses**.
4. Pick a date range (Last 7 / 14 / 30 days, or custom). Athena will show you how many AI responses fall in that window before you start.
5. Click **Start**. The analysis typically takes 5-15 minutes. You can leave the page - a progress card stays anchored in the bottom-right corner and you'll get notified when it finishes.
6. When it completes, head back to Oracle to see your discrepancy rate, open count, and the top items to address.
You don't need to configure anything else to get started - Oracle uses the AI responses Athena is already collecting for your site.
***
## Reviewing discrepancies
When Athena finds a mismatch between an AI response and your Pillars, it shows up as a **discrepancy**. The **Top high-impact discrepancies** section on the Oracle page is the recommended place to start - it surfaces the most critical, highest-confidence findings first.
Click any row (or **See all** for the full list) to open the Oracle Review Modal. For each discrepancy you'll see:
* **Two claims side-by-side** - what the AI said vs. what your Pillars say.
* **Why this was flagged** - a short explanation of the conflict, with clickable references to the AI response and any supporting sources.
* **Research verdict** (when available) - an extra AI pass that goes out to the web to determine which claim is correct, with cited sources.
You can then:
* **Approve** one claim as the correct version (keyboard: **1** or **2** to pick, then **Enter**).
* **Mark both as true** if the situation is genuinely nuanced (keyboard: **B**).
* **Skip** to look at the next one (keyboard: **>**).
Approving updates the underlying Pillar claim so future analyses use the corrected fact. Notes are optional.
***
## Verifying your facts against external sources
The **Verify facts** flow goes the other direction: instead of asking "what is the AI getting wrong," it asks "what websites and AI responses are out there contradicting *us*?" This is useful for spotting outdated facts in Wikipedia, in competitor blogs, or in AI responses that haven't picked up your latest information yet.
To run it:
1. Click **Run analysis > Verify facts**.
2. Select the Pillars you want to check (you can pick a few, or select all).
3. Click **Start**.
When it finishes, the **Validation** card on the Oracle page shows a ranked list of source domains by contradiction count. Click any row to see the specific contradictions for that domain and decide whether to update your Pillars or treat the external source as outdated.
A pinned **Knowledge Base** row at the top represents *internal* inconsistencies - places where two of your own Pillars contradict each other. This is where to clean up before sharing your Pillars more broadly.
***
## Drafting fixes
Oracle remediation drafts are reviewed from **Content > Content Hub**, not from a tab inside Oracle.
* Oracle-created drafts appear in Content Hub as in-progress rows labeled **Oracle**.
* Open a draft to preview the recommended content and see which discrepancies it addresses.
* From the preview, you can **Approve & publish** to make the draft available for editing and publishing, or **Dismiss** if it's not useful.
Approved drafts stay in **Content > Content Hub**, where you can edit, publish, or push them to your CMS through any connected integration (Webflow, WordPress, Shopify, etc.).
***
## Reading the Oracle page
The Oracle page is your at-a-glance dashboard:
* **Discrepancy rate** - share of analyzed AI responses with at least one claim that doesn't match your Pillars. Lower is better. A small trend line shows how it's moved across recent runs.
* **Open discrepancies** - total unresolved discrepancies, with a sub-label showing how many are high-impact.
* **Validation** card - appears once you've run a Verify facts analysis. Lists external source domains contradicting your facts.
* **Top high-impact discrepancies** - the five most critical unresolved items, shortcut-clickable into the review modal.
* **Coverage** - how complete your Pillars are relative to the topics AI is actually talking about. Shows total claims, claims AI has cited, uncovered claims (Pillar gaps), and trends over time. Two extra tabs under Coverage drill into specific gaps and unused content.
***
## How Oracle and Pillars work together
Oracle is the *audit* layer; Pillars are the *source of truth*. Every discrepancy Oracle finds is a comparison between an AI response and the claims in your Pillars, so:
* The more complete your Pillars, the more discrepancies Oracle can find.
* Approving a side of a discrepancy updates the underlying Pillar claim, so your source of truth stays current.
* Verify-facts runs use your Pillars as the input; the more authoritative they are, the more useful the validation report.
If you haven't set up Pillars yet, do that first. The [Knowledge Base / Pillars article](./knowledge-base) covers everything you need.
***
## Frequently asked questions
**Do I need Pillars set up before running Oracle?** You'll get more out of Oracle when your Pillars are populated, but you can still run a Check responses analysis without them - it just won't find as many discrepancies. We recommend running **Discover pillars** in the Pillars tab of Knowledge Base first.
**How often should I run an analysis?** For most customers, a weekly Check responses run on a rolling 7-day window is a good cadence. Verify facts can be run less frequently - once a month is plenty unless you're publishing rapidly.
**Why is my discrepancy rate going up?** That usually means AI models have started repeating new claims that aren't yet covered or corrected in your Pillars. Look at the top high-impact discrepancies - these are typically the source of the change. Approving the correct side of each will improve the rate on the next run.
**Can I undo a discrepancy resolution?** Yes. Pillar claim changes are reversible from the **Pillars** tab in Knowledge Base. Open the relevant pillar, find the claim, and edit it back.
**What does "high-impact" mean?** High-impact discrepancies combine three things: high severity (the claim is materially wrong, not just imprecise), high confidence (Athena is sure the claim is in the response), and high impact (the claim appears frequently or in influential responses). Start here.
**Where do approved drafts go?** Approved drafts are saved into your **Content > Content Hub** as drafts. From there you can edit them and publish via any connected CMS integration (Webflow, WordPress, Shopify, etc.).
**Why don't I see Fact Bank or Drafts in Oracle?** Fact Bank now lives in the **Pillars** tab of Knowledge Base, and Oracle-generated drafts are reviewed from **Content > Content Hub** as in-progress drafts. Oracle itself shows the analysis overview and review workflows. Reach out to your account manager if you want to upgrade to Oracle.
**Can I cancel a running analysis?** Yes. The progress card in the bottom-right of the page has a **Cancel** button. You can also dismiss the card to hide it - the run continues in the background and you'll be notified when it finishes.
# Setting Up Your Prompts
Source: https://docs.athenahq.ai/setting-up-prompts
Build a useful Athena prompt set with direct entry or the Discover tab
Prompts are the questions Athena runs against AI engines on your behalf. Your prompt set is the biggest single driver of useful data - a weak or narrow set means the platform is answering the wrong questions.
Athena gives you two ways to build your prompt set: add prompts directly, or run discovery from the Discover tab. This doc explains what each one is, when to use it, and how to work through it. They're not mutually exclusive - most teams start with one method and fill in gaps with another.
***
## Before you choose: what a good prompt looks like
Think buyer language, not internal language. A prompt is a question or query someone would type into ChatGPT, Perplexity, or Gemini when looking for something in your category.
Good prompts are:
* **Questions your buyers actually ask** - not how you describe your product, but how they describe their problem. "What's the best platform for tracking AI search visibility" beats "AthenaHQ competitors."
* **A mix of Branded and Non-Branded** - Branded prompts include your company or product name. Non-Branded prompts are generic category queries where you want to show up without being named. You need both.
* **Specific enough to return signal** - very broad prompts ("what is marketing") return noise. Specific ones ("what tools track brand mentions in AI responses") return the data you can act on.
Aim for 50-100 prompts to start. Enough to see patterns; focused enough to act on.
***
## Option 1 - Add Prompts directly
This is the quickest path for getting prompts into Athena. You open the Add Prompts drawer and choose how you want to add them: let Athena generate suggestions, type them in yourself, or upload a CSV.
**Access it from:** Prompts > **+ Add More** > **Add Prompts**
Once the drawer opens, you'll see three ways to add:
### AI generation
Athena generates a starting set of prompts for you based on your website, brand description, and industry. This is the fastest way to get something in place if you're starting from scratch and want Athena to do the thinking.
**Best for:** New customers who haven't done keyword research yet and want a reasonable starting point immediately. Good for filling coverage gaps when you know a topic area you're missing but aren't sure what the right prompts are.
### Manual entry
Type or paste prompts directly into the drawer. You set the type (Branded or Non-Branded), assign a topic, choose a country, and add tags before saving.
**Best for:** When you know exactly what you want to track. Common use cases: prompts you heard from customers, questions from sales calls, terms your team competes on, or specific product comparisons you want to monitor. This is also the right move when AI generation misses something obvious - just add it yourself.
### CSV import
Upload a formatted CSV to add prompts in bulk. Download the template from within the drawer, fill it out, and drag the file to upload.
If you attach locations to prompts, separate multiple locations with semicolons (`London; Manchester`). Commas are treated as part of the location name, so a full address like `Acme Autocentre, 12 Windsor Way, Aldershot, GU11 1JG` stays one location. In the Country column, list one country per location in the same order, also separated by semicolons.
**Best for:** Teams coming from an SEO tool with an existing keyword export, or any situation where you have a list of 20+ prompts you want to load in one go rather than one by one. Also useful for migrating prompt sets from another system, or when multiple stakeholders have contributed prompts to a shared spreadsheet.
**Tips for all three:**
* After adding, review the Topics Athena assigns - the defaults are a starting point, not final. Drag prompts between topics to get your structure right, since Topics are how you'll slice data in Olympus and the Heatmap.
* Once a prompt has collected response data, its text becomes read-only. You can't edit the wording - you'd need to pause it and create a new one. Get the phrasing right upfront.
***
## Option 2 - Discover
*Enterprise plan only. The Discover tab shows a lock icon if your workspace doesn't have access.*
Discover runs a multi-source discovery scan against your website and market, and produces a structured, filtered, ranked set of prompts ready for review. It's not just generating prompts - it's discovering them from real data sources and organizing them by funnel stage, intent, and volume so you can prioritize before you track.
**Access it from:** Prompts > **Discover** tab > **Run discovery**
When starting a run, you name it, choose a country and language, and check which sources to scan:
* **Website analysis** - market analysis from your website, segments, and products, deriving prompts from the structure of your business
* **Search Console** - clusters your Google Search Console keywords into prompts grounded in real search data *(requires GSC to be connected in Settings > Integrations)*
* **Social** - Reddit threads, YouTube comments, and videos in your category
* **Keyword gaps** - prompts where AI cites competitors but not you, built from your keyword landscape
* **Custom instructions** - guide discovery with your own topics, products, and tone (opt-in; requires a short written brief)
Once you click **Run discovery**, the sources run in the background - allow several minutes to an hour depending on what you selected. The run's detail page shows live progress, and suggestions appear as results come in (Keyword gaps results arrive independently of the other sources). When results are in, you get a table of discovered prompts grouped by Topic with columns for:
* **Source** - which source produced it
* **Funnel** - TOFU (awareness), MOFU (consideration), or BOFU (decision)
* **Intent** - Informational, Commercial, Transactional, or Navigational
* **Type** - Head, Mid tail, or Long tail
* **Volume** - estimated monthly search volume
* **Value** - estimated keyword value (CPC)
Signal chips (such as *Competitor Gap* and *Social Signal*) appear above the table when the run found prompts carrying those signals. An **Already tracked** section at the bottom lists suggestions you already cover (previously accepted suggestions, exact matches, and Keyword gaps prompts at 85%+ similarity) - so you're not adding redundant coverage.
Review the results, filter by source, funnel, intent, type, or top volume, sort by any column, select the prompts you want, and click **Start tracking (N)** - Athena checks for duplicates and shows you a count of new vs. already-tracked selections before confirming.
**Best for:** Teams starting from scratch who want data-grounded prompts rather than a manual brainstorm - and teams with a baseline set who want to expand strategically. Particularly strong when GSC is connected, since your actual search terms feed directly into discovery. The Keyword gaps source is the move when you suspect competitors are gaining AI visibility you're not monitoring.
**Tips:**
* Connect Google Search Console before running discovery. The Search Console source is the highest-signal input and appears disabled with a connect link if it's not connected.
* Use the Funnel filter to check you have coverage across TOFU, MOFU, and BOFU. Most teams over-index on bottom-funnel branded terms at the start.
* Social prompts surface the informal, conversational language your buyers actually use. These are often the prompts where you're most invisible in AI responses, because they're phrased the way people talk, not the way brands write.
* Topic names are renamable inline on the results page. If you rename two topics to the same name, Athena will prompt you to merge them.
* You can export the currently filtered view as a CSV before tracking - useful if you want a stakeholder to review before anything goes live.
* Re-run discovery periodically - every few months, or when you expand into a new product area - rather than just once at setup.
***
## Choosing the right option
| Your situation | Best option |
| :----------------------------------------------------------- | :---------------------------------- |
| You need something running quickly from scratch | Add Prompts > AI generation |
| You know exactly which prompts you want | Add Prompts > Manual entry |
| You have an existing keyword list or spreadsheet | Add Prompts > CSV import |
| You want data-grounded discovery with funnel/intent labeling | Discover |
| You have GSC connected and want keyword-backed prompts | Discover (Search Console source) |
| You want to find where competitors are winning | Discover (Keyword gaps source) |
| You want prompts from community discussions | Discover (Social source) |
| You're filling gaps in an existing prompt set | Discover |
| You're on Self-Serve (not Enterprise) | Add Prompts (all three sub-methods) |
These methods layer well together. A common starting pattern: use AI generation or CSV to get something tracking immediately, then run discovery to fill structural gaps and catch competitive exposure you didn't know to look for.
***
## After you add prompts: organizing and managing them
Once prompts are in, a little structure makes your data significantly more useful.
**Topics** are the main organizational unit. Prompts are grouped into Topics on the Manage tab. Think of Topics like content pillars or product areas - "Pricing," "Competitors," "Use Cases," and so on. A well-organized topic structure makes the Heatmap and Olympus filter bar much more powerful, since you can slice all your metrics by Topic to see exactly where you're winning or losing.
To move prompts between Topics, select them and use **More > Assign topic** in the bulk command bar, or drag them directly onto a different topic row.
**Branded vs. Non-Branded** is the other key label. Branded prompts include your company or product name. Non-Branded are generic category queries. Track both - Branded mention rate reflects direct awareness; Non-Branded reflects whether you're showing up when buyers haven't decided yet. You can set or edit this in the Edit Prompt drawer (click ... > Edit on any prompt row).
**Tags** let you create custom groupings across Topics - useful for things like campaign tracking, product lines, or funnel stage labels you want to apply manually. Manage the full tag library from **+ Add More > Add Tag**.
**Pausing prompts** is the right move for anything off-target - don't delete, since paused prompts keep their historical data. Select the rows and click **Pause** in the bulk command bar, or use the row-level ... menu.
**A note on editing prompt text:** once a prompt has collected response data, its text is locked. You can't edit the wording directly - the Edit Prompt drawer will have the text field disabled. If you need to change it, pause the prompt and create a new one with the corrected text. Plan your phrasing carefully upfront and you won't need to do this often.
***
## Questions?
Reach out to your Athena team or contact [support@athenahq.ai](mailto:support@athenahq.ai).
# Sources
Source: https://docs.athenahq.ai/sources
See which websites AI search engines cite across your tracked prompts
Sources answers one question: **when AI search engines write about your market, what websites do they read?**
When ChatGPT, Perplexity, Gemini, Claude, Copilot, Google AI Overview, AI Mode, Grok, or DeepSeek answer a tracked prompt, they almost always cite one or more web pages as evidence. Sources collects every one of those citations across every prompt you track, rolls them up by website (and by individual URL), and shows you which pages are influencing AI's answers about your brand, your competitors, and your category.
It's one of the highest-leverage pages in Athena, because the sites that show up here are the sites you need to be present on. Yet many customers underuse it - they look at Olympus and stop. Sources is where you turn AI visibility insights into concrete content, outreach, and SEO actions.
You'll find Sources in the left sidebar.
***
## Why Sources matters
Three concrete things you can do with Sources that you can't do anywhere else in Athena:
1. **Find where to publish or pitch.** The third-party sites that show up at the top of your Sources list (Reddit threads, Forbes articles, Wikipedia pages, niche industry blogs, YouTube videos) are the sites AI is already trusting to answer questions about your market. Getting your brand mentioned in those places is one of the most direct ways to influence AI answers.
2. **Spot content gaps.** If a domain drives a lot of competitor citations but rarely cites you, that's a measurable, named gap to close - either by getting your own content mentioned there, or by publishing better content on a similar topic on your own site.
3. **Audit your own performance as a source.** Switch the source type to Owned for your domain and you can see exactly which of *your* pages are being cited by AI, how often, and alongside which competitors. This is the closest thing Athena has to a direct AI-SEO performance report for your own content.
***
## What you can do here
### Two ways to look at the data
A toggle at the top of the page switches between:
* **Domain view** - one row per website (e.g. `reddit.com`, `forbes.com`, `yourcompany.com`). Best for spotting which sites matter most.
* **Page view** - one row per individual URL. Best for drilling into exactly which articles, threads, or videos are doing the work.
A second toggle splits the table into:
* **All** - every domain or URL.
* **Social** - social platforms only (YouTube, Reddit, X, LinkedIn, Facebook, TikTok, Quora, Substack, etc.). When you're on the Social tab, platform chips appear so you can narrow to one platform at a time.
### Reading the columns
The main columns work the same way in both views:
* **Citation %** - the share of AI responses (under your current filters) that include at least one citation to this domain or URL. Higher = more influential.
* **Responses Influenced** - the raw count of distinct AI responses that cited this source.
* **Brand Mention %** - of the responses that cite this source, how often your brand is also mentioned in the answer.
* **Competitor Mention %** - of the responses that cite this source, how often a tracked competitor is also mentioned.
* **Trend** - a small sparkline showing how citation share has moved across your selected date range.
* **Type** - the source-type tag (Owned / Competitor / Partner / Third-party). Color-coded throughout the product.
* **Impressions Captured** - estimated total AI impressions delivered through citations to this source.
Page view also shows **Mentions** (the same as Brand Mention but per URL), a stack of **Competitor logos** for tracked competitors co-mentioned alongside the URL, and an optional **First Seen** column (turn it on via the Columns menu) showing when the URL first appeared in an AI response.
### Drilling into a source
Click any row to open a drawer with deeper analytics for that domain or URL:
* **Citation Rate Over Time** - a line chart of citation share over your selected date range.
* **URL Breakdown** - every URL on the domain that's been cited, with the same columns.
* **Prompt Breakdown** - which of your tracked prompts produced these citations.
* **Creator Breakdown** and **Timestamp Insights** - extra tabs that appear only for YouTube, surfacing video creators and the specific timestamps AI cites.
From the URL drawer you can navigate up the URL stack (click the domain or path segments in the header) and export the breakdown to CSV.
### Filtering and saved views
Above the table is a filter row with date range, models, prompts, competitors, personas, locations, prompt tags, prompt status, source type, "mentioned," and a free-text search box. Any combination can be saved as a **Saved View** for one-click recall later. Saved views persist per website.
If no date range is set, Sources defaults to the **last 7 days**.
### Tagging sources
Every domain and URL is automatically classified as Owned, Competitor, Partner, or Third-party based on your website, your tracked competitors, and a default list. If something is misclassified - or if you want to flag a partner site or industry publication as something more specific - you can override it:
* **Single row:** click the ... menu on any row and choose **Edit Source Type**.
* **Multiple rows (Page view only):** check the rows you want, then use **Assign Type** in the bulk command bar that appears at the bottom of the screen.
Re-tagging updates the badge immediately and flows through to filtering and reporting.
### Rescanning brand and competitor mentions
For each URL that AI cites, Athena scans the page to see whether your brand and tracked competitors are mentioned in the surrounding content. This is what powers the **Brand Mention %** and **Competitor Mention %** columns.
You can refresh that data:
* **One URL at a time:** click the rescan icon on the row (Page view only).
* **In bulk:** click the **Rescan** column header in Page view to open the bulk rescan dialog. Pick a scope (Never scanned, Not mentioned, No competitors, or All), choose how many URLs to scan (up to 10,000 per run), and start the job. Each batch consumes about **1 credit per 10 URLs scanned**, and the dialog shows you both the cost and your remaining balance before you confirm.
### Exporting
Click the **Download** icon at the top right of the table to open the **Export Sources** dialog. You can export 1,000 / 5,000 / All rows, or any custom count. The CSV downloads automatically. Each drawer also has its own download button for exporting the URL breakdown for a single domain.
## Suggested workflows
**Find the top sites AI cites about your market**
1. Open Sources (Domain view, All tab).
2. Sort by Citation % descending.
3. Skim the top 10-20 domains. Note which are owned, competitor, or third-party.
4. Click the most influential third-party domain to see which prompts it's appearing on.
**Find content gaps (sites that talk about competitors but not you)**
1. Open Sources in Domain view.
2. Sort by **Competitor Mention %** descending.
3. Look for rows where **Brand Mention %** is low. Those are the highest-leverage domains to target.
**Audit your own AI-SEO performance**
1. Filter Source Type to **Owned**.
2. Switch to Page view.
3. Sort by Responses Influenced.
4. These are your top AI-SEO performers - the pages on your site that AI is actually citing.
**Plan social outreach**
1. Click the **Social** tab.
2. Pick a platform chip (Reddit, YouTube, etc.).
3. Sort by Responses Influenced. The top rows are the specific threads and videos AI relies on most for your market.
4. Click a row to read the underlying AI responses and decide where to engage.
**Re-tag a partner or industry site**
1. Switch to Domain view.
2. Search for the domain.
3. Use the row's ... menu > **Edit Source Type** > choose Partner.
4. Reporting and color-coding update everywhere immediately.
***
## Frequently asked questions
**Where does the citation data come from?** Athena runs every prompt you track against the major AI search engines (ChatGPT, Perplexity, Gemini, Claude, Copilot, Google AI Overview, AI Mode, Grok, and DeepSeek), captures their responses, and extracts every domain and URL each response cites. Sources is built entirely from that data - no third-party SEO tool is feeding it.
**What does "Citation %" actually count?** It's the share of all AI responses captured under your current filters that include at least one citation to this domain (or URL, in Page view).
**Why is a YouTube URL stripping the `?v=...` part on other sites but keeping it on YouTube?** For most domains, Athena normalizes URLs by stripping query parameters so duplicates collapse into one row. For social platforms (especially YouTube `/watch` and `/shorts` URLs), the query parameters are preserved so each video tracks separately.
**How do I see when a URL was first cited?** Switch to Page view, click **Columns**, and turn on **First Seen**. It's hidden by default.
**Why don't I see the Domain / Page or All / Social toggles?** They're hidden on narrow screens (mobile or very small browser windows). Widen the window or use a desktop browser.
**I re-tagged a domain but other pages still show the old type. What happened?** The badge updates immediately in Sources. Other reports run on a server-side recompute and may take a moment to reflect the change. If it still looks wrong after a full reload, contact support.
**Why is the bulk Rescan button disabled?** Either another bulk rescan is already in progress for this website, or you don't have enough credits. The dialog shows the credits needed (about 1 per 10 URLs) and your remaining balance.
**Can I export the full list?** Yes - click the Download icon at the top right of the table and choose **All** in the Export Sources dialog. Drawers also have their own per-domain export.
**Do saved views sync across users?** Saved views are saved per website, so any user with access to that website's Sources page can load them. Sort order, column widths, and column order are stored in your browser's local storage and stay on the device you set them on.
**Why is the same source listed twice with a slightly different URL?** The page treats every distinct URL Athena has captured as its own row. Common reasons for near-duplicates: trailing slashes, anchors (`#section`), or social-platform query parameters that are intentionally preserved. Use the **Clear URL Param** action inside the URL drawer to roll a suffixed URL back to its base.