# 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 active website in your API key's organization and streaming schedule. Website-scoped keys must also include the website in their allowlist. Deleted websites return HTTP 403 even if their IDs remain in the key's allowlist. 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. # 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. > [card] [Manage API Keys](https://app.athenahq.ai/organization?tab=api) > > 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 * **Website creation** — `POST /api/v1/websites` and `POST /api/v1/websites/provision` * **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. > [!WARNING] > > 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. Requires a global API key; website-scoped keys return HTTP 403 before any resources are created. 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. A successful creation also provisions the website's Default prompt schedule in the same transaction. Tracking patterns preserve the submitted host, path case, and query parameters. An apex such as acme.com includes www.acme.com; an explicit www.acme.com tracks only that host. Paths include the named section and descendants on slash boundaries. Domain matching is case-insensitive; path and query values are case-sensitive. # 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 the competitors tracked for a website. With `include_discovered=true`, also returns `discovered_competitors`: brands Athena found in the website's AI responses that the website does not track. # 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 Identifiers Source: https://docs.athenahq.ai/api-reference/basics/get-identifiers /api-reference/openapi.json get /api/v1/identifiers Returns the identifiers of a website's own brand, or of one of its competitors when you pass `competitor_id`: the names, aliases and domains Athena looks for in AI responses to count a mention. `default_identifiers` holds the name and domain, which are always matched. `identifiers` holds every other value the Competitors page shows, so the two lists together are the full set. `case_sensitive` tells whether matching respects letter case. `entity` says what the identifiers belong to, with `type` set to `brand` or `competitor`. # 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. `saved_response_progress` separately counts distinct saved responses against the original request, with an immutable first-terminal-outcome snapshot. 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 Activity Source: https://docs.athenahq.ai/api-reference/basics/list-activity /api-reference/openapi.json get /api/v1/activity Returns the changes made to prompts, topics and prompt tags across your organization, newest first by default. Each entry names the website, the entity type, the kind of change (`created`, `updated`, `deleted`, `restored`, `paused`, `unpaused`), the affected entity ids and who made the change. Use it to find out what happened without re-listing every website. `entity_ids` is `null` when the affected set is not known (for example a bulk import); re-list that website's prompts with `GET /api/v1/prompts`. A `topic` or `prompt_tag` entry means the `topic_name` or `tags` of that website's prompts may have changed, so re-list the website in that case too. Changes made with an API key carry the key's id and name in `actor`, so you can skip your own writes. Changes made in the app carry the person's id and email in `actor.user`. Keys scoped to specific websites see the identity of members of those websites only; other people appear with `user: null`. Websites provisioned through `POST /api/v1/websites/provision` do not appear here; list a website once after provisioning it. To mirror data, pin a window per sync run: set `since` to the previous run's `until`, set `until` to now minus one minute, pass `order=asc`, walk `page_num` until `pagination.has_more` is `false`, then store that `until` for the next run. `since` is exclusive and `until` inclusive, so consecutive windows neither overlap nor skip. With no `since` the walk covers the whole history, so `order=asc` with no bounds is a full export. Pagination uses `page_size + 1` lookahead: there is no total-count field. Requires a partner API key. Keys scoped to specific websites see only those websites. # List API Keys Source: https://docs.athenahq.ai/api-reference/basics/list-api-keys /api-reference/openapi.json get /api/v1/api-keys Lists API key metadata for the authenticated key's organization, including each key's creator (ID, current name and email), creation date, scope and revocation status. Requires a global API key; website-scoped keys receive 403. No organization ID is accepted. Secrets and hashes are never returned. Revoked keys are included so you can detect a key created and revoked between polls. Results are ordered by creation date ascending, then ID ascending. For new-key alerts, first record a baseline of key IDs. On each poll, pin `until` to now minus one minute, overlap `since` with the previous successful window, and keep both bounds fixed while incrementing `page_num` until `pagination.has_more` is false. Both time bounds are inclusive. Deduplicate alerts by key ID and advance your saved window only after all pages succeed. Filter `is_revoked` locally if you need active keys only. This is a current inventory, not a durable audit log or webhook: deleting a creator's account removes their keys, and concurrent deletions can shift pages. Overlapping windows reduce polling gaps but cannot guarantee detection of every creation. The MCP tool `list_api_keys` exposes the same fields and filters to global API keys and organization-admin OAuth connections, subject to MCP permissions. # 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. Filters take one schedule; the metrics endpoints combine the schedules of a saved view stored with several schedules. # 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. A successful creation also provisions the website's Default prompt schedule in the same transaction. > **Beta**: This endpoint is in beta. The request and response schemas may change. Website and competitor tracking patterns preserve the submitted host, path case, and query constraints. Apex domains include their www form; explicit www hosts remain distinct. Paths match sections on slash boundaries. # 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 Run tracked prompts against external AI providers to collect new responses for a website. Sends prompt text to the selected providers, stores their responses in AthenaHQ, and consumes response credits. Starts immediately; use only for a user-requested run. Returns a workflow_id; 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. # 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. ## November 2026 ### Fixed: `cited` on answers in `query_metrics` and `query_rows` In the MCP tools `query_metrics` and `query_rows`, the `cited` field of the `responses` dataset was `false` on every answer, so a per-prompt count of cited answers came back 0 even for prompts whose citation-rate series showed citations. `cited` is now `true` when the answer cites at least one of the website's own pages: the same answers `get_citation_rate_time_series` counts as cited, and the ones the `citations` dataset returns with `is_website: true`. Filters and counts on `cited` return those answers. Field names, types and status codes are unchanged. ### Fixed: invalid partner write requests return HTTP 400 Invite and group creation, the affected partner credit and add-on pricing writes, and website subscription cancellation now return HTTP 400 with `Invalid JSON body` for malformed or empty JSON. Billing writes also validate website and group UUIDs before using them, and credit and pricing writes reject JSON `null` bodies. These invalid requests previously returned HTTP 500. Valid requests, authentication, and partner access requirements are unchanged. ### Fixed: website creation requires a global API key `POST /api/v1/websites` now requires a global API key, matching website provisioning. Website-scoped keys receive HTTP 403 with `Forbidden: global API key required` before any website, tracking schedule, partner mapping or billing entity is created. Global-key request fields and response shapes are unchanged. ### Fixed: scoped keys cannot read reports or change members on deleted websites Website-scoped keys now receive HTTP 403 when they request Looker Studio reports, credit usage or subscription information for a deleted website, cancel its subscription, or list or change its members. An entry remaining in a key's website allowlist no longer grants access after deletion or an organization move. Active websites remain accessible within the key's scope; member changes still require the key's creator to be an Admin of the website. Website deletion, restoration and partner external-ID cleanup retain their existing behavior. Creating website invitations through `POST /api/v1/invites` or `POST /api/v1/invites/bulk`, and revoking them through `DELETE /api/v1/invites/website/{invite_id}`, also require active websites. Deleted websites use these routes' existing HTTP 404 responses. A bulk request containing a deleted website is refused before any invitations or memberships are created. ### Fixed: organization member removal revokes Market Landscape access `DELETE /api/v1/organizations/members/{user_id}` now removes the user's direct Market Landscape memberships issued by your organization and revokes their pending landscape invitations in the same transaction as organization removal. Access issued by other organizations is preserved. The request, response, and status codes are unchanged. ### Added: discovered competitors on Get Competitors **[GET /api/v1/competitors](/api-reference/basics/get-competitors)** accepts a new optional query parameter, `include_discovered`. When it is `true`, the response adds `discovered_competitors`: brands Athena found in the website's AI responses, as the Competitors page lists them on its Discovered competitors tab (up to 6), without the ones the website already tracks by name or domain. Each entry has `name`, `domain` (best-effort, `null` when unknown), `mention_count`, `response_count`, `mention_rate` (0-100, the share of the responses Athena analyzed for discovery that mention the brand, not the date-range mention rate of the metrics endpoints), `first_seen_at` and `last_seen_at`. A discovered competitor has no ID and cannot be used in `competitor_ids` filters or the metrics endpoints until the website tracks it. Without the parameter the response is unchanged. The MCP tool `get_competitors` is unchanged. ### Fixed: SCIM deprovisioning persists SCIM removal now persists across later sign-ins. To restore organization access, send a new organization invitation after removal and add the user directly or have them accept it. Website and group invitations grant their requested scope without restoring automatic organization joins. ### Added: filter sources by source tag, including Other and No tag **[POST /api/v1/sources](/api-reference/sources/list-sources-by-root-domain)** and **[POST /api/v1/source-pages](/api-reference/sources/list-source-pages-per-url)**, also the MCP tools `get_sources` and `get_source_pages`, accept two optional fields that match the Source Tag filter in the app. `source_tags` takes tag IDs from `source_tags__list` (built-in tags such as Media or PR Wire, and your custom tags), `owned`, `competitor`, `other` (sources classified outside every built-in category, which the Tags column badges Other) and `untagged` (sources with no tag). `source_tags_operator` is `is_any_of` (the default), `is_not_any_of` or `has_all_of`. Any other value returns 400. Built-in tags now resolve the same way they do in the app, so `source_type_ids` in each row can also list the built-in tags a source carries. Omitting both fields returns every source, as before; existing fields and status codes are unchanged. ### Added: create a brand kit over MCP `create_brand_kit` creates a brand kit from text you provide: a `name` unique on the website, `guidance` entries per field, `voice_settings` as 1 to 5 or `"auto"`, and `rules`; nothing is generated. The kit starts as a draft, `publish: true` publishes it as version 1, and the website's first kit becomes its default; the result carries the same `outcome` as `update_brand_kit`. A name another kit uses or a rule that contradicts a global rule is refused and no kit is created. Needs a paid plan and, for rules, the writing rules feature; sits in the Brand knowledge permission section, needs the Brand knowledge write permission on signed-in connections, and is audit-logged. There is no REST endpoint. Existing tools and response shapes are unchanged. ### Added: global writing rules over MCP `update_global_rules` adds, updates by id, or removes by id the website's global writing rules, the ones the Global rules tab holds and every brand kit and every future piece of content follows; the ids come from `get_brand_kit`'s `global_rules`. There is no draft: the change is live as soon as it is saved, as a new version the Global rules tab's change history can restore. A rule that contradicts an existing global or kit rule is refused with the reason and nothing is saved. Needs the writing rules feature, sits in the Brand knowledge permission section, needs the Brand knowledge write permission on signed-in connections, and is audit-logged. There is no REST endpoint. Existing tools and response shapes are unchanged. ### Added: read and update brand kits over MCP `get_brand_kit` returns a brand kit as the Brand Profile editor shows it: the draft name, the eight guidance fields as text (`voice` is the writing direction), voice settings as 1 to 5 or `"auto"`, tone traits, the kit's writing rules and the website's global rules with their ids, and the draft and published versions. Omit `kit_id` for the default kit; `available_kits` lists every kit. Long fields come back clipped and listed in `truncated_fields`; pass `fields` to read them whole. `update_brand_kit` changes one kit's `name`, `guidance` (a whole field, or one passage through `find`), `voice_settings` and `rules` (`add`, `update` by id, `remove` by id) in the kit's draft, and publishes it as a new version when `publish` is true; `outcome` reports `saved`, `saved_and_published` or `saved_publish_failed` with `publish_error`. Both tools follow the Brand Profile page's rules: a paid plan, the writing rules feature for rules, a refusal with the reason for a rule that contradicts another, and nothing saved on a refusal. They sit in the Brand knowledge permission section; the update needs the Brand knowledge write permission on signed-in connections and is audit-logged. There is no REST endpoint. Existing tools and response shapes are unchanged. ### Changed: Citation rate entries include relative citation rate Both citation rate endpoints now return a `relative_citation_rate` field for every brand/competitor entry: the entity's cited responses as a percentage (0-100) of responses that cite your brand or at least one tracked competitor. Responses that cite none of them, including responses that came back without sources, are left out of that denominator. This is the same "Relative" rate the dashboard's citation rate card shows. The existing `citation_rate` field stays absolute (share of all responses), and all existing fields are unchanged. Affects **[POST /api/v1/metrics/citation-rate/cumulative](/api-reference/metrics/cumulative-citation-rate)** (per entry, across the date range) and **[POST /api/v1/metrics/citation-rate/time-series](/api-reference/metrics/citation-rate-over-time)** (per entry, per day). Also returned by the MCP tools `get_citation_rate_cumulative` and `get_citation_rate_time_series`. ### Added: TikTok creators and cited pages through API and MCP `POST /api/v1/sources/tiktok-creators` and `POST /api/v1/sources/tiktok-pages`, also available as `get_tiktok_creators` and `get_tiktok_pages`, expose TikTok citation breakdowns for your website. Creators are grouped by lowercase handles from cited profile, video and photo URLs. Short links and unsupported creator paths stay in an explicit `unattributed` group. Use `channel_key` to list a creator's cited pages, with zero-based pagination of up to 100 rows per page. Shares and totals use all filtered TikTok citations, including unattributed URLs, even when you drill into one channel. These are AI-answer citation counts, not TikTok views or engagement. No scraping or live TikTok lookup occurs; ownership and account renames are not verified. Results are cached for up to five minutes. Both tools use the Analytics MCP permission section and existing website access and provider-data restrictions. ### Added: YouTube citation data over API and MCP `POST /api/v1/sources/youtube-creators` and `get_youtube_creators` return cited channels, citation shares, category and length breakdowns, and metadata availability. `POST /api/v1/sources/youtube-videos` and `get_youtube_videos` return paginated videos with saved titles, channel details, citation counts, response percentages and linked timestamps. Use `channel_key` to drill into a creator or `video_id` to select one video. Both reads require website access and support inclusive UTC date ranges, model and prompt filters. These are citations in AI answers, not YouTube view counts. Missing metadata stays null; reads do not request live YouTube data. ### Added: the source page of an optimization on content detail `GET /api/v1/content/{content_id}` and the MCP tool `get_content_detail` now return `source_url`: for an `optimize` item, the live page it is based on, available as soon as the item exists. `url` still stays `null` until `POST /api/v1/content/{content_id}/publish` records the published page and marks the item `done`, so an integration can link a request in review to its page without publishing it. Reading `source_url` changes nothing: the item keeps its `status`, and its citation attribution still starts at publish. `source_url` is `null` for other content types and for optimizations based on pasted text or a file, and running an optimization again on another page or a file updates it. Existing fields and status codes are unchanged, and `GET /api/v1/content/items` and `list_content` don't carry the new field. If your MCP client cached tool definitions or approvals, refresh the tool list and re-approve `get_content_detail` when prompted. ### Added: read brand and competitor identifiers over REST `GET /api/v1/identifiers` returns the names, aliases and domains that count as a mention of your brand, or of one competitor when you pass `competitor_id`. It is the read the MCP tool `get_identifiers` already does, with the same fields: `default_identifiers`, the name and domain that are always matched; `identifiers`, every other value; `case_sensitive`; and `entity`, which says what the identifiers belong to. It respects API-key website scopes. Editing stays on MCP through `update_identifiers`. Existing endpoints, tools and response shapes are unchanged. ### Added: Site Health over MCP and the partner API Nine Site Health tools join the MCP connector under a new `site_health` permission section, and three of them also ship as REST endpoints. `get_site_health_issues` (`POST /api/v1/seo/issues`) lists a website's issues grouped by check with severity, priority, owner, effort, per-status page counts and sample affected pages; `get_site_health_issue_pages` (`POST /api/v1/seo/issues/pages`) pages through every page one issue affects, 50 at a time; `get_site_health_analytics` (`GET /api/v1/seo/analytics`) returns the live Google Analytics 4, Search Console and AI-citation figures for the last 28 days beside the 28 before. MCP only: `get_site_health_properties`, `get_site_health_pages` and `get_site_health_page` read the crawl scopes, a property's audited pages and one page's measurements and findings; `update_site_health_task` and `update_site_health_issue` set the status or assignee of one finding or of a whole issue; `start_site_health_audit` runs a full, sample or per-page audit. Over MCP, a call returns at most 25 issues and each carries at most 10 sample pages; the REST endpoint carries up to 200 issues of 50. Every tool needs Site Health on the website's plan and returns HTTP 403 otherwise. The two task writes need a signed-in connection, since an API key has no teammate to act as; the audit start works with API keys. Writes follow the Analytics write permission on signed-in connections and are audit-logged. Existing endpoints, tools and response shapes are unchanged. ## October 2026 ### Added: Copilot and Perplexity shopping model filters `POST /api/v1/metrics/shopping` and the MCP tool `get_shopping_metrics` now accept `copilot` and `perplexity` in `filters.models`, alongside `chatgpt`, `ai_mode` and `gemini`. Shopping Insights also exposes both models in its Models filter and saved views. Copilot product cards are captured on new responses; this change does not backfill past responses. Existing request fields, response shapes and status codes are unchanged. ### Added: add and remove competitors over MCP `add_competitors` tracks 1 to 25 new competitors on a website per call, each with a name and its website URL (or `no_website: true`), and optional identifiers and extra domains. `remove_competitors` stops tracking 1 to 25 competitors by the IDs `get_competitors` returns. Both follow the Competitors page's rules, including the own-domain check and the limit of 500 competitors per website, and return a result per competitor: `added`, `already_tracked` or `rejected` with a reason, and `removed`, `no_change` or `not_found`. Removal is a soft delete the Competitors page can undo. Neither tool reanalyzes past responses or spends credits; the backfill stays on the Competitors page. Both need the Competitors write permission on signed-in connections and respect API-key website scopes. There is no REST endpoint. ### Added: organization API key inventory `GET /api/v1/api-keys` and the MCP tool `list_api_keys` list key metadata with creator, creation date, scope and revocation status. REST requires a global API key; MCP also supports organization-admin OAuth connections, subject to MCP permissions. Secrets and hashes are never returned. Revoked keys are included to help detect keys created and revoked between polls. Use inclusive `since`/`until` filters and `page_num`/`page_size` pagination, overlap polling windows and deduplicate alerts by key ID. This is an inventory, not a durable event log: deleting a creator account removes its keys. ### Changed: website-scoped keys manage members only for websites their creator administers A website-scoped API key can now change a website's members and invites only while the person who created the key is an Admin of that website: an organization owner or Admin, a website Admin, or an Admin of a group assigned to the website. This applies to `PATCH` and `DELETE /api/v1/websites/{website_id}/members/{user_id}`, website invites through `POST /api/v1/invites` and `POST /api/v1/invites/bulk`, and `DELETE /api/v1/invites/website/{invite_id}`. Otherwise these endpoints return HTTP 403 and change nothing. Global API keys, request fields and response shapes are unchanged. ### Changed: MCP query tools state each cube's limits and serve an over-max limit The `from` input of the MCP `query_metrics` and `query_rows` tools now describes each cube: its fields, the fields it can be grouped by, its maximum `limit`, and the order `orderBy` must follow. A `limit` above a cube's maximum no longer fails the call. The query runs at the maximum, and the result carries a `notice` that says so. For example, `limit: 20000` on `responses` returns at most 100 rows. A query the cube rejects, such as a field it doesn't have or a group-by it doesn't allow, now returns the same 400 error followed by that cube's description. Tool names, input fields, result fields and the other status codes are unchanged. ### Fixed: brand fact search returns only Knowledge Base facts `GET /api/v1/knowledge-base/facts/search` and the MCP tool `search_brand_facts` could return facts generated by Oracle analysis, which the Knowledge Base page and `get_brand_facts` exclude by default. They now return only approved facts the Knowledge Base shows. Request fields and response shapes are unchanged; some searches return fewer facts. ### Added: Competitive landscape discovery source `start_prompt_discovery` accepts a new source, `competitive_landscape`. It searches Google for the market around the competitors tracked on the website and suggests category questions, comparisons between your brand and a tracked competitor, and questions about tracked competitors. It needs at least one tracked competitor, otherwise the tool returns a validation error, and it follows the same plan restrictions as `keyword_gaps`. `get_prompt_discovery_runs` reports it like any other source. Existing sources, fields and statuses are unchanged, and there is no REST endpoint. ### Fixed: source pages apply `has_all_of` prompt tags `POST /api/v1/source-pages` and the MCP tool `get_source_pages` used to treat `filters.prompt_tags_operator` `has_all_of` as `is_any_of`, returning pages cited for prompts that carry any listed tag. They now return only pages cited in responses to prompts that carry every listed tag, and `citation_percentage` and `estimated_impressions` are computed over those same prompts. A prompt tag that does not belong to the website returns HTTP 403, as prompt, competitor and location ids already do. An unrecognized `prompt_tags` entry returns HTTP 400, as does `has_all_of` with two or more different `type:` entries, whether or not `filters.prompt_type` is set. `filters.persona_ids`, `filters.prompt_tags` and `filters.prompt_tags_operator` are now listed in this endpoint's request schema. Request fields and response shapes are unchanged. ### Added: `find_more_prompt_discovery` MCP tool `find_more_prompt_discovery` starts the next round of a finished Discover study, given the study's `website_id` and the `run_id` of the study or of any finished round that continues it. The round repeats the study's sources, country, language, prompt-count target and custom instructions, skips every question earlier rounds suggested, and reads evidence they did not use, so its prompts add to the same study. It returns the round's `run_id` and `version`, which `get_prompt_discovery_runs` polls as for a new study. A study takes one round at a time and at most two after the first run, and ends early after a round that found fewer than ten new prompts or nothing new to read; the tool then returns an error with the reason. A round ended for that last reason reports `reason_code` `sources_exhausted`. It requires prompt-management permission and the study's source entitlements. `get_prompt_discovery_runs` lists a continued study as one run, accepts the `run_id` of any of its rounds, and adds `rounds`, `can_find_more` and `find_more_reason`; its other fields are unchanged. There is no REST endpoint. ### Added: Outreach over MCP `list_outreach_contacts`, `find_outreach_author`, `draft_outreach_message`, `update_outreach_contact` and `set_outreach_status` let an assistant work the Outreach pipeline: read saved contacts, find a cited page's author and email, draft a pitch with the website's team-wide custom instructions, edit a contact, and move pages between statuses. Each email reports its source when known (`page_author`, `page_contact`, `hunter` or `manual`; `null` for emails saved before sources were recorded) and up to five other addresses the page publishes. Finding an author and drafting cost the same credits as on the Outreach page. Writes need Content write permission and are audit-logged. No REST endpoints are added. ### Fixed: MCP OAuth prompts for protected tool calls Unauthenticated account-tool calls on `/api/mcp` and `/api/mcp/claude` now return HTTP 401 with a `WWW-Authenticate` OAuth challenge. Previously, the challenge appeared only inside an HTTP 200 tool result, so clients such as Devin did not prompt you to sign in. The tool-level challenge remains in the response body. Initialization, tool discovery, public crawler tools, and authenticated calls retain their existing behavior. ### Fixed: tracked content applies persona and tag filters, and lists view tabs `POST /api/v1/content` and the MCP tool `get_tracked_content` used to ignore `filters.persona_ids`, `filters.prompt_tags` and `filters.prompt_tags_operator`, returning metrics for every response. These filters now narrow `total_responses`, `citations`, `citation_percent` and `estimated_impressions`; every tracked page is still listed. A `sheet_id` of a `view` tab, such as the default tab, used to return no content; it now lists the shared main pool (content not filed in any sheet), without the view's saved filters. A persona or prompt tag that does not belong to the website returns HTTP 403, as prompt, competitor and location ids already do. An unrecognized `prompt_tags` entry returns HTTP 400, as does `has_all_of` with two or more different `type:` entries when `filters.prompt_type` is not set. The three filters are now listed in this endpoint's request schema. Request fields and response shapes are unchanged. ### Updated: regional account domain restrictions New accounts are restricted for email domains associated with Cuba, Iran, North Korea, Russia, and Belarus, including their internationalized country domains. Within Ukraine, only the regional domains for Crimea (including Sevastopol), Donetsk, and Luhansk are restricted; general `.ua` domains are allowed. Direct invites keep their existing error responses: HTTP 400 for a single invite and HTTP 201 with per-target failures for bulk invites. ### Fixed: provisioned prompts without a topic stay uncategorized `POST /api/v1/websites/provision` used to create a topic named `Uncategorized` for prompts sent without a `topic` and put them in it. Those prompts, and prompts sent with a blank `topic`, now have no topic, the same as prompts added in the app, and are shown as Uncategorized. A topic named explicitly, including `Uncategorized`, is still created as sent. Existing `Uncategorized` topics were removed and their prompts left without a topic. Request fields, response shapes and status codes are unchanged. ### Fixed: direct invites enforce account domain restrictions Direct invites through `POST /api/v1/invites` and `POST /api/v1/invites/bulk` cannot create new accounts for email domains ending in `.ua`, `.ir`, `.ru`, or `.cu`. Single invites return HTTP 400 with an `error`; bulk invites keep HTTP 201 and report a failure for each target in `results`. Existing accounts can still be invited and sign in. ### Updated: facts similar to existing ones are listed for review instead of skipped `POST /api/v1/knowledge-base/facts` used to report a fact as `duplicate` and add nothing when the Knowledge Base already held a similar fact, even one nobody had reviewed. The outcome is still `duplicate` with a null `fact_id`, and now also lists the similar facts under `matches` (text, status, source, whether the source is on your own domains, pillar and date); the response carries a `match_token`. To resolve them, call again with the same facts, the `match_token`, a `decisions` entry for every listed match (`approve`, optionally with new `text`, or `delete`; an approval or new wording follows the same approval rules as a new fact, so a third-party source or a competitive claim stays pending) and `save_submitted` (true adds your facts as written, false only applies the decisions). Decisions that do not answer exactly the listed matches return 400; a listed fact that changed in the meantime returns 409, and nothing is written. The second response adds `resolved` with the approved, still-pending and removed fact ids. Facts with no similar facts are added on the first call as before. Existing fields and status codes are unchanged. The MCP tool `add_brand_facts` behaves the same way. ### Changed: which source URLs auto-approve added facts A fact added through `add_brand_facts` or `POST /api/v1/knowledge-base/facts` with a `source_url` now auto-approves only when the URL is on one of the website's domains: its URL patterns (the brand's Domains on the Competitors page) plus pages and domains marked Owned on the Sources page. Before, any page on the website's registrable domain counted. `example.com` covers `example.com` and `www.example.com` only; add `help.example.com`, or `*.example.com` for every subdomain. A `source_url` on an uncovered subdomain now comes back `pending`, and one on another of your domains or on a page marked Owned can now come back `approved`. Facts without a `source_url` are unchanged. Request fields, response shapes and status codes are unchanged. ### Updated: why a discovery run ended Each run returned by `get_prompt_discovery_runs` now includes `reason_code` and `reason`. `reason_code` is the terminal reason of a completed run, such as `requested_minimum_not_met` or `coverage_saturated`, or the error code of a failed one, such as `website_evidence_failed`. `reason` is the sentence the Discover page shows for a failed, empty or short run, safe to repeat to the user. Both are `null` while a run is in progress and when there is nothing to explain. Existing fields and statuses are unchanged, and there is no REST endpoint. ### Updated: clearer content-generation and prompt-run guidance The MCP titles for `create_content` and `start_response_streaming` now describe their results: “Generate an article or content brief” and “Run prompts and collect AI responses.” Input descriptions explain mode requirements, brief approval, and prompt selection. The MCP schema converter now preserves descriptions on optional and array fields. `publish_content` leads with recording an already-published article's URL for tracking. Tool identifiers, defaults, validation, and REST contracts are unchanged. ### Updated: saved-response count snapshots `GET /api/v1/response-streaming/status` now reports the observation times of saved-response counts in `saved_response_progress.completed_count_observed_at` and `initial_completed_count_observed_at`. Treat a count with no observation time as unknown. Counts refresh in bounded background batches and may remain stale during an outage; polling status does not trigger recounts. The initial count preserves the last observed snapshot at first finalization, which can precede the finalization time. Current counts include retained responses and can decrease after response deletion. Execution-queue progress, billing, and run status are unchanged. ### Updated: source tag tools know built-in tags The source tag MCP tools are now `source_tags__list`, `source_tags__get_sources`, `source_tags__create`, `source_tags__update`, and `source_tags__delete`, replacing `list_source_tags`, `create_source_tag`, `update_source_tag`, and `delete_source_tag`. The listing returns every tag a website sees, including Owned, Competitor and the built-in tags AthenaHQ classifies automatically, with kind, icon, colour and, for built-in tags, only the website's own additions and removals. The new `source_tags__get_sources` lists the cited domains a custom tag matches or, with `untagged`, the domains no tag covers. `source_tags__update` edits a built-in tag's website copy by adding or removing patterns; creating a tag named like a built-in tag, listing a built-in tag's sources, renaming or deleting a built-in tag are refused. Create accepts an optional icon and colour. No REST endpoints change. ### Added: custom source tags over MCP `list_source_tags`, `create_source_tag`, `update_source_tag`, and `delete_source_tag` manage custom source tags with the same validation, Analytics permissions, audit logging, and source-cache invalidation as Athena AI chat. Edit and delete require the revision returned by the list tool and advertise destructive-action hints. MCP clients control confirmation; authorized calls execute immediately. Deletion retains source records. No REST endpoints are added. Authenticated MCP tool calls also emit a structured completion log with duration in milliseconds, status, tool name, and authentication type for latency inspection. No histogram metric is added. ### Added: brand and competitor identifiers over MCP `get_identifiers` reads the names, aliases and domains that count as a mention of your brand, or of one competitor when you pass `competitor_id`. It separates `default_identifiers`, the name and domain that are always matched, from `identifiers`, the ones you can remove. `update_identifiers` takes `add` and `remove` lists under the same rules as the Competitors page: the name and domain cannot be removed, and a value that is already listed, or that another tracked brand or competitor on the website uses, is refused without saving anything. New responses use the change right away. Past responses are reanalyzed only when someone runs the backfill on the Competitors page; `changes_awaiting_backfill` counts the edits waiting for it. Both tools follow the Competitors permission on signed-in connections (view to read, write to edit) and respect API-key website scopes. `get_competitors` is unchanged, and there is no REST endpoint. ### Updated: clearer MCP write tool effects `publish_content` is displayed as “Mark content as published”: it records a live URL for citation tracking without publishing to a CMS. `set_prompt_tags` now declares `destructiveHint: true` because it replaces existing tag assignments. Content generation and response-streaming descriptions now state their external AI provider use and credit consumption. For brief-only draft generation, explicitly set `auto_approve: false`; its default is `true`. Response runs use every active prompt when both `schedule_id` and `prompt_ids` are omitted. Tool names, request fields, response shapes, and REST status codes are unchanged. ### Updated: Gemini in Shopping metrics `POST /api/v1/metrics/shopping` accepts `gemini` in `filters.models`, next to `chatgpt` and `ai_mode`. Athena now records the product cards Gemini shows in shopping answers, so Shopping metrics include Gemini products from this release onward, with no earlier Gemini history. With `models` omitted the response covers every shopping-capable model, so totals include Gemini products. As with AI Mode, Gemini cards carry no per-seller offers, so `merchant_breakdown` and `offer_summary` do not count them. The MCP tool `get_shopping_metrics` accepts the same value. Field names, response shapes and status codes are unchanged. ### Added: add a finished article to Content Hub over MCP `add_content` stores an article that is already written, such as one drafted with Claude, as an editable Content Hub draft, the same as pasting it into the blank editor. Send `website_id` and the article as Markdown in `body`, plus an optional `title` (taken from the body's first heading when omitted) and `sheet_id`. No AI model runs and no content credits are spent. The item is created with type `manual` at stage `generated`, and the body is recorded as version 1, so `get_content_draft`, `edit_content`, `revise_content` and `get_content_versions` work on it right away. Link and image destinations with an unsafe scheme, such as `javascript:`, are replaced with `#` and counted in `unsafe_links_removed`. The item is not published: once it is live, call `publish_content` with its URL. `create_content` is unchanged apart from its description, which now points to `add_content` for articles that are already written. There is no REST endpoint for this yet. ### Updated: saved views that follow a topic A saved view can follow a topic in Athena, so it covers prompts added to the topic after the view was saved and drops prompts deleted from it or moved out. The metrics endpoints under `/api/v1/metrics` apply such a view, sent as `filters.saved_view_id`, to the topic's prompts at the time of the request. `GET /api/v1/saved-views` and `GET /api/v1/group-saved-views` keep listing prompt ids in the `prompts` and `selectedGroupPromptIds` filters: for a view that follows a topic, those are the topic's current prompts, or `00000000-0000-0000-0000-000000000000`, which matches no prompt, when the topic has none left. The MCP tools `get_saved_views` and `get_group_saved_views` return the same. Request fields, response shapes and status codes are unchanged. ### Added: Prompt discovery over MCP `start_prompt_discovery` starts an asynchronous Discover study with selected sources, country, language, prompt-count target and optional custom instructions. `get_prompt_discovery_runs` reads visible history or polls the returned `run_id`, distinguishing pending, running, completed, partial, failed and cancelled studies. Launch retains prompt-management permissions and source entitlements; progress is read-only. MCP clients handle invocation confirmation. Prompts are not automatically added to tracking, and candidate results remain available on the Discover page. These additions do not add public REST endpoints or change existing tool contracts. ### Updated: consistent URL-pattern ownership and source tags Sources and Source Pages now use the same URL-pattern engine as website and competitor tracking. Domain matching ignores case; explicit `www` hosts remain distinct, and path rules match sections rather than partial path names. Query constraints preserve case and support exact values or parameter presence. Domain summaries use whole-host rules only. Source Pages retains its normalized URL identifiers, response shape, and pagination. Website creation and provisioning preserve the submitted tracking scope, path case, and query constraints. `acme.com` includes `www.acme.com`; submitting `www.acme.com` tracks only that host. Existing stored patterns are read through the migration adapter until configuration migration is complete. ### Added: Branded or Non-branded on listed prompts `GET /api/v1/prompts` now returns `prompt_type` on each prompt: `branded`, `non_branded`, or `null` when the prompt has no type. These match the Branded and Non-branded badges in Athena and the values the `prompt_type` filter on the metrics endpoints accepts. They are not tags, so they never appear in the `tags` array, which still lists only your custom tags. To set the type when you create or edit a prompt, keep sending `type` on `POST /api/v1/prompts` and `PATCH /api/v1/prompts/{prompt_id}`, where `high_intent` means Branded and `discovery` means Non-branded. The MCP tool `get_prompts` returns the same field. Existing fields are unchanged. ### Fixed: runs no longer drop a model whose id they don't recognize `POST /api/v1/response-streaming/start` used to skip any `selected_models` key that named no model and start the run with the rest. Selecting AI Overviews as `google_ai_overview` (its name in the model filters) therefore ran every other selected model and left AI Overviews out, and a selection with only that key was rejected as having no available models. `google_ai_overview` is now accepted as another name for `ai_overview`, and any other key set to `true` that names no model is rejected with 400, listing the valid ids. Unknown keys set to `false` are still ignored. The MCP tool `start_response_streaming` behaves the same way. Field names, response shapes and the other status codes are unchanged. ### Added: Brand trait observations with a strength score `POST /api/v1/attributes/observations` returns individual brand trait observations, for your brand and your competitors, each with the excerpt of the AI response it comes from. Each row carries a `score` from -1 to 1: its sign always matches `positive`, and its magnitude (0.1 to 1.0) is how strongly the wording praises or criticizes. `score` is `null` for observations that were not scored, including those extracted before scoring existed; use `score ?? (positive ? 1 : -1)` if you only need the direction. Filter by `entity_ids`, `attribute_ids` and `positive`, sort by `intensity` (strongest first, the default) or `recent`, and page with `page_num`, `page_size` and `has_more`. The MCP tool `get_attribute_observations` returns the same data. The existing `/api/v1/attributes` endpoints are unchanged. ### Added: combine several schedules in MCP queries and saved views The MCP `query_metrics` and `query_rows` tools accept an array in `schedule`, such as `["default", ""]`, which combines those streaming schedules, archived included, in one result. Order does not matter and duplicates collapse. Omitting `schedule` still selects Default, and a single schedule is still `"default"` or a custom or archived schedule's UUID. Schedules run on different cadences, so combined counts and trends mix them. The metrics endpoints under `/api/v1/metrics` apply a saved view stored with several schedules when you send it as `filters.saved_view_id`: they return combined metrics for those schedules. A `filters.schedule_id` sent next to `saved_view_id` still replaces the view's schedules with that one schedule. REST `filters.schedule_id` still takes exactly one schedule and returns `400` for a list. `get_prompt_schedules` is unchanged and has no combined row. ### Fixed: AI Access evidence distinguishes failed probes from denied requests `POST /api/v1/ai-access/check` adds `result.evidence` with per-agent nullable HTTP observations, independent robots.txt policies and an `inconclusive` rollup. Diagnostics retain `verdict` (`allowed`, `blocked`, `challenged`, `error`, `not_tested`). Policy-only tokens are not tested, and diagnostic logs use the evidence status so an incomplete probe is not reported as blocked. HTTP 200 challenge pages are detected; timeouts, network failures and ordinary server errors mean unknown access. Google-Extended is evaluated as a robots.txt policy token, without an HTTP probe. Existing status and boolean fields remain for compatibility. Legacy Gemini HTTP training falls back to the measured Googlebot response when Google-Extended has no HTTP observation, without changing its raw `null` evidence or independent robots.txt policy. New consumers should use `evidence`. No sitemap is claimed without a check. Requests come from Athena's network and cannot guarantee real crawler access, indexing or citations. ### Changed: expected count leaves out variations that were never generated In `GET /api/v1/response-streaming/status`, `saved_response_progress.expected_count` now counts every planned base request plus only the prompt variations that generation actually produced. Until now it always equalled `planned_count`, so a run whose variation generation came up short could never reach its expected count, even with every queued response saved. `planned_count` still reports the original plan, so the difference is the number of variations that were not generated. Runs whose original population completed before this change keep their stored counts. Field names, types and status codes are unchanged. ### Changed: Grok responses cost 5 credits for every organization Grok responses are now billed at 5 credits each, like Claude, DeepSeek, Meta AI and Mistral. Until now, organizations created before July 21, 2026 paid 1 credit per Grok response. Grok now answers from xAI's own web search instead of Perplexity's, so the sources Grok cites shift from this release on. The `grok` model filter value, response shapes and status codes are unchanged. **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", Grok included. Pass an explicit `selected_models` map without Grok to stop paying for it. ### Added: public AI crawler access and ChatGPT extension `check_public_ai_access` checks public HTTPS domains without an AthenaHQ account. Reports separate HTTP observations from robots policy for search, retrieval and training, with nullable evidence and diagnostics. The ChatGPT extension provides sidebar and thread entrypoints, report restoration, copy/export and explicit sharing. Requests use crawler user agents from AthenaHQ, not verified crawler IPs; access does not guarantee indexing or citation. Existing account analytics, writes and the authenticated AI-access endpoint retain their contracts and permission checks. See [public crawler access](/api-reference/mcp#public-ai-crawler-access). ## September 2026 ### Added: saved-response progress on streaming status `GET /api/v1/response-streaming/status` now includes `saved_response_progress`: original planned and expected counts, current distinct saved responses, and the first terminal outcome's saved count, status, and timestamp. Recovery can increase current completion without rewriting that snapshot. The summary is `null` when no original request plan was recorded; an incomplete original population keeps its expected and initial saved counts `null`, not zero. Existing `progress` fields still measure queue completion, and only `state: "completed"` signals that downstream analysis has finished. The MCP `get_response_streaming_status` tool exposes the same additive field; Claude.ai users may need to allow the updated tool once after deployment. ### Added: confirmed-statement evidence in Oracle MCP findings `get_oracle_findings` and `get_oracle_finding` include optional `grounding` for findings derived from a team-confirmed statement. It contains `kind: "confirmed_statement"`, the complete `statement`, `confirmationId`, `sourceFindingId`, and all supporting `facts` (`id`, `text`). Use this complete statement as the finding's evidence; existing `fact_id` and `fact_text` retain their compatibility-anchor meaning and must not be treated as independent proof when grounding is present. The `fact_id` list filter also matches supporting fact references. Legacy findings retain their existing fact evidence. Public REST endpoints are unchanged. ### Added: metrics for a saved view The metrics endpoints under `/api/v1/metrics` (mention rate, share of voice, citation rate and position, cumulative and time series) accept `filters.saved_view_id`, an id from `GET /api/v1/saved-views`. The view's filters apply the way the dashboard applies them, including its defaults of active prompts and every model, so the numbers match the dashboard for the same view and dates. `start_date` and `end_date` still decide the window; the view's saved date range is ignored. A filter sent next to `saved_view_id` replaces the view's value for that field. A view on another website returns `404`, and a view filter the API cannot apply returns `400` naming it. The MCP metric tools take the same field. See [Saved view exports](/api-reference/saved-view-exports) for a scheduled export into a warehouse such as Snowflake. Requests without `saved_view_id` are unchanged. ### Improved: consistent schedule creation `POST /api/v1/websites` and `POST /api/v1/websites/provision` create each website and its Default prompt schedule together. Successful responses retain the same fields and status codes. ### Improved: flexible dates in MCP date-range filters MCP `filters.start_date` and `filters.end_date` now accept ISO dates and timestamps, English month names, and unambiguous numeric dates. Impossible dates, ambiguous day/month ordering, and reversed explicit ranges return validation errors instead of silently producing empty results. Date-only end bounds include the UTC day through `23:59:59.999Z`; explicit timestamps retain their instant. Partner REST contracts are unchanged. See [MCP date-range inputs](/api-reference/mcp#date-range-inputs) for formats and UTC behavior. ### Fixed: email addresses refused as website URLs `POST /api/v1/websites` and `POST /api/v1/websites/provision` now return `400` when `url` is an email address or any other URL with a user name, such as `name@example.com` or `mailto:name@example.com`. These parsed as a user name on the email's domain and were stored as the website URL. The error reads "Enter your website address, not an email address." Valid website URLs, including ones with `@` in the path (`example.com/@brand`), are unaffected. ### Fixed: owned URL patterns with a path no longer own their whole host `POST /api/v1/sources` and `POST /api/v1/source-pages` (MCP: `get_sources`, `get_source_pages`) classify sources against the website's owned domains. An owned URL pattern with a path, such as `reddit.com/user/brand`, used to make every page on that host `owned`; it now makes only the pages under that path `owned`, matching how citations are attributed. On the host level (`/sources`) such a pattern no longer marks the host as `owned`. Domain-level source-type overrides now take effect on hosts that were `owned` only as subdomains of a listed domain, while a listed host or path stays `owned`; an override on the exact URL still decides first. Responses keep the same shape; only `default_source_type` values on the affected rows change. ### Added: create prompt tags through MCP Use `create_prompt_tag` with `website_id` and `tag` to create a tag or reuse an existing case-insensitive name match. The result includes `tag_id`, `tag`, and `created`. Assign or unassign prompts with `set_prompt_tags`, which replaces one prompt's full tag list; include the IDs you want to keep, or pass an empty list to clear all tags. Both tools require Prompts: write on signed-in connections and respect API-key website scopes. See [MCP write tools](/api-reference/mcp#write-tools). ### Added: who made each activity entry `GET /api/v1/activity` now returns `actor.user` on changes made in the app: the person's `id` and `email`. It is `null` for changes made through an API key or by the system. Keys scoped to specific websites see members of those websites only; other people appear as `user: null`. Existing fields are unchanged. ### New: activity feed for partner integrations `GET /api/v1/activity` lists the changes made to prompts, topics and prompt tags across your organization, newest first by default, with the website, the kind of change, the affected ids and whether an API key made it. Filter by `website_id`, `entity_type`, `change_type` and a `since`/`until` window; page with `page_num` and `page_size`. To mirror prompts, pin a window per sync run (`since` = the previous run's `until`, `until` = now minus one minute, `order=asc`) and walk the pages: one call per run replaces re-listing every website. An entry with `entity_ids: null` means re-list that website. Available to partner API keys. ### New: Generate pitch reports through the API `POST /api/v1/pitches` accepts `website_url`, with optional `country` and `language`. Use your global organization API key and an `Idempotency-Key` header. The API returns `202` with `pitch_id`, `status`, and a shareable `report_url`; poll `GET /api/v1/pitches/{pitch_id}` for completion. Reports appear in your Pitch Workspace. Each admitted attempt consumes one pitch allowance unit. Repeating the same request key reuses the report, including after completion or failure. Generation sends no email. ### Fixed: MCP API-key connections from Optimizely Opal The MCP endpoint now accepts AthenaHQ API keys in `Authorization: Bearer `, enabling clients such as Optimizely Opal that cannot send a custom `x-api-key` header. Keys retain their existing organization, website scope, and write permissions. OAuth access tokens and `x-api-key` connections continue to work. REST endpoints under `/api/v1` still require `x-api-key`. See [Connect Optimizely Opal](/api-reference/mcp#connect-optimizely-opal) for OAuth and API-key setup. ### Added: active period on prompt schedules `GET /api/v1/prompt-schedules` (MCP: `get_prompt_schedules`) now returns `starts_on` and `ends_on` on every schedule: the first and last UTC calendar days (`YYYY-MM-DD`) a custom schedule fires, or `null` when that side has no bound. A schedule can be `is_active: true` and still not run because today is before `starts_on` or after `ends_on`; use the two dates to tell a seasonal schedule that has ended from one that is running. Default always returns `null` for both. Existing fields are unchanged. ### Improved: response-streaming status says why a run stopped `GET /api/v1/response-streaming/status` (MCP: `get_response_streaming_status`) now includes `finish_reason` next to `state`. It is set when a run ended `failed` or `cancelled` and names the cause: `credits_exhausted` (no credits remaining), `credits_paused` (credit allocation paused by the partner), `subscription_inactive`, `organization_deleted`, `entitlement_unreadable` (billing could not be read mid-run; pending responses are retried by the backfill), `cancelled_by_user`, `responses_failed` (collection finished with some failed responses), `items_stuck`, `attribute_extraction_failed`, `workflow_error` or `stale`. It is `null` while a run is in progress, for runs that completed normally, and for runs that ended before this field existed. The field is additive; the rest of the response is unchanged. ### 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) This release introduced retrieval of brand-perception attributes and how often each appeared in AI responses. The August 2026 update changed attributes to neutral traits, such as **Pricing** or **Support responsiveness**, with positive and negative observations of the same trait. Current attributes do not have a fixed sentiment. * **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. # 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. > [card] [Create API Keys](https://app.athenahq.ai/organization?tab=api) > > Generate and manage API keys in your organization settings > [!NOTE] > > 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. `filters.schedule_id` takes exactly one schedule and answers a list with `400`. Two other paths combine several schedules, archived included. The MCP `query_metrics` and `query_rows` tools accept an array in `schedule`, such as `["default", ""]`, and the metrics endpoints apply a saved view stored with several schedules when you send it as `filters.saved_view_id`. A `filters.schedule_id` sent beside the view replaces its schedules with that one schedule. Schedules run on different cadences, so combined counts and trends mix them. 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`. # Looker Studio Source: https://docs.athenahq.ai/api-reference/looker-studio Integrate AthenaHQ with Looker Studio ## Setup **1. Create an API Key** 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. > [card] [Manage API Keys](https://app.athenahq.ai/organization?tab=api) > > Create and manage API keys in your organization settings **2. Add Data Source in Looker Studio** 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 **3. Configure the Connector** 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) follow your account's access permissions, with the Claude response-data exclusions described below. 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 ``` ## Source tags Use `source_tags__list`, `source_tags__get_sources`, `source_tags__create`, `source_tags__update`, and `source_tags__delete` to work with source tags. A website sees three kinds: Owned and Competitor (set from brand and competitor identifiers), built-in tags AthenaHQ classifies automatically (Media, Social, Government, E-Commerce, Review sites, PR Wire, Academic and research, Wiki), and the website's custom tags. These are separate from prompt tags. All tools require `website_id` and respect API-key website scopes or your account's Analytics permissions. Reading needs view access; writes need write access. `source_tags__list` returns every tag with its kind, icon, colour, revision and patterns: a custom tag's own patterns, or, for a built-in tag, only what this website added or removed from it. The platform's own patterns are never listed. Use `offset` and `limit` for tag pagination, or `tag_id`, `pattern_offset`, and `pattern_limit` to page one tag's patterns. `source_tags__get_sources` lists cited domains with citation counts: the domains one custom tag matches (`tag_id`), or, with `untagged: true`, the domains no tag covers at all. Built-in tags and Owned/Competitor are refused as `tag_id`; add or remove patterns on them instead. `source_tags__update` edits a tag with the current `expected_revision`. On a custom tag it accepts `name`, `add_patterns`, and exact `remove_patterns`. On a built-in tag it adds patterns to this website's copy or removes patterns from it: an addition is accepted only when the pattern does not already carry the tag here, a removal only when it does (by a platform rule, by automatic classification, or by your own addition). Built-in tags cannot be renamed. `source_tags__create` creates a custom tag with patterns and optional icon and colour; names of built-in tags are reserved. `source_tags__delete` removes a custom tag and its assignments while retaining source records; built-in tags cannot be deleted. Patterns support hosts, subtrees (`*.example.com`), path sections, exact pages, and query constraints; at most 500 per list. Update and delete advertise destructive-action hints and ask the assistant to obtain explicit confirmation. Your MCP client controls approval prompts; these hints do not enforce a confirmation dialog. Authorized MCP calls execute immediately. Athena AI chat retains its approval cards. If `analytics_refreshed` is false, the write succeeded but filtered analytics may still be cached; do not repeat the write to refresh analytics. These tools do not add REST endpoints. ## Outreach Outreach finds the authors of pages that AI answers cite and drafts a pitch to each. Five tools cover the same work as the Outreach page: * `list_outreach_contacts` reads saved contacts: status, author, email and its source, LinkedIn, contact page, and draft. Only pages someone has triaged, enriched or drafted are listed; find other cited pages with `get_source_pages`. Filter by `url` or `statuses`; page with `offset` and `limit` (default 20, at most 50). * `find_outreach_author` reads a page's byline, the addresses the page publishes, and Hunter.io, then saves the result. When no author is found it saves any site contact address or contact page it finds instead. * `draft_outreach_message` writes a pitch for a page and saves it as the page's draft. It uses the website's team-wide custom instructions (set on the Outreach page), the saved author name, and the signed-in user's name; API-key connections can pass `sender_name`. Nothing is sent. * `update_outreach_contact` edits the author name, email, LinkedIn, subject or body. Supply at least one field; only the fields you supply change, and `null` clears one. Changing the author to a different person also clears the previous author's email and LinkedIn unless you supply new ones. * `set_outreach_status` moves up to 100 pages to `New`, `Todo`, `In Progress`, `Done` or `Rejected`, and records each change to an existing contact in its Activity. A page without a contact gets one at the new status, with no Activity entry yet; `New` only resets existing contacts. Each email carries an `email_source`: `page_author` (published on the page and matching the author), `page_contact` (the site's own address, which may not reach the author), `hunter` (a Hunter.io match the page does not publish; check it before sending) or `manual`. It is `null` when the source is unknown, as for emails saved before sources were recorded. `page_emails` lists up to five addresses the page or its linked contact page publishes, the chosen one first, so you can compare them with the chosen one; it is not a complete inventory. Pages are identified by `url` in the form the Outreach feed stores, such as `example.com/blog/post`. A contact already saved under the exact URL you pass is used first, such as one the Outreach page saved for a query variant that the website's URL rules list separately. Otherwise protocol, `www.` and the query string (for example `utm_` tracking parameters) are ignored, as on the Outreach page. The page is always read at the URL you pass. All tools require `website_id` and Content permissions: view access to list, write access for the rest. `find_outreach_author` costs 0.1 credits when it finds an author and `draft_outreach_message` 0.1 credits per draft, billed as whole credits every 10 successful rows, the same as the Outreach page. These tools do not add REST endpoints. ## Public AI crawler access `check_public_ai_access` checks a public HTTPS domain without an AthenaHQ account. Pass `{ "domain": "example.com" }`, with no path, credentials or custom port. The response includes nullable per-agent `evidence`, request `diagnostics` and a diagnostic `log`. Search, user retrieval and training have separate roles. Google-Extended is policy-only and receives no HTTP probe. The ChatGPT extension opens from supported sidebar and thread surfaces. It shows HTTP responses and robots permissions, restores tool-result reports, follows the host theme, and supports copy, export and explicit report sharing. Requests originate from AthenaHQ using crawler user-agent strings, not verified crawler IPs. Unknown observations stay inconclusive. These checks do not measure visibility or guarantee real crawler access, indexing or citation. Public scans are limited to five per minute per hashed ingress IP. Anonymous MCP requests have a separate limit of 60 per minute and 512 KiB per request; batches are rejected. Account analytics and writes retain authentication, scopes and audit checks. The authenticated `check_ai_access` tool and partner `POST /v1/ai-access/check` contract retain their existing behavior. When you call an account tool without credentials, the server returns HTTP 401 with a `WWW-Authenticate` header pointing to its OAuth resource metadata. The response also retains the tool-level `_meta["mcp/www_authenticate"]` challenge. Your client can use either signal to start sign-in, then retry the tool call. Initialization, tool discovery, and public crawler tools remain available without sign-in. ## Date-range inputs MCP tools with `filters.start_date` and `filters.end_date` accept these formats: | Format | Examples | | - | - | | Year first | `2026-09-29`, `2026/9/29`, `2026.9.29` | | English month name | `September 29, 2026`, `Sep 29 2026`, `29 September 2026`, `29-Sep-2026` | | Unambiguous numeric date | `09/29/2026`, `29/09/2026`, `29-09-2026`, `29.09.2026` | | ISO 8601 timestamp | `2026-09-29T12:30:00Z`, `2026-09-29T12:30:00-07:00` | Dates are normalized before querying. Date-only inputs keep their calendar day; timestamps preserve their instant and are normalized to UTC. An ISO timestamp without a timezone is interpreted as UTC. A date-only start begins at midnight UTC; a date-only end includes that day through `23:59:59.999Z`. Explicit end timestamps keep their exact instant, including midnight. Omitting `end_date` keeps the tool's existing default. Invalid calendar dates, incomplete dates, relative expressions such as `yesterday`, and ambiguous numeric dates such as `03/04/2026` return a validation error instead of empty results. Spell out the month or use `YYYY-MM-DD` to resolve ambiguity. Use four-digit years. An explicit end must not precede the start. This flexibility applies to the shared MCP date-range filters, including metrics, responses, sources, and content analytics. Partner REST inputs, activity-feed timestamps, and generic cube query predicates retain their documented formats. ## Connect Claude.ai Connect from the AthenaHQ listing in Claude's connector directory. No API key needed. You sign in with your AthenaHQ account. > [!NOTE] > > The Claude connector excludes individual Claude-generated responses and > response-level records derived from them by provider policy. You can use it to > explore responses from other AI platforms, such as ChatGPT. Aggregate > analytics, such as visibility totals and attribute metrics, can still include > Claude data. To view individual Claude responses, use the AthenaHQ dashboard > or the REST API with an [API key](/api-reference/authentication). On Claude Team plans, an Owner or Primary Owner must enable the connector for your organization before you can connect your account. On Enterprise plans, users with a custom role that includes **Manage access to Libraries** can also enable it. **1. Connect AthenaHQ** Open the [AthenaHQ connector listing](https://claude.ai/directory/athenahq) in Claude and follow the connection prompts. You can also find AthenaHQ under **Customize > Connectors**. **2. Sign in and pick an organization** You'll be prompted to sign in with your AthenaHQ account and choose which organization to connect. Claude then discovers all available tools automatically. **3. Ask about your AI search performance** In a chat, open **+ > Connectors** and enable AthenaHQ for the conversation. Ask a question such as "Use AthenaHQ to compare our share of voice with competitors over the last 30 days." Claude pulls your AthenaHQ data into the conversation. Review and approve tool requests when prompted. Try questions like: * "How visible is our brand in AI search over the last 30 days?" * "What is ChatGPT saying about our brand in our tracked responses?" * "Which competitors gained share of voice over the last month?" * "Which pages are getting cited, and where should we focus next?" > [!NOTE] > > Prefer a manual setup? In Claude, open **Customize > Connectors** and add a > custom connector named **AthenaHQ** with the server URL > `https://api.athenahq.ai/api/mcp`. Follow the authentication prompts to sign > in with your AthenaHQ account and choose an organization. On Team and > Enterprise plans, an Owner or Primary Owner must add the connector first; > Enterprise users with **Manage access to Libraries** permission can also > add it. > See [Claude's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) > for the steps for your plan. ## 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. **1. Install the plugin** Open the [AthenaHQ plugin listing](https://chatgpt.com/plugins/plugin_asdk_app_6a4da6c4bcfc81919397faceada2af69) in ChatGPT and click **Install plugin**. **2. Sign in and pick an organization** Authorize with your AthenaHQ account and choose which organization to connect. **3. Mention @AthenaHQ in a chat** 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. > [!NOTE] > > 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 Optimizely Opal You need the Opal administrator role to register a remote MCP provider. ### Sign in with OAuth 1. In Opal, open **Tools > External Providers > Add Remote MCP Provider**. 2. Enter `https://api.athenahq.ai/api/mcp`, select **OAuth 2.0**, and click **Discover OAuth Endpoints**. 3. Leave **Use my own credentials** off so Opal uses Dynamic Client Registration. AthenaHQ issues a client ID automatically; you do not need a pre-issued client ID or client secret. 4. Leave scopes empty. AthenaHQ advertises no OAuth scopes. Do not enter the placeholder values `your-client-id` or `scope1,scope2,scope3`. 5. Enter a unique provider name and register it. Complete Opal's approval steps, then connect from **Tools > Connectors** and sign in to AthenaHQ to choose your organization. 6. Select the tools to add. To use them in Opal Chat, enable **Enable for Chat** in **Tools > Tools**. ### Connect with an API key If you prefer a shared API-key connection, create a key on the [API Keys page](https://app.athenahq.ai/settings/api). Scope it to the websites Opal should access. 1. Register a remote MCP provider with the same server URL. 2. Select **Bearer token** and paste the complete AthenaHQ API key into **Bearer Token**, without adding the word `Bearer`. 3. Complete registration, add the tools, and enable them for chat as needed. Opal sends the key as `Authorization: Bearer `. The connection uses the key's organization and website permissions, including write access within that scope. Delete the key in AthenaHQ to revoke access. See [Optimizely's remote MCP setup guide](https://support.optimizely.com/hc/en-us/articles/47179211028749-Add-a-remote-MCP-provider) for its provider approval and tool setup steps. ## Connect other MCP clients Clients that don't support the sign-in flow authenticate with an API key using either `x-api-key: ` or `Authorization: Bearer `. Bearer API-key authentication is supported on `/api/mcp`; REST endpoints under `/api/v1` require `x-api-key`. **1. Create an API key** 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. > [card] [Manage API Keys](https://app.athenahq.ai/settings/api) > > Create, view, and manage API keys in your organization settings **2. Add the server to your client config** 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. > [!NOTE] > > 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 the dimensions that cube allows, with optional period-over-period comparison | | `query_rows` | Individual rows (response text, identifiers, mentions) from any cube, with cursor pagination | ### Brand traits Brand-perception keywords (like "Affordable" or "Slow Support") extracted from AI answers. The API and tool names call them attributes. | Tool | What it returns | | - | - | | `get_attributes` | Brand traits tracked for a website, with attribute IDs | | `get_attribute_metrics` | Per brand trait, 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 brand trait, brand and competitors side by side | | `get_attribute_observations` | Individual brand trait observations with the response excerpt and a score from -1 to 1 | ### 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`. For an `optimize` item, `get_content_detail` also returns `source_url`: the live page it is based on, available as soon as the item exists. `url` stays `null` until `publish_content` records the published page and marks the item `done`, so read `source_url` to link a request in review to its page without publishing it. `list_content` does not carry this field. ### 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 | ### Brand kits The voice and style guidance content generation follows (Brand Profile > Brand kits). Needs a paid plan; the writing rules also need the writing rules feature. | Tool | What it returns | | - | - | | `get_brand_kit` | A brand kit as the editor shows it: the draft name, the eight guidance fields as text, voice settings, tone traits, the kit's and the website's global writing rules with ids, and the draft and published versions | ### 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 | | `get_identifiers` | Names, aliases and domains counted as mentions of your brand or a competitor | ### Outreach | Tool | What it does | Sign-in permission | | - | - | - | | `list_outreach_contacts` | Saved Outreach contacts with author, email and its source, and draft | Content: view | | `find_outreach_author` | Find and save a cited page's author and email, or the site's contact page | Content: write | | `draft_outreach_message` | Draft and save a pitch with the team's custom instructions | Content: write | | `update_outreach_contact` | Edit a contact's author, email, LinkedIn, or draft | Content: write | | `set_outreach_status` | Move pages between Outreach pipeline statuses | Content: write | ### 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. ### Prompt discovery | Tool | What it does | Sign-in permission | | - | - | - | | `start_prompt_discovery` | Start an asynchronous Discover study for untracked prompt opportunities | Prompts: write | | `find_more_prompt_discovery` | Start the next round of a finished study to find more prompts | Prompts: write | | `get_prompt_discovery_runs` | Read visible discovery history or one run's progress | Prompts: view | To start a study, supply `website_id`, a `name`, and at least one source: `website_analysis`, `social`, `search_console`, `keyword_gaps`, `competitive_landscape`, or `brand_guidelines`. You can specify `country`, `language`, `prompt_count_range` with `min` and `max`, and `custom_instructions`. The default locale is `en-US`, the default country is United States, and the default prompt-count target is 25 to 50. Current count bands are 25 to 50, 50 to 75, 75 to 100, 100 to 150, and 150 to 200. Selecting `brand_guidelines` requires non-empty custom instructions. Keyword gaps and Competitive landscape retain their plan restrictions. Competitive landscape also requires at least one tracked competitor, and Search Console requires a connected integration to supply evidence. Review the sources, locale, requested count and instructions before launching. Launch uses external research services and AI models. Your MCP client handles invocation confirmation; Athena's in-app chat approval card is not displayed over MCP. The requested count is a target, not a guarantee, and discovery does not add prompts to tracking automatically. Startup returns `run_id` and `version`. Pass that ID as `run_id` to `get_prompt_discovery_runs` to poll the same study; do not start a second study to check progress. Without `run_id`, the tool returns recent history. `limit` defaults to 10 and is capped at 20. Status is `pending`, `running`, `completed`, `partial`, `failed`, or `cancelled`; results include `progress_percentage`, the current `phase` when available, and `total_prompts`. A finished run also carries `reason_code`, the terminal reason of a completed run or the error code of a failed one, and `reason`, a sentence safe to show the user that explains a failed, empty or short run, the same line the Discover page shows. Both are `null` when there is nothing to explain. `rounds` counts the rounds of a study continued with `find_more_prompt_discovery` (1 for a study never continued); status, progress and reason then describe the latest round, and `total_prompts` adds every round. `can_find_more` says whether another round can start now, and `find_more_reason` explains why not when one cannot. Review candidate prompts on the application's Discover page. These tools do not send notifications or add public REST endpoints. To find more prompts for a finished study, pass its `run_id` (or the `run_id` of any finished round that continues it) to `find_more_prompt_discovery` with its `website_id`. The new round repeats the study's sources, country, language, prompt-count target and custom instructions, skips every question the earlier rounds suggested, and reads evidence they did not use. Each round runs the same research as a new study, so confirm with the user first. A study takes one round at a time and at most two after the first run, and ends early after a round that found fewer than ten new prompts or nothing new to read; the tool then returns an error with the reason. The response is the new round's `run_id` and `version`; poll it with `get_prompt_discovery_runs` as for a new study. ### Site Health Site Health (`site_health` section) needs the feature on the website's plan; without it every tool below returns a 403. Start with `get_site_health_issues`: one group per kind of problem, with the pages it affects and each page's `finding_id` and `task_revision`. Over MCP a call returns at most 25 groups and a group carries at most 10 sample pages; `get_site_health_issue_pages` walks the rest, 50 at a time, and its page 0 repeats the sample pages. | Tool | What it returns | | - | - | | `get_site_health_issues` | Issues grouped by check: title, why it matters, severity, priority, owner, effort, page counts by status (`open`, `in_progress`, `fixed`, `verified`, `dismissed`), the sections they concentrate in, and sample affected pages with detail, recommendation, evidence and assignee. Filter by status, check, search, page URLs or `assignee: "me"`. | | `get_site_health_issue_pages` | Every page one issue affects, 50 per page, with each page's finding, evidence, dates and task revision. | | `get_site_health_analytics` | Live GA4, Search Console and AI-citation figures for the last 28 days beside the 28 before: AI sessions, organic and total sessions, clicks, impressions, CTR, position, top queries, pages and sources, and the website's most cited pages. | | `get_site_health_properties` | The crawl scopes Site Health audits, each with its live page count and latest crawl or audit run. | | `get_site_health_pages` | A property's audited pages, 50 per page, with last audit status, open finding count and priority flag; `groups` counts every open check on the property. | | `get_site_health_page` | One page's measurements (title, meta description, canonical, status code, word count, indexability, rendering comparison, Core Web Vitals), its audit history and every finding on it with its verification. | ### Site diagnostics | Tool | What it returns | | - | - | | `check_ai_access` | Robots.txt policies and observed crawler user-agent responses from Athena's network. Use `result.evidence` for nullable per-agent results and separate search/training; failed or challenged probes mean unknown access. No guarantee of real crawler access, indexing or citations. Includes a diagnostic log 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. To create a prompt tag, call `create_prompt_tag` with `website_id` and `tag`. The result includes `tag_id`. Tag names are trimmed, and an existing case-insensitive match returns `created: false`. Before changing assignments, call `get_prompts` with the same `website_id` and find the target prompt by its `id`. Its `tags` array contains the current assignments as `{ id, name }` entries. Build the full desired `tag_ids` list from those IDs: add the new `tag_id` to assign it, or remove a tag's ID to unassign it, keeping all other IDs. Call `set_prompt_tags` with `website_id`, that prompt's `prompt_id`, and the resulting `tag_ids`. Pass an empty list only when you want to clear all tags. Repeat this read-and-update process for each prompt. Identifiers are the names, aliases and domains Athena looks for in AI responses to count a mention. Before changing them, call `get_identifiers` with `website_id`, plus the `competitor_id` from `get_competitors` for a competitor (omit it for your own brand). `default_identifiers`, the name and domain, are always matched and cannot be removed. Then call `update_identifiers` with the same ids and `add` and `remove` lists. The rules are the Competitors page's: a value that is already listed, or that another tracked brand or competitor on the website already uses, is refused and nothing is saved. New responses use the change right away. Past responses are reanalyzed only when someone runs the backfill on the Competitors page, which costs credits; `changes_awaiting_backfill` counts the edits waiting for it. A brand kit is edited as a draft and used by content generation only once published. Call `get_brand_kit` with `website_id`, and `kit_id` for a kit other than the default, to read the draft text, the rule ids and the versions; pass `fields` to read a clipped guidance field whole. Then call `update_brand_kit` with the `kit_id` and only what changes: `name`; `guidance` entries with a `field` and the new `text`, plus `find` to replace one passage that occurs exactly once in the text you read; `voice_settings` with values 1 to 5 or `"auto"`; `rules` with `add`, `update` by id and `remove` by id. Edits save to the draft; `publish: true` also publishes it as a new version, which the Brand Profile page can restore from. The result's `outcome` is `saved`, `saved_and_published`, or `saved_publish_failed` with the reason in `publish_error`. A rule that contradicts an existing kit or global rule, a name another kit uses, and a kit still generating are refused and nothing is saved. Kit rules need the writing rules feature on the plan. The tool does not change global rules. Global writing rules, the ones the Global rules tab holds and every kit follows, are changed with `update_global_rules`: `website_id` plus `add`, `update` by id and `remove` by id, with the ids from `get_brand_kit`'s `global_rules`. There is no draft: the change is live for all future content as soon as it is saved, as a new version the Global rules tab's change history can restore. The same conflict check applies, and the feature requirement is the same. To create a kit from material you already have, call `create_brand_kit` with `website_id`, a `name` unique on the website, and the `guidance` entries, `voice_settings` and `rules` you author from it; nothing is generated. The kit starts as a draft; `publish: true` publishes it as version 1, and the website's first kit becomes its default. Generating a kit from the website or uploaded documents stays on the Brand Profile page. To track new competitors, call `add_competitors` with `website_id` and 1 to 25 `competitors`, each with a `name` and its website `url`, or `no_website: true` for a brand without a website, plus optional `identifiers` and `additional_urls`. Each competitor gets its own result: `added` with its `competitor_id`, `already_tracked` when the website already tracks that URL (nothing changes), or `rejected` with a `reason`, such as a URL on your own domains or the limit of 500 competitors per website. To stop tracking competitors, call `remove_competitors` with up to 25 `competitor_ids` from `get_competitors`; each result is `removed`, `no_change` (already removed) or `not_found`. Removal keeps past mentions and citations, and the Competitors page can restore the competitor. Neither tool reanalyzes past responses or spends credits: that backfill stays on the Competitors page. | 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 | | `create_prompt_tag` | Create a prompt tag, or return an existing tag with the same name (case-insensitive) | Prompts: write | | `set_prompt_tags` | Replace one prompt's tag assignments, or clear them with an empty list | 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 | | `update_identifiers` | Add or remove identifiers on your brand or a competitor (no backfill, no credits) | Competitors: write | | `add_competitors` | Track up to 25 new competitors, with a result for each (no backfill, no credits) | Competitors: write | | `remove_competitors` | Stop tracking up to 25 competitors, with a result for each (no backfill, no credits) | Competitors: write | | `start_response_streaming` | Start a response run for all prompts or a selection | Prompts: write | | `start_prompt_discovery` | Start a Discover study with selected sources, locale and optional instructions | Prompts: write | | `find_more_prompt_discovery` | Start the next round of a finished Discover study, skipping what earlier rounds suggested | Prompts: write | | `create_content` | Start the content pipeline (brief or full article, from a prompt or a topic) | Content: write | | `add_content` | Add an already written article as an editable draft (no generation, no credits), as version 1 | 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 | | `update_brand_kit` | Change a brand kit's name, guidance text, voice settings or rules in its draft, and publish on request | Brand knowledge: write | | `update_global_rules` | Add, update or remove the global writing rules every kit follows (live immediately, restorable from change history) | Brand knowledge: write | | `create_brand_kit` | Create a brand kit from text you provide (name, guidance, voice settings, rules), as a draft or published as version 1; no generation | Brand knowledge: write | | `update_site_health_task` | Assign one Site Health finding or set its work status (`todo`, `in_progress`, `ready_to_verify`, `dismissed`); needs the page's `finding_id` and `task_revision`; `unassign: true` clears the assignee; signed-in connections only | Analytics: write | | `update_site_health_issue` | Set the status or assignee of a whole Site Health issue, every unresolved page of one check at once; `unassign: true` clears every page; signed-in connections only | Analytics: write | | `start_site_health_audit` | Audit a Site Health property: full (crawl, then every page), a sample, or 1 to 100 named pages to verify a fix | Analytics: write | | `create_saved_view` | Save a dashboard filter preset (name, optional icon, `filters` object up to 64KB, stored verbatim) | Any member | The two Site Health task writes need a signed-in connection: the task row records who changed it and a newly assigned teammate is told who assigned them, and an API key stands for no one, so API-key connections are not offered them. `start_site_health_audit` works on API-key connections. `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`, `move_content` and `add_content` are the three 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." # Generate a pitch report Source: https://docs.athenahq.ai/api-reference/pitch-creation Create a shareable prospect report from a website URL, then poll for results. Use a global organization API key with admin access. Your organization needs Pitch Workspace access and available pitch allowance. ## Create Choose one request key per report. Keep the same key when retrying a timeout or temporary error. ```bash theme={null} curl --request POST 'https://api.athenahq.ai/api/v1/pitches' \ --header "x-api-key: $ATHENA_API_KEY" \ --header 'Idempotency-Key: prospect-example-september-2026' \ --header 'Content-Type: application/json' \ --data '{"website_url":"https://example.com"}' ``` ```json theme={null} { "pitch_id": "600d2cf4-3419-4eaa-a077-e94c46c26939", "status": "processing", "report_url": "https://app.athenahq.ai/report/600d2cf4-3419-4eaa-a077-e94c46c26939" } ``` The response is `202 Accepted`. Only `website_url` is required. Optional `country` and `language` default to `United States` and `English`. Research prepares the company profile, competitors, and prompts before the standard Pitch Workspace report runs. A processing report may initially show the submitted domain and empty results. Reports research 20 prompts and query ChatGPT, Perplexity, Gemini, and Copilot. The report displays all 11 supported models and highlights those with results. ## Poll ```bash theme={null} curl 'https://api.athenahq.ai/api/v1/pitches/600d2cf4-3419-4eaa-a077-e94c46c26939' \ --header "x-api-key: $ATHENA_API_KEY" ``` Poll every 10 seconds and inspect **`pitch.status`** in the existing detail response. Stop at `completed` or `failed`. Completed reports include competitors, prompts, sources, attributes, and metrics. Share `report_url` after completion. Anyone with that link can view the report. Creation does not send email; your application chooses when and how to deliver it. ## Retries and allowance * Each admitted report consumes one pitch, including a report whose research or generation later fails. Unlimited organizations do not consume a finite allowance. * Retrying the same key and normalized input returns the same report without a second charge. A different body with the same key returns `409`. * A new key requests a new report, even for the same website. * Creation permits three concurrent API reports per organization and 10 requests per minute. Honor `Retry-After` on `429` responses. * On a temporary `500`, retry the same request key. Do not switch keys to work around a billing error. An unresolved billing operation can require support reconciliation; its reserved allowance remains held to prevent duplicate spending. See [Create a pitch report](/api-reference/pitch-workspace/create-a-pitch-report) for the full request and response schema. # 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 **1. Create an API key** 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. > [card] [Manage API keys](https://app.athenahq.ai/organization?tab=api) > > Create and manage API keys in your organization settings **2. Look up your website_id** 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. **3. Add the query in Power BI Desktop 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 ``` **4. Shape the response into a table** 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. **5. Configure credentials in Power BI Service or Fabric** 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 > [!WARNING] > > 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 > [!WARNING] > > 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. # Saved view exports Source: https://docs.athenahq.ai/api-reference/saved-view-exports Pull the metrics of a dashboard saved view into Snowflake, BigQuery, or any warehouse on a schedule AthenaHQ does not ship a native warehouse connector. To keep a warehouse table in step with a saved view, run a scheduled job on your side that asks the metrics endpoints for that view and a date range, then writes the result to your warehouse. The endpoints apply the view's filters the way the dashboard does, so the numbers match what the dashboard shows for the same view and dates. ## Prerequisites * An AthenaHQ API key with access to the website (Organization → API tab). See the [Authentication](/api-reference/authentication) page. A dedicated key scoped to this one website is the safest choice for a scheduled job. * The `website_id` you want to report on. Fetch it with `GET /api/v1/websites`. * A saved view on that website, created in the dashboard. ## Setup **1. Find the saved view's id** ```bash theme={null} curl "https://api.athenahq.ai/api/v1/saved-views?website_id=YOUR_WEBSITE_ID" \ -H "x-api-key: YOUR_API_KEY" ``` Copy the `id` of the view whose `name` you want. The id stays the same when someone edits the view in the dashboard, so the export follows those edits. **2. Request a month of metrics for the view** ```bash theme={null} curl -X POST https://api.athenahq.ai/api/v1/metrics/mention-rate/cumulative \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "website_id": "YOUR_WEBSITE_ID", "filters": { "saved_view_id": "YOUR_SAVED_VIEW_ID", "start_date": "2026-08-01", "end_date": "2026-08-31" } }' ``` The response has one entry per brand: yours (`is_self: true`) and each competitor the view selects. ```json theme={null} { "data": { "Your Brand": { "mention_rate": 42.3, "relative_mention_rate": 61.8, "is_self": true }, "Competitor A": { "mention_rate": 24.9, "relative_mention_rate": 36.4, "is_self": false } } } ``` **3. Schedule it** Run the request once a month for the month that just ended and append the rows, with the month, to your table. For example, in Python: ```python theme={null} import datetime as dt import requests today = dt.date.today() end = today.replace(day=1) - dt.timedelta(days=1) # last day of last month start = end.replace(day=1) response = requests.post( "https://api.athenahq.ai/api/v1/metrics/mention-rate/cumulative", headers={"x-api-key": API_KEY}, json={ "website_id": WEBSITE_ID, "filters": { "saved_view_id": SAVED_VIEW_ID, "start_date": start.isoformat(), "end_date": end.isoformat(), }, }, timeout=60, ) response.raise_for_status() rows = [ {"month": start.isoformat(), "brand": name, **values} for name, values in response.json()["data"].items() ] # Write `rows` to your warehouse table, e.g. with the Snowflake connector's # write_pandas or an INSERT through your usual loading tool. ``` ## Which number matches the dashboard The dashboard's Mention Rate card shows the **relevant** rate by default. In the API that is `relative_mention_rate`: mentions of the brand divided by the responses that mention your brand or one of the view's competitors. `mention_rate` is the card's **absolute** mode: mentions divided by every response in the view. Read the entry with `is_self: true` for your own brand. Because the relevant rate counts responses that mention any of the view's competitors, changing the view's competitor list changes your own relevant rate too, both in the dashboard and here. ## How the view is applied * **Dates.** `start_date` and `end_date` decide the window; the date range saved with the view is ignored. Send plain dates (`YYYY-MM-DD`). `end_date` is inclusive. * **Defaults.** Like the dashboard, the view counts active prompts only and every model, unless the view says otherwise. A request without `saved_view_id` keeps the API's own defaults, which include paused prompts. * **Overrides.** Any filter you send next to `saved_view_id` replaces the view's value for that field. For example, `"models": ["chatgpt"]` reads the view for ChatGPT only. * **Other pages' filters.** A saved view is shared with the Prompts, Responses and Sources pages. Filters that only those pages use, such as sentiment or source tags, do not change metrics in the dashboard, and they do not change them here. * **Every metric.** The same `saved_view_id` works on all the metrics endpoints: mention rate, share of voice, citation rate and position, cumulative and time series. The MCP metric tools (`get_mention_rate_cumulative` and the others) take it too. ## Errors | Status | Meaning | What to do | | - | - | - | | `404` Saved view not found | The id is not a saved view of `website_id`. | List the website's views again; the view may have been deleted. | | `400` Saved view "…" uses filters the API cannot apply | The view uses a filter the API cannot reproduce, such as a "Models is not any of" filter. The message names it. | Send the named filter explicitly (for example `filters.models`) to replace the view's value, or change the view in the dashboard. | # 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. > [card] [Contact support](mailto:support@athenahq.ai) > > Email [support@athenahq.ai](mailto:support@athenahq.ai) to start SSO onboarding > [!NOTE] > > SSO is an Enterprise-tier feature. If you are not on an Enterprise plan, contact your AthenaHQ account team about upgrading. # Brand Profile Source: https://docs.athenahq.ai/brand-profile Set up the brand details Athena uses for tracking, scoring, and content generation Use Brand Profile to manage your brand identity, the traits you track in AI responses, writing preferences, and brand kits. Attributes measure how AI describes your brand; Content Memories and Brand Kits guide content generation. Open [Brand Profile](https://app.athenahq.ai/brand-profile) from the left sidebar. To change attributes, open the [Attributes tab](https://app.athenahq.ai/brand-profile?tab=attributes). Editing requires **Brand Knowledge** write access. If controls are disabled or you see **View-only**, ask an organization admin to update your permissions. Some tabs also depend on the features included in your plan. *** ## 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** | Neutral traits tracked for positive and negative mentions in AI responses | | **Content Memories** | Saved writing preferences for future content | | **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 5 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. *** ## How to update brand attributes Open **Brand Profile > Attributes**. You can add a trait, deactivate one with **Delete**, or restore a deactivated trait. There is no inline rename or sentiment selector. To replace a trait, delete the old one and create the replacement. Attributes are neutral topics such as **Pricing**, **Reliability**, or **Ease of use**. Each trait can receive both positive and negative mentions in AI responses. For example, the same Pricing trait can capture praise for affordability and criticism of high costs. You do not assign a fixed positive or negative sentiment when creating a trait. ### Add an attribute 1. Open [Brand Profile > Attributes](https://app.athenahq.ai/brand-profile?tab=attributes). 2. Click **Create new**. 3. Enter a neutral trait name, such as Pricing. Each trait can receive both positive and negative observations; you do not choose a sentiment. 4. Click **Add**. The trait appears in the active list. You can have up to **12 active attributes in total**, shared across positive and negative observations. If an older account already has more than 12, reduce the active list before expanding it. To change an existing trait, use its **... > Delete** action and create the replacement; there is no inline rename. To bring back a removed trait, expand **Deactivated attributes** and click **Restore**. ### Delete or replace an attribute 1. Open the **...** menu on the attribute row. 2. Click **Delete**. This deactivates the trait and moves it to **Deactivated attributes**. 3. To replace it, click **Create new**, enter the replacement name, and click **Add**. Deleting a trait stops tracking it in future analysis. It is not an edit to the words in past AI responses. ### Restore an attribute Expand **Deactivated attributes**, then click **Restore** next to the trait. Restoring uses an active-attribute slot and makes the trait available for future analysis again. ### Reanalyze historical responses Adding, deleting, or restoring a trait shows the attribute backfill bar. Historical analysis does not automatically refresh when you change the list. 1. Select the date range to reanalyze. Presets range from **Last 2 weeks** to **Last 6 months**. 2. Click **View Changes** to review the pending changes. 3. Review the response count and credit cost, then click **Backfill**. The cost is one credit per 100 responses, rounded up. The bar shows the exact cost before you start. You can dismiss pending changes if you do not want to reanalyze past responses. ### Why is the Positive/Negative selector missing? This is expected. Attributes no longer have a fixed sentiment. Athena tracks positive and negative observations for each neutral trait. You only enter a name in **Add attribute**. ## Content Memories tab Content Memories are saved writing preferences, such as terminology to use or formatting to avoid. This tab appears when your plan includes the feature. 1. Open **Content Memories** and click **Add memory**. 2. Enter a writing preference and optionally choose a category: Style, Formatting, Terminology, Tone, Structure, or Other. 3. Save the memory. Click a memory or use its **... > Edit** action to change the text or category. Use the Status switch to enable or disable it, or **... > Delete** to remove it after confirmation. Disabling preserves the memory for later use. Content Memories guide writing. Keep verified product facts in the [Knowledge Base](/knowledge-base) and brand voice guidance in **Brand Kits**. *** ## 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. Open **Brand Profile > Brand Kits** and click **Create New**. 2. In **Setup**, enter a kit name and your blog or newsroom URL. 3. Review and edit the **Source notes** drawn from your existing content. 4. Add optional documents, such as a **Style guide** or **Brand Context**, in the Documents step. You can upload up to five PDFs. 5. Review the inputs, then click **Generate** to create the guidelines. The kit shows progress while generation runs. If you leave setup before generating, reopen the draft kit to continue from its saved step. A failed generation offers a retry. ### How to edit a brand kit Open a completed kit to edit its generated guidelines directly, then click **Save**. This saves your wording without running another generation. Use **View sources** to inspect the source notes and documents behind the kit. If you change those inputs and want Athena to rewrite the guidelines, use **Regenerate guidelines** and confirm. Regeneration replaces the generated guidelines, so review any manual edits you want to retain first. ### 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 a kit and select **Delete**, then confirm. Deletion cannot be undone. Make sure another suitable kit is set as the default if you want future content to keep using brand voice guidance. *** ## 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 An `llms.txt` file provides a readable overview of your site for tools that support it. It does not control crawler access or guarantee that AI models use your preferred description. 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. Use the results to investigate access problems. A blocked crawler cannot fetch that page directly, but AI answers may still use other sources about your brand. *** ## 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 the neutral traits you want to measure, up to 12 active traits. Each can be mentioned positively or negatively. 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. **Content Memories tab** *(if available)* - Add saved writing preferences for future content. 5. **Technical tab** - Generate your LLMs.txt and check your AI accessibility to make sure crawlers can reach your site. *** ## Permissions Changing your General details, Attributes, Content Memories, or Brand Kits requires **Brand Knowledge** write access. Technical generation actions, including LLMs.txt and sitemap generation, require **Content** write access. Ask an organization admin to adjust your role or resource permissions if the controls you need are disabled. See the [Brand Profile page reference](/guides/brand-profile) for the full set of controls and states. # 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. You need access to Discover on your plan. Individual sources can have separate access requirements; unavailable sources show **Requires an upgraded plan**. Search Console also requires a connected Google Search Console property. ## 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. **Checks existing coverage** - Compares proposed questions with the prompts you already track and removes redundant suggestions. A question that asks buyers to discover a suitable product serves a different purpose from a question evaluating a named product, so both may be useful. **Already tracked** labels identify suggestions already in your monitored set. **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** - customer questions informed by competitor search keywords. These indicate market demand; they do not prove that an AI engine currently cites a competitor or excludes your brand. * **Competitive landscape** - category questions and comparisons researched on Google from the competitors you track, such as how your brand compares with a competitor or which alternatives buyers consider. *Requires at least one tracked competitor; otherwise the source appears disabled with a link to add one.* Questions never claim what a competitor offers beyond what the research shows. * **Custom instructions** - describe the topics, products, audience, or intent you want the run to focus on. Selecting this source requires a written brief. Your instructions guide the run; they are not treated as verified product facts. Athena also reads your website to connect the selected market signals to your products and services, even if Website analysis was not selected. The run's source summary explains when website evidence was added for this purpose. Connecting Search Console is optional unless you want to use that source. ## 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; completion time depends on the selected sources and available evidence. 5. Open the run from the history list to follow progress and review results. Check its status and source summary before interpreting the output; a failed or empty source means that evidence was unavailable for the run. You can leave the page while it runs. ## Writing useful custom instructions Name the products, customer needs, and market you want to cover. Include exclusions and say whether you want branded questions, non-branded discovery questions, or both. You can include relevant product URLs to clarify the scope. For example: "Focus on organic bedding for people who sleep hot. Cover material choices, care, and durability. Include non-branded shopping questions and branded product comparisons. Exclude bath products." Examples communicate the direction of the run, so use them as illustrations rather than a fixed list to reproduce. Avoid asking Athena to assume product claims that your website does not support. Market signals establish what people need; your website establishes which needs your products can address. ## 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 want to explore competitor demand** - The Keyword gaps source uses competitor search keywords to find relevant customer questions. Use your tracked response and citation data separately to measure who actually appears in AI answers. **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. ## If a run returns few or no prompts Review the run's source summary. **Could not collect evidence** means a source failed; **No usable evidence** means it returned nothing usable. A small result set can reflect narrow instructions, limited supporting evidence, or coverage already in your tracked prompts. It does not by itself prove that you have covered the entire market. Check the website content and source connections, broaden overly narrow instructions, and start a new run when needed. Earlier runs remain in history and may show the older discovery layout. See the [Discover run reference](/guides/prompts-discover-id) for the current result controls. # 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 prompt schedule**: the AI engines and cadence configured during setup. Review the active schedule and credit estimate in **Schedules** in the sidebar. > [!NOTE] > > 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. **1. Invite users to the platform** 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**. **2. Connect your integrations** 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. > [!NOTE] > > 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. **3. Confirm your brand profile** 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. > [!NOTE] > > Brand Kit assets and guidelines are used to generate your custom content > in the Content Hub. **4. Add your competitors** 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. **5. Generate your first set of prompts** 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 (if included in your plan)** 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**. > [!NOTE] > > 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. **6. Set your schedule** Open **Schedules** in the sidebar to configure recurring prompt runs. 1. Edit **Default**. It runs all active prompts. 2. Pick the AI models and set a weekly or monthly cadence. 3. Review Prompt expansion, personas, locations, and the estimated credit use. 4. Click **Save schedule** and confirm the schedule is active. On the Enterprise plan, click **New schedule** for a separate run, and add conditions by tag, topic, prompt type, or country to choose which prompts it covers. Multiple schedules can include the same prompt and run independently. Paused personas and locations retain their history but do not create new responses. See [Set up recurring schedules](/setting-up-prompts#set-up-recurring-schedules) for selection rules, additional personas and locations, pausing, and one-off runs. 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 your schedule is saved and active. * 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 Multi-step wizard for creating (or resuming/completing) a website's onboarding setup: brand profile, competitors, prompts, region, Google Search Console, and monitoring schedule. > [card] [Open in AthenaHQ](https://app.athenahq.ai/add-website) > > `app.athenahq.ai/add-website` ## Purpose The Add Website page is a multi-step onboarding wizard where customers configure a new website for Athena to monitor. It captures the target website URL, autogenerates and refines the brand profile, discovers competitors, and stages the core prompts (queries) the AI will track. Customers also use this flow to set their target geography and language, optionally connect Google Search Console, and schedule which AI models to scan and on which days. It serves as both the initial setup for brand-new signups and the flow for existing accounts adding additional brands to their organization. ## What's on the page ### Form Steps * **About You**: Captures "First Name" and "Last Name". Asks "What's your role?" to customize the sidebar experience (General, Content Marketer, SEO, Executive, PR). It also includes a "Let teammates join automatically" toggle. * **Website URL**: Contains a "Website URL" input field where the user enters the domain they want to track. * **Region**: Contains "Country" and "Language" selectors to ensure the AI scans localized search results. * **Review Card Stack**: A stacked, swipeable interface containing three configuration cards: * **Brand profile**: Includes "Name", "Description", and "Select industry" dropdowns. * **Competitors**: Shows the **Competitors table** (detailed below) where users review AI-discovered competitors. * **Prompts**: Shows the **Prompts table** (detailed below) where users review the initial queries Athena will track. * **Google Search Console**: An optional card offering to "Connect" or "Disconnect" a GSC property. * **Schedule**: Shows toggles for "Models" (ChatGPT, AI Overview, Perplexity, Gemini, Copilot, AI Mode, Grok, Claude, DeepSeek, Meta AI, Mistral) and "Which days do you want your data reviewed?". It concludes with a "Cost summary" outlining estimated credits. * **Pricing Selection Popup**: A full-screen dialog shown to certain users adding a site to an existing org, offering "Free", "Starter", and "Enterprise" plans. Includes a "Monthly" / "Annual" billing toggle. * **Leave setup?**: A confirmation dialog that appears if the user clicks the top-left "X" to exit. It asks "What would you like to do?" and offers "Delete draft" or "Save for later". ### Competitors table (Review step) * **Name**: The competitor's name and auto-fetched logo. * **Website**: The competitor's domain, acting as an external link. * **Identifiers**: Alternate names or aliases AI might use to refer to the brand. * *Tooltip*: "Different ways AI might refer to this brand, like nicknames or abbreviations." * **Actions (⋯)**: A menu to Edit or Delete the competitor row. ### Prompts table (Review step) * **Prompt**: The literal query text that will be sent to the AI models. * **Type**: A badge indicating if the query is "Branded" or "Non-Branded". * *Tooltip*: "Branded prompts mention your company by name. Non-branded prompts are generic industry queries." * **Actions (⋯)**: A menu to Edit or Delete the prompt row. ## What you can do here * **Advance or Return**: Click **Continue** (or press Enter) to save the current step and advance. Click **Back** to return to the previous screen. * **Add competitor**: In the Competitors card, click **Add competitor** to open a drawer and manually add a tracked domain. * **Edit or Delete a competitor**: Click the **⋯** (More) menu on a competitor row to **Edit** (opens a drawer to modify the Name or URL) or **Delete** (removes the competitor). * **Add prompts**: In the Prompts card, click **Add prompts** to open a drawer and generate new AI suggestions, upload a CSV, or type queries manually. * **Edit or Delete a prompt**: Click the **⋯** (More) menu on a prompt row to **Edit** the query text or type, or **Delete** it entirely. * **Retry discovery**: If the background AI generation fails, click **Try again** inside the warning banner to restart discovery. * **Connect GSC**: Click **Connect** on the Google Search Console step to open a Google OAuth window and link a property. * **Configure Schedule**: Click individual AI models or days of the week to toggle them on or off for recurring monitoring. * **Skip initial analysis**: On the Schedule step, click **Skip** to complete onboarding without spending credits on a first run or enabling a recurring schedule. * **Exit Setup**: Click the **X** icon in the top left (if visible) to exit. You can choose **Save for later** to keep the draft or **Delete draft** to discard everything. * **Select a Plan**: On the Pricing popup, click **Choose Starter** or **Start for free** to select a plan, or **Contact sales** to discuss Enterprise. ## Data shown * **Auto-generated profiles**: Brand descriptions, competitor names, and suggested prompts are actively generated by Athena's AI based on the URL you provide. * **Estimated Costs**: The "Cost summary" section mathematically projects your "First run" cost and "Estimated monthly" cost by multiplying your configured prompts, selected models, and selected days. ## Common workflows **Setting up a new brand** 1. Enter your website URL and click Continue. 2. While Athena extracts your brand description in the background, set your target Country and Language. 3. Review the "Brand profile" card, fixing any inaccuracies in the description. 4. Review the "Competitors" card, using the ⋯ menu to delete irrelevant suggestions and "Add competitor" to include missing rivals. 5. Review the "Prompts" card, curating the list of queries to track. 6. Select the days and AI models you want to monitor, then click Continue to finalize. **Manually adding a competitor** 1. On the Review step, navigate to the Competitors card. 2. Scroll past the generated table and click **Add competitor**. 3. In the drawer, enter the competitor's URL and name, then save. **Resuming an abandoned setup** 1. If you leave the page via "Save for later" (or close the tab), you can return via an email link or the sidebar. 2. A "Loading draft..." overlay will appear while your saved progress is retrieved. 3. You are dropped onto the exact step you left off on, with all prior data intact. ## Empty, loading, and error states * **Loading**: You will see a full-screen "Loading draft..." overlay when resuming a saved setup. The app also shows an "entry-loading" spinner while checking billing eligibility. * **Empty Discovery**: If AI fails to scrape your website or find competitors, the UI surfaces a banner stating "Competitor research didn't finish" or "No direct competitors found", alongside a "Try again" button. * **Errors**: Toasts appear for issues like "We couldn't read your website" or "Failed to load draft". * **Blocked Access**: Non-admin users who try to navigate here see a plain screen stating: "Only organization admins can add websites. Please contact your administrator." ## Linked from / links to * **Linked from**: Automatically reached after creating an account (login/signup), the "Create new organization" flow, the "Add Website" button in the organization menu, or a draft-resume link in an email. * **Links to**: Navigates to **Olympus** (the main dashboard) upon completion. The pricing modal links to external **Stripe Checkout** pages or **Cal.com** scheduling pages. ## Common support questions **Why don't I see the "X" button to close the wizard?** Brand-new users who do not yet have a completed Athena dashboard must finish setting up their first website before they can navigate around the app. The "X" button is only shown if you have another fully configured website to fall back to. **What happens if I click "Skip" on the schedule step?** Clicking Skip finishes your website setup but keeps both the initial first-time analysis and your recurring schedule disabled. Athena will not spend any credits until you manually run an analysis or turn on scheduling from the dashboard. **Why are some models locked with a padlock icon?** Certain advanced models (like Grok, Claude, DeepSeek, Meta AI, Mistral, or AI Mode) require a paid Starter or Enterprise plan. On a Free plan, these models are disabled and show an "Available on the Starter plan" tooltip. **If I go back and change my URL, what happens?** If you navigate back to step 1 and change the website URL, Athena will clear the brand description, competitors, and prompts it previously generated and start analyzing the new URL from scratch. # Ads Source: https://docs.athenahq.ai/guides/ads Show sponsored ads captured across ChatGPT, Google AI Mode, and Google Search/AI Overview responses to tracked prompts, and which advertisers are buying them. > [card] [Open in AthenaHQ](https://app.athenahq.ai/ads) > > `app.athenahq.ai/ads` ## Purpose The Ads page helps marketers understand the paid search landscape around their tracked AI queries. When answer engines like ChatGPT and Google serve sponsored advertisements alongside their organic AI answers, Athena captures them. This page reveals which advertisers (including your tracked competitors) are buying ad placements against your tracked prompts, what creative copy or products they are promoting, and how frequently those ads appear over time. This competitive intelligence allows you to monitor who is bidding on your brand and industry terms in the AI era. ## What's on the page ### Page header & Platform tabs The top header includes the "Ads" title with an info tooltip explaining the page: *"Shows sponsored ads captured across ChatGPT and Google responses to your tracked prompts, and which advertisers are buying them."* Next to the title is a set of platform tabs: **ChatGPT**, **AI Mode**, and **Google Search**. Selecting a tab updates the entire page to show only ad data for that specific platform. ### Filter row A customizable filter bar where you can narrow data by **Date Range**, **Topics & Prompts**, **Prompt Tags**, **Personas**, **Locations**, and **Countries**. You can also use the **Views** dropdown to save and load your favorite combinations of filters. ### Ads hero (Ad pressure) The large top card provides a high-level summary of your selected date range: * **Ad pressure**: A percentage metric showing how often ads appeared. It includes the text: *"Sponsored ads ran against \[X] of \[Y] \[Platform] answers to your tracked prompts."* * **View answers with ads**: A clickable link that takes you to the Responses page to see the specific AI answers that carried ads. * **Trend sparkline**: A smooth area chart plotting the number of ads captured per day over your selected date range. * **Top advertisers on your prompts**: A mini leaderboard showing the top 4 advertisers buying ads on your prompts, alongside a progress bar and their ad count. Tracked competitors are badged "Competitor" and your own brand is badged "You." ### Stat rail A row of summary tiles below the hero section: * **Ads captured**: The total number of ads found. For ChatGPT, the tooltip notes: *"Every sponsored ad ChatGPT reported for your tracked prompts, including auctioned placements that did not render."* For Google platforms, the tooltip notes: *"Every sponsored ad captured in these answers. Google returns placements that rendered."* * **Advertisers**: Total distinct advertisers found. * **Competitors advertising**: How many of your explicitly tracked competitors bought ads. * **Surface-specific 4th tile**: Depending on your platform tab, this fourth tile changes: * **ChatGPT - Ads shown**: Includes a breakdown of ads actually rendered vs reported as "not shown." Tooltip: *"Shown means the placement rendered in the captured response. ChatGPT can also report an auctioned placement that did not render, which still reveals who is bidding."* * **Google Search - Inside the AI Overview**: Breaks down ads found directly inside the AI Overview vs standard search results on the same page. Tooltip: *"Google places some ads inside the AI Overview itself and others in the search results on the same page. Both are captured; this splits them."* ### Ad click warning banner On the Google platforms tabs, a yellow warning banner appears above the creatives table: *"Warning: Clicking an ad link may result in a charge to the advertiser."* This ensures users know that clicking out to a live creative URL interacts with a real ad network. ### Advertisers table A paginated table titled "Advertisers" with a subtitle explaining *"Who is buying ads against your tracked prompts."* An info tooltip notes: *"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."* * **#**: The advertiser's numerical rank by ad volume. * **Advertiser**: The name and domain of the advertiser. May include a "You" or competitor badge. * **Ads**: The number of ads captured for this advertiser, with a relative visual bar. * **Shown**: The number of ads that actually rendered (appears on the ChatGPT tab only). * **Prompts**: The number of distinct tracked prompts that triggered an ad from this advertiser. * **Last seen**: The most recent date an ad from this advertiser was captured. * **Expand (Chevron icon)**: Clicking the arrow expands the row to reveal a detailed drilldown. Hovering over it says *"Show prompts for \{advertiser}"* or *"Hide prompts for \{advertiser}."* **Advertiser Drilldown**: Expanding a row reveals two additional panels: * **Prompts triggering these ads**: A list of specific prompts the advertiser showed up on. Clicking a prompt here drills down to the Responses page filtered to those exact ads. * **Latest creative**: The most recent headline, body text, and destination link used by that advertiser. ### Creatives / Sponsored products table The bottom table lists the actual ad copy or products promoted. On the ChatGPT and Google Search tabs, it is titled "Top creatives". On the AI Mode tab, it is titled "Sponsored products". An info tooltip explains: *"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 responses, not clicks, conversions, spend, or performance."* * **#**: The creative's numerical rank. * **Creative** (or **Product**): The ad's headline and body text. If a URL is captured, it acts as a clickable outbound link. AI Mode products include a thumbnail image. * **Advertiser**: The name and domain of the advertiser who ran the creative. * **Placement**: Appears on the Google Search tab only, indicating whether the ad was in the "AI Overview" or "Google Search" results. * **Captures**: How many times this exact creative was captured by Athena. * **Shown**: How many times the creative actually rendered (ChatGPT tab only). * **Prompts**: How many distinct tracked prompts triggered this creative. * **Last seen**: The most recent date the creative was captured. ## What you can do here * **Switch ad platforms**: Click the ChatGPT, AI Mode, or Google Search tabs at the very top of the page to swap which platform's ad data you are analyzing. * **Filter and search**: Use the top filter bar to narrow data by date range, specific prompts, locations, or personas. Use the search box above the Advertisers table to find specific domains, or the search box above the Creatives table to search for specific ad copy. * **Toggle All / Tracked advertisers**: Above the Advertisers table, click "Tracked" to hide unknown domains and only show ads bought by your brand or your tracked competitors. * **View answers with ads**: Click the "View answers with ads" link in the hero card (or click the "Ads captured" stat tile) to navigate directly to the Responses page, pre-filtered to show only answers that contained ads for the selected timeframe and platform. * **Drill into an advertiser's prompts**: Click any row in the Advertisers table (or the chevron icon on the right) to expand it. In the expanded view, click any of the prompts listed to navigate to the Responses page, pre-filtered to show exactly where that advertiser's ad appeared for that prompt. * **View a live ad landing page**: Click on a hyperlinked title inside the Creatives table (or in an advertiser's "Latest creative" detail panel) to open the destination landing page in a new browser tab. * **Dismiss the click warning**: Click the "X" icon on the warning banner to dismiss it. This preference is saved in your browser. * **Load more data**: Scroll to the bottom of the Advertisers or Creatives tables and click "Load more advertisers" / "Load more creatives" to fetch the next page of results. * **Manage saved views**: Click the "Views" dropdown in the filter bar to save your current filters as a new view, update an existing view, load a saved view, set a default view, or delete a view. ## Data shown The data on this page reflects sponsored advertisements captured directly alongside or inside the AI responses generated for your tracked prompts. This includes text ads, sponsored links, and AI Mode product carousels. The metric counts reflect how often Athena observed the ad during a prompt run. **They do not represent global impressions, clicks, conversions, or actual ad spend.** Advertiser identities are derived from the ad's destination URL root domain or the brand name provided by the platform. ## Common workflows **Investigating who is bidding on your keywords** 1. Go to the Ads page and set your desired Date Range in the filter bar. 2. In the Advertisers table, look at the top-ranked domains to see who is capturing the most ad real estate. 3. Click a competitor's row to expand it. 4. Review the "Prompts triggering these ads" list to see exactly which of your tracked queries they are successfully bidding against. **Reviewing competitor ad copy** 1. Scroll down to the Top Creatives table. 2. Type a competitor's name into the table's search box to filter the list. 3. Review the "Creative" column to read the headlines and body copy they are currently running. 4. Click the creative's title link to visit their landing page and review their destination experience. ## Empty, loading, and error states * **Empty (No ads data yet)**: If your tracked prompts have never returned a sponsored ad, the page displays a large illustration with the message "No ads data yet" and a button to "Manage prompts." Tracking more commercial prompts increases the likelihood of capturing ads. * **Empty (Date range has no ads)**: If your prompts have historically captured ads but none were found in your currently selected date range, the page displays a "No \[Platform] ads in this date range" message, suggesting you switch tabs to check other platforms. * **Empty tables**: If a search or filter yields no results in a specific table, it will display "No advertisers found" or "No creatives match \[your search]." * **Loading**: While the dashboard or tables fetch data, skeleton gray bars appear in place of the charts, text, and table rows. A full-page spinner appears if the system is verifying your plan access. * **Error**: If the dashboard fails to load, a red warning card appears stating "Couldn't load ads data" with a "Try again" button. If a specific table or advertiser drill-down fails, a localized "Couldn't load..." message and "Try again" button appears there. If the page cannot verify your subscription plan, a full-page "Something went wrong / Couldn't verify access" screen is shown. ## Linked from / links to * **Linked from**: You can reach this page by clicking "Ads" in the main left-hand navigation sidebar, or via shared links/saved views from your team. * **Links to**: The page links heavily to the **Responses** page (via "View answers with ads" and prompt drilldowns) to show the raw AI answers. It links to the **Prompts** page via the empty state's "Manage prompts" button. Creative links point outward to external advertiser landing pages. ## Common support questions **Why don't I see the "Shown" column on the Google tabs?** Google platforms only return ad data for placements that successfully rendered on the screen. Because every ad captured on Google was "shown," the column is unnecessary. ChatGPT, however, occasionally reports "auctioned" placements in its data that ultimately did not render in the UI, so the ChatGPT tab splits "Ads" (bids) from "Shown" (rendered). **Why am I seeing a warning about charging the advertiser?** Clicking an ad link in the Creatives table takes you to the actual live URL provided by the ad network. Because this is a real ad link, clicking it may register as a paid click for the advertiser. We provide the warning so you are aware before clicking competitor links. **Why does an advertiser show up as "Unknown"?** Athena attempts to identify advertisers by the root domain of their ad link. Sometimes, ad platforms (like Google AI Mode) return opaque click-tracking URLs without revealing the true destination domain, or they only provide a plain text brand name. When the system cannot confidently resolve a domain or name, the ad is grouped into a shared "Unknown advertiser" bucket. **Do these numbers match my Google Ads account?** No. The captures and ad counts on this page measure exposure specifically within the AI responses Athena gathered for your tracked prompts. They are competitive visibility metrics, not a reflection of global impressions, clicks, or ad spend from an ad network dashboard. # The AthenaHQ Crawler (/bot) Source: https://docs.athenahq.ai/guides/bot A public, unauthenticated reference page explaining AthenaHQ's crawler identity, user agent, and access behavior so IT admins can allow it through firewalls. > [card] [Open in AthenaHQ](https://app.athenahq.ai/bot) > > `app.athenahq.ai/bot` ## Purpose The AthenaHQ Crawler page is a public, unauthenticated reference page designed for IT administrators and security teams. It explains what the AthenaHQ site auditor is, what user-agent strings it uses, and how it behaves when requesting pages. Because IT admins typically discover this page by following the URL found in their server or firewall logs, they do not need an AthenaHQ account to view it. The page provides the technical details they need to safely allowlist AthenaHQ's crawler so it can successfully audit their organization's web properties. ## What's on the page **Page heading** Introduces the crawler's purpose: AthenaHQ reads public pages to check what AI assistants can see when answering questions about a brand. It checks for JavaScript dependencies, title tags, structured data, and whether AI crawlers are allowed to read the content. **How to identify us** Shows the exact primary user-agent string the crawler sends (`AthenaHQ-Bot/1.0 (+https://app.athenahq.ai/bot)`). It explains that the audit also sends a small number of requests mimicking real AI crawlers (like ChatGPT, Claude, and Perplexity) and standard browsers to accurately measure how the site's firewall treats them. It also notes that AthenaHQ does not publish a list of fixed IP addresses. **If your firewall turns us away** Shows the fallback browser user-agent string. It explains that if a site's bot protection blocks the primary AthenaHQ bot, the crawler will retry the request once using a standard browser user agent to ensure the customer's audit can finish. **What we do and do not do** A bulleted list clarifying the crawler's operational boundaries: * Audits happen in short bursts of a few dozen requests over a few seconds, not a steady trickle. * The crawler reads `robots.txt`, but it will not stop auditing if the file disallows the AthenaHQ user agent, because the site owner specifically requested the audit. * The crawler does not submit forms, sign in, or try to access authentication-gated content. * The crawler does not collect personal data. **Contact information** Provides a direct email link to AthenaHQ support for anyone with questions about the traffic they are seeing. ## What you can do here * **Email support:** Click the `support@athenahq.ai` link at the bottom of the page to open your email client addressed to AthenaHQ support. * **Copy user agents:** IT admins can manually copy the provided user-agent strings to paste into their web application firewall (WAF) or bot-management allowlists. ## Data shown This page displays static technical documentation. It does not display any customer-specific data, metrics, or tracked content. ## Common workflows **Investigating and allowlisting the crawler** 1. An IT or security admin notices a burst of traffic or blocked requests in their firewall logs containing the `AthenaHQ-Bot` user agent. 2. The admin copies the URL from the user-agent string and opens this page in their browser. 3. They read the documentation to verify the crawler's legitimacy and purpose. 4. They copy the `AthenaHQ-Bot` user-agent string and add it to their firewall's allowlist so future audits requested by their marketing team succeed. ## Empty, loading, and error states Because this is a static text page, there are no loading states, empty states, or error states. ## Linked from / links to * **Linked from:** This page is not linked anywhere within the logged-in AthenaHQ application navigation. Users arrive here exclusively by typing or clicking the URL embedded in the crawler's user-agent string. * **Links to:** The `support@athenahq.ai` link opens the user's default email client. ## Common support questions **Why is this bot ignoring our robots.txt Disallow rule?** We do not treat a Disallow for our own user agent as a stop command because the audit runs only when the site's owner (your organization) explicitly requested it via their AthenaHQ account. If you want to stop the crawler, you can ask the account holder to remove the site, block our user agent at your edge firewall, or contact us. **Do you have a list of IP addresses we can allowlist instead of the user agent?** No. We do not publish fixed IP addresses. Firewall rules must match the user-agent string. If your organization requires a stronger identity guarantee than a user-agent string, the page advises the AthenaHQ account holder to contact us to arrange an alternative. **Why am I seeing requests from AI crawlers coming from your infrastructure?** To accurately measure whether your site's firewall rules admit AI crawlers, we send a small number of probes to your homepage carrying those exact crawlers' user agents. Those specific probes are the measurement itself, so they cannot announce themselves as AthenaHQ. **Why did you retry the request as a normal web browser?** If your bot protection turns away the declared `AthenaHQ-Bot` user agent, we retry the request once as a standard browser. We do this so the customer's requested audit can still finish. However, we prefer you allowlist our bot so our traffic stays identifiable in your logs. # Brand Profile Source: https://docs.athenahq.ai/guides/brand-profile Central hub for managing a website's brand identity, brand attributes/traits, content memories, brand voice kits, and technical AI-crawler settings (llms.txt, sitemap, schema, AI accessibility). > [card] [Open in AthenaHQ](https://app.athenahq.ai/brand-profile) > > `app.athenahq.ai/brand-profile` ## Purpose Use Brand Profile to manage your brand identity, the traits you track in AI responses, writing preferences, and brand kits. Attributes measure how AI describes your brand; Content Memories and Brand Kits guide content generation. Editing attributes, Content Memories, and Brand Kits requires Brand Knowledge write access. Generating technical artifacts requires Content write access. The Technical tab provides diagnostic tools and files you can publish on your site; an llms.txt file does not control crawler access or guarantee how external AI models describe you. ## What's on the page **Page header** Displays the title "Brand Profile" and the subtitle "Your brand identity in one place". If a user lacks the necessary write permissions, a "View-only" banner will appear here. **Tabs** The page is split into five tabs: * **General:** Contains basic identity fields like "Brand Name", "Industry", "Website logo", "Brand Description", "Base location", and "Default language". * **Attributes:** Manages the specific brand traits tracked across AI responses. It includes a table of active attributes, a collapsible section for deactivated attributes, and conditionally shows an attribute backfill bar at the bottom of the screen. * **Content Memories:** (Only visible if the customer's plan includes this feature). Manages writing preferences and rules that guide Athena's AI content generation. * **Brand Kits:** Manages generated brand voice guidelines used for maintaining a consistent tone and style. * **Technical:** Houses controls for configuring AI-crawler interactions, including LLMs.txt files, Sitemaps, Schema validation, and AI Accessibility checks. ### Active attributes table (Attributes tab) Lists the website's currently active brand traits. Traits are neutral; Athena tracks both positive and negative mentions of the same trait. * **Attribute:** The neutral trait or attribute name being tracked for the brand. ### Deactivated attributes list (Attributes tab) A collapsible list located below the active attributes table. * **Deactivated attribute name:** An attribute the user previously deleted. It can be restored to active status. ### Content Memories table (Content Memories tab) Lists global writing preferences. * **Memory:** The writing preference or rule text (e.g., "Stop using em dashes"). * **Category:** Optional classification of the memory (Style, Formatting, Terminology, Tone, Structure, or Other). * **Status:** A toggle switch showing whether the memory is currently active and being applied to future content generation. ### Brand Kits table (Brand Kits tab) Lists all brand voice kits available for the website. * **Name:** The brand kit's name. * **Status:** The kit's current state. This can be "Draft" (setup is incomplete), "In progress" (generating), "Retry" (generation failed), "Default" (currently the active default kit), or a "Set as default" button for any completed, non-default kit. ## What you can do here **General actions** * **Upload logo:** Customers can drag and drop an image or click to open a file picker to upload a square brand logo (max 5MB; JPEG, PNG, GIF, WebP, or SVG). * **Save changes:** Persists any edits made to the General tab's form fields. **Attribute actions** * **What changed about brand traits:** Clicking the `?` info icon opens a tooltip explaining: "What changed? Brand traits no longer have a fixed positive or negative sentiment. Each trait is now tracked for both positive and negative mentions in AI responses." * **Create new:** Opens a dialog to enter a new neutral attribute name. Clicking **Add** saves it to the catalog. Note: Customers are capped at 12 active attributes. * **Delete attribute:** Found inside the `⋯` menu on an active attribute row. Clicking **Delete** deactivates the attribute and moves it to the "Deactivated attributes" list. * **Restore:** Found next to items in the "Deactivated attributes" list. Reactivates the attribute and queues an "Added" backfill change. * **View Changes:** Located on the floating Attribute Backfill bar at the bottom of the screen. Opens a dialog listing pending attribute changes with the ability to **Dismiss from list** individually, or **Dismiss all**. * **Backfill:** Located on the Attribute Backfill bar. After selecting a date range, clicking this starts a credit-charged workflow that reanalyzes historical responses using the updated attribute catalog. The button's tooltip will read: "Reanalyze N responses with updated attributes (X credits)". **Content Memory actions** * **Add memory:** Opens a dialog to write a new content memory. Clicking **Save** adds it to the table. * **Toggle Status:** Clicking the switch in the status column enables or disables that specific memory. * **Edit memory:** Found inside the `⋯` menu on a memory row. Opens the edit dialog pre-filled with the memory's details. * **Delete memory:** Found inside the `⋯` menu. Opens a confirmation dialog: "Are you sure you want to delete this memory? This action cannot be undone." **Brand Kit actions** * **Create New:** Opens the Setup, Source notes, Documents, and Review steps to generate a new brand kit. You can upload up to five PDFs as Style guide or Brand Context documents. * **Edit brand kit:** Open a completed kit to edit its guidelines directly, then click **Save**. Open **View sources** to review its inputs. To rewrite the guidelines from changed inputs, click **Regenerate guidelines** and confirm. Draft kits reopen at their saved setup step. * **Set as default:** Clicking this button in the Status column assigns the kit as the primary brand voice. * **Retry:** Appears if a brand kit generation fails; clicking it attempts generation again. * **Delete brand kit:** Found inside the `⋯` menu. Opens a confirmation dialog: "Are you sure you want to delete "\{brandKitName}"? This action cannot be undone." **Technical actions** * **Generate llms.txt:** Uses AI to generate an `llms.txt` file for the website. * **View llms.txt:** Opens a dialog where the user can preview, manually edit, view the raw output, **Regenerate**, or **Save** the file. * **Sitemap Generate:** Submits a domain path to crawl and generate a new sitemap. * **View Sitemap:** Clicking a generated sitemap row opens a dialog displaying the paginated XML. From here, users can **Copy XML**, **Download XML**, or **Delete sitemap**. * **Validate Schema:** Submits a URL to check for valid Schema.org JSON-LD data. Users can also click example domains to try it out. * **Check AI accessibility:** Opens a dialog evaluating whether AI models (like ChatGPT, Claude, Gemini, Perplexity, Copilot, Grok, DeepSeek, Rufus, AI Mode, and AI Overviews) can crawl the site based on robots.txt and live probes. ## Data shown * **Brand Details:** The website's core identifying information (name, logo, description, geography, industry). * **Attributes:** The user-defined list of traits Athena tracks when analyzing search responses about the brand. * **Content Memories:** Saved writing preferences applied during AI content generation. * **Brand Kits:** Saved voice and tone guidelines generated from user-provided URLs and documents. * **Technical artifacts:** Generated sitemaps, generated `llms.txt` configurations, schema validation results, and live AI accessibility statuses fetched directly from the customer's domain. ## Common workflows **Add a new brand attribute and backfill history** 1. Go to the **Attributes** tab. 2. Click **Create new**. 3. Type a neutral trait name (e.g., "Pricing transparency") and click **Add**. 4. The new attribute appears in the active attributes table, and a pending "Added" change is queued in the floating backfill bar at the bottom of the screen. 5. Select a date range in the backfill bar and click **Backfill** to reanalyze historical responses with the new attribute (costs credits). **Replace an existing attribute (rename workaround)** 1. Go to the **Attributes** tab. 2. Open the `⋯` menu for the attribute you want to replace. 3. Click **Delete** to deactivate it. 4. Click **Create new**, enter the corrected name, and click **Add**. 5. If you want to reanalyze historical responses, review the date range and credit cost in the bottom bar, then run **Backfill**. This step is optional. **Create a new Brand Kit** 1. Go to the **Brand Kits** tab and click **Create New**. 2. Complete the setup wizard by providing a name, blog URL, custom notes, and uploading reference documents. 3. Review the summary step and click **Generate** to produce the brand voice instructions. **Generate and review llms.txt** 1. Go to the **Technical** tab. 2. Click **Generate llms.txt** and wait for the success toast to appear. 3. Click **View llms.txt** to open the preview dialog. 4. Edit the markdown if needed and click **Save**. ## Empty, loading, and error states * **Empty:** If no data exists, tabs display empty states with brief instructions (e.g., "No attributes yet", "No content memories yet", "No brand kits yet"). * **Loading:** Skeleton placeholders appear in lists and tables while data loads. Action buttons display animated spinners while processing. * **Error:** Actions that fail trigger a red toast notification (e.g., "Failed to update attributes", "Failed to fetch sitemaps"). In the Schema section, an inline orange banner will explain if the fetch failed or if the JSON-LD is invalid, providing tips on how to fix it. ## Linked from / links to * **Linked from:** The main sidebar navigation (Brand Profile), the "Brand Guidelines" onboarding tour step, and the "Manage brand kits" link inside the content editor's Brand panel. * **Links to:** External documentation for schema.org types (from the Schema validator) and sitemaps.org index protocols (from the Sitemap section). ## Common support questions **How do I change whether an attribute is positive or negative?** Brand traits in Athena no longer have a fixed positive or negative sentiment. Instead, you enter a neutral trait (like "Customer Service"), and Athena will automatically track and report when it is mentioned positively and when it is mentioned negatively. **Why can't I rename an attribute?** Attributes cannot be renamed inline. Delete the old trait, then click **Create new**, enter its replacement, and click **Add**. You can optionally use the Backfill bar to reanalyze historical responses after reviewing the date range and credit cost. **Does deleting an attribute rewrite my historical data?** No. Deleting an attribute deactivates it for future analysis. Use the optional Backfill action to reanalyze historical responses with the updated attribute catalog. Backfill runs in the background and costs one credit per 100 responses, rounded up. **Why can't I add more than 12 attributes?** To ensure AI analysis remains highly accurate and focused, accounts are capped at a maximum of 12 active attributes. If you hit this limit, you must delete an existing attribute before adding a new one. **Why is the "Content Memories" tab missing?** The Content Memories feature is tied to specific subscription plans. If the customer's plan does not include this feature, the tab will be entirely hidden from their Brand Profile. # Competitors Source: https://docs.athenahq.ai/guides/competitors Track and manage competitor brands (and your own website's identity), review AI-visibility comparisons, discover new competitors, and manage deleted competitors. > [card] [Open in AthenaHQ](https://app.athenahq.ai/competitors) > > `app.athenahq.ai/competitors` ## Purpose The Competitors page is the central hub for managing the brands you want to track across AI search engines. It allows you to configure exactly how AI detects mentions of your own brand and your competitors by managing keywords (identifiers) and website domains. Beyond configuration, this page serves as a performance dashboard. It ranks your tracked competitors by their visibility, surfaces new competitor brands the AI engines are talking about, and offers deep-dive head-to-head comparisons to help you understand where your brand leads or lags. ## What's on the page The page is organized into three tabs: **Tracked competitors**, **Discovered competitors**, and **Deleted** (which only appears if you have previously removed competitors). ### Identifier Suggestions Bar If our system detects new potential keywords (identifiers) for your tracked brands based on how AI models are responding, a suggestion bar appears above the tables. It shows the number of suggestions and the suggested keyword, letting you quickly click **Add** or **Dismiss**. You can also click **Review all** to open a modal that lists all suggestions grouped by competitor. ### Pending Changes Bar If you edit a brand's identifiers, domains, name, or case-sensitivity, those changes are queued up. A bar appears showing a summary (e.g., "2 pending changes") with a **Review & backfill** button. If a backfill is currently running, this bar shows live progress (e.g., "Reanalyzing X of Y responses"). ### Tracked competitors table This is the main view showing your own website alongside every competitor you are currently monitoring. * **(checkbox)**: Select rows to perform bulk actions (like deletion or exporting data). * **Name**: The name and logo of the competitor. Your own brand is pinned to the top and has a "You" badge. Clicking a competitor's name opens a head-to-head comparison. * **Visibility**: Shows the brand's rank and share-of-voice percentage. *Tooltip: "Visibility - Based on mentions across tracked AI responses. Rank: Position among tracked brands. Share: Percent of all tracked mentions. Last 30 days"* * **Website**: The primary URL for the brand. Features a click-to-copy tooltip and an external link icon. Shows " - " if no URL is recorded. * **Identifiers**: A dropdown showing the keywords used to detect the brand in AI responses. *Tooltip: "We use these keywords to identify your brand in AI responses"* * **Domains**: A dropdown showing the web domains used to track citations. \*Tooltip: "Domains used for citation tracking. Supports wildcards (e.g. *.acme.com)"* * **Added on**: The date the competitor was added to your workspace. For competitors with a recorded activity history, this date is underlined and clickable. ### Discovered competitors table When on the **Discovered competitors** tab, this table shows AI-surfaced brands that frequently appear alongside your tracked topics but aren't currently being monitored. * **Competitor**: The candidate's name and URL. Clicking the row expands it to show the specific AI response and text snippet that mentioned them. * **Mention %**: *Tooltip: "Percentage of AI responses that mention this competitor"* * **Mentions**: *Tooltip: "Total number of times this competitor was mentioned across all responses"* * **Mentioned in**: *Tooltip: "Unique responses mentioning this competitor out of total analyzed"* * **Last seen**: The date they were most recently mentioned. * **Actions**: An **Add** button to start tracking them, or an "Added" label if you already track them. ### Deleted competitors table When on the **Deleted** tab, this table lists soft-deleted competitors. It contains the **Name**, **Website**, and an **Actions** column with a **Restore** button. ### Drilldowns * **Head-to-Head Comparison**: Clicking a competitor's name (or selecting **Compare performance** from the actions menu) opens a side drawer titled "\[Your brand] vs \[Competitor]". It features side-by-side metrics (Share of voice, Mention rate, Citation rate, Average position), a "Model breakdown" showing how often each AI engine mentions them versus you, and a "Where \[Competitor] leads" section highlighting topics where they outperform you. From here, you can click **View heatmap** or **View mentions** to drill deeper into the data. * **Competitor History**: Clicking an underlined date in the "Added on" column opens a "\[Competitor] history" drawer, showing a timeline of who added, edited, or modified the competitor and when. * **Expanded Discovery Evidence**: Clicking a row in the Discovered tab drops down a list of AI response snippets. Clicking one of those snippets opens the full AI response drawer to show exactly how the competitor was discussed. ## What you can do here * **Add competitors**: Click **Add competitor** to open a drawer. You can add a single brand manually, switch to the "Multiple" tab to paste a list of names/URLs, or upload a CSV/Excel file for bulk importing. The system can automatically use AI to generate tracking keywords for bulk imports. * **Edit Identifiers**: Click the Identifiers cell for any brand to open a dropdown. Here, you can type to add new keywords, hover over existing ones to delete or edit them, and toggle **Match case** to make matching case-sensitive. * **Edit Domains**: Click the Domains cell to add or remove tracked web domains. Hovering over a non-primary domain reveals a **Make primary** button. * **Rename a competitor**: Click the three-dot menu and select **Edit** to change the company's display name. A prompt will ask if you want to automatically swap the old name out of the identifier list. * **Delete / Restore**: Use the three-dot menu to **Delete** a competitor (which requires confirmation). If you make a mistake, an undo toast appears for 8 seconds. Alternatively, go to the Deleted tab and click **Restore**. * **Bulk Delete & Export**: Select multiple rows using the checkboxes. A command bar will appear at the bottom allowing you to **Delete** them all at once or **Export** their data (Name, URL, Identifiers) to a CSV file. * **Review & Backfill Changes**: When you make edits (like adding a new identifier), they apply to *future* AI responses automatically. To apply them retroactively, click **Review & backfill** in the pending changes bar. This opens a dialog where you can review your queued edits, pick a date range, and click **Start backfill** (which consumes credits) or **Skip backfill** (to clear the queue without historical scanning). You can also **Undo** edits from this dialog. ## Data shown * **Tracked/Discovered Competitors**: Populated from your workspace configuration and our AI discovery pipeline, which constantly analyzes your tracked AI responses for unknown brands. * **Visibility Metrics**: Sourced from your tracked AI responses over the last 30 days. * **Change Queue / Audit History**: Sourced from your workspace's activity logs and pending edit queue. ## Common workflows **Adding multiple competitors via file upload:** 1. Click **Add competitor** in the top right. 2. Select the **Multiple** tab in the drawer. 3. Under "Upload a CSV or Excel file", click the file input and upload your list. (You can click "Download Template" first if you need the format). 4. Review the preview list that appears. The system will alert you to duplicates or URLs you already own. 5. Click **Add \[X] competitors** to save them to your tracked list. **Updating a brand's tracking keywords (Identifiers) and backfilling:** 1. Find the brand in the Tracked competitors table. 2. Click its **Identifiers** dropdown, type a new keyword, and click **Add**. 3. A pending changes bar appears at the top of the screen. Click **Review & backfill**. 4. In the dialog, verify your changes. If you want the keyword to apply to older AI responses, ensure the time range is set correctly and click **Start backfill**. **Comparing your brand against a rival:** 1. Locate the rival in the Tracked competitors table. 2. Click their name (or use the three-dot menu and select **Compare performance**). 3. Review the "\[Your brand] vs \[Competitor]" drawer to see side-by-side share of voice and topic gaps. 4. Click **View heatmap** at the bottom of the drawer to jump directly to a detailed visual breakdown of their performance. ## Empty, loading, and error states * **Empty states**: If you haven't selected a website in the sidebar, a full-page "No website selected" message appears. If you have no discovered or deleted competitors, those tabs display "No discovered competitors yet" or "No deleted competitors". * **Loading states**: While fetching data, the tables show animated skeleton rows. A blue loading bar traverses the top of the page during navigation. * **Error states**: If metrics fail to load, the Visibility column simply shows "Unavailable". If the head-to-head comparison drawer partially fails, an amber banner appears with a "Retry" button. ## Linked from / links to * **Linked from**: Users generally navigate here directly from the main sidebar navigation. * **Links to**: The Head-to-Head comparison drawer contains buttons linking directly to the **Heatmap** and **Responses** pages, automatically pre-filtered to focus on that specific competitor. ## Common support questions **Why is my own company in the competitors list?** Your own brand is included (pinned at the top with a "You" badge) so you can manage your own identifiers and domains exactly the same way you manage your rivals. This ensures the system knows precisely how to detect mentions of your company. **What does the "Match case" toggle do in the Identifiers dropdown?** By default, identifiers are case-insensitive (e.g., "Apple" matches "apple"). If your brand name is a common word (like "Apple" or "Polo"), you can turn on "Match case" so the system only counts mentions when the capitalization matches exactly, reducing false positives. **I added a new identifier, but my past mentions didn't update. Why?** Edits to identifiers or domains apply to *new* AI responses automatically. To apply them to older responses, you must click **Review & backfill** in the bar that appears at the top of the page, select a date range, and click **Start backfill**. **Why is the "Make primary" button missing for some domains?** You cannot promote a domain to be primary if it uses wildcards (e.g., `*.acme.com`). The primary domain must be a specific, exact website URL. **What happens if a competitor doesn't have a website?** That is completely fine. When adding a competitor manually, you can just provide their name. The system will use the name as the primary identifier for tracking mentions. # Content Source: https://docs.athenahq.ai/guides/content Manage, generate, import, and publish website content in a spreadsheet-style workspace with AI agent columns, custom columns, and metrics tracking. > [card] [Open in AthenaHQ](https://app.athenahq.ai/content) > > `app.athenahq.ai/content` ## Purpose The Content page is a spreadsheet-style workspace where you can manage, generate, import, and publish your website's content. It centralizes your workflows, allowing you to track live URLs, optimize existing pages, snipe competitors' highly-cited content, or draft new articles from scratch. Beyond basic organization, you can group content into different sheets and add custom columns - including AI agent columns that generate insights or copy automatically. The page also features a calendar view to visualize your publishing schedule and an aggregate metrics footer to monitor overall performance, such as citations and traffic. ## What's on the page ### Page header / Sheet tabs Located at the top of the page, this section lets you switch between different sheet views of your content pool. The default "All content" tab shows all items, while additional tabs represent custom sheets you've created. You can drag and drop tabs to reorder them. The "+" icon allows you to add a "New sheet". ### Filter bar A set of controls to narrow down the visible content rows. You can filter by: * **Content type**: Restricts rows by their origin type (e.g., Draft, Snipe, Optimize). * **Published status**: Filters by whether the content is published or unpublished. * **Content opportunity**: Filters rows flagged as content opportunities. * **Attribution status**: Filters by whether the page is included or excluded from your attribution metrics. * **Search**: A text input to find specific titles or URLs. * **Models**: Restricts citation and metric data to specific AI models. * **Prompts**: Restricts metrics to selected tracked prompts. * **Competitors**: Contextual filter for metrics computation. * **Personas**, **Locations**, **Countries**: Filters metrics based on audience segments. * **Website mentioned**: Filters metrics by whether your website appeared in the response. * **Prompt status** and **Prompt tags**: Filters rows based on prompt metadata. * **Date range**: The time window used for computing citations, traffic, and search positions. * **Custom column filters**: Enables filtering on your user-defined spreadsheet columns (e.g., text contains, date before/after, checkbox status). ### All / In progress / Published tabs Quick-access tabs above the spreadsheet to toggle the view between all your tracked content, items that are actively being drafted or optimized, and items that are finalized and live. ### Content Spreadsheet The main data grid listing your content items. It supports sorting, resizing, column reordering, and inline editing. **Columns:** * **Checkbox**: Used to select rows for bulk actions. * **Content**: Shows the title of the content, a badge denoting its type (e.g., Draft, Snipe, Optimize, Slice), its current status, and acts as a button to open the content editor sidebar. * **Progress**: Displays the generation or publishing state of the row. * **URL**: The live or tracked web address for the content. * **Metrics**: A configurable column displaying a selected performance metric. You can change what it shows using the column header menu. It offers the following metric groups and tooltips: * AI citations: "Freshness score", "Citation %", "Citations" * AI positions: "Google ranking", "GEO ranking" * Organic search: "Clicks", "Impressions", "CTR" * Site analytics: "Traffic", "Bounce rate", "Engagement rate", "Avg duration", "AI traffic" * **Created**: The date the row was added to the hub. * **Updated**: The date the row was last modified (hidden by default). * **Custom columns**: User-created columns to store basic data types like Text, Number, Date, Checkbox, Link, or Multi-select (Tags). * **Approval**: Displays whether the row is approved, along with the designated approver and a timestamp. * **OG image**: Shows a generated Open Graph preview card for the page. * **Web Search**: Shows results from an AI-executed web search based on a custom query. * **Cited Sources**: Lists the top sources cited by AI models for the prompts associated with this row. * **Freshness Score**: A calculated score indicating how recent the cited sources are for this topic. * **Analyze Source**: Contains an AI-generated analysis of links provided in other columns, driven by a custom prompt. * **Citation Freshness**: Shows how the citation rate for this page is trending compared to the previous date period. * **Athena Agent**: A custom AI column that evaluates a provided prompt - optionally referencing other columns or your Knowledge Base - to generate text. It writes in your Brand Kit's voice and follows your rules unless you turn that off for the column. ### Calendar view An alternative to the spreadsheet that plots your content items on a calendar based on their creation or publish dates. You can switch between day, week, month, and year layouts. Events are color-coded by content type. ### Aggregate metrics footer A pinned bar at the bottom of the spreadsheet that calculates total citations, traffic, search console clicks, and ranking averages across all the published rows currently visible in your filtered view. Clicking on it opens a drawer with deeper time-series charts and topic breakdowns. ### Content editor sidebar/overlay A slide-out panel that opens when you click a content row. It contains tabs for writing or reviewing the article ("Content"), viewing the AI-generated outline ("Brief"), managing page details ("Metadata"), and reviewing AI column outputs ("Agents"). It includes options to publish, export, share, or view the document's version history. ### Create menu A primary "Create" button that opens a dialog to initiate new workflows. ### Import dialogs Accessible via the "Import" button, these modals allow you to ingest content from external sources: * **CSV Import**: Upload a file and map its headers to your columns. * **Domain Import**: Discovers pages on your site using your sitemap or Google Analytics, allowing you to select which URLs to track. ### CSV export dialog Triggered by the "Export as CSV" button, this dialog lets you choose which columns to include in your downloaded CSV file, rename the column headers for the export, and preview the output. ### Column dependency / workflow dialog A visual workflow canvas opened from the custom column menus. It displays a flowchart of how your agent columns feed data into one another, allowing you to trace dependencies and circular errors. ### Remediation Drafts (Oracle inbox rows) Remediation drafts retained from older Oracle runs can appear as rows in the spreadsheet. Current Oracle findings are reviewed in Oracle; acknowledging a finding does not automatically create or publish a correction. **Columns:** * **Checkbox**: For row selection. * **Content title**: The title of the page being corrected, or "Drafting…" if it is still generating. * **Status**: Indicates if the draft is "Approved", "Dismissed", "Drafting", or "Pending review". * **Discrepancies**: The number of factual errors this draft addresses. * **Actions**: Inline buttons to "Preview", "Approve", "Dismiss", or "Open" (once approved). ## What you can do here ### Add and organize content * **Create**: Click the "Create" button to open the "Choose an action" dialog. Select a brand kit and a sheet selector, then choose a flow: "Write" (for new AI-optimized drafts), "Optimize" (for improving existing pages), "Snipe" (for targeting a competitor's page), "Slice" (for breaking content into multiple pieces), or "Blank editor" (for a clean writing slate). * **Import CSV**: Click "Import" then "Import CSV" to upload a spreadsheet of URLs or content data and map them to your columns. * **Domain Import**: Click "Import" then "Domain Import" to scan your website and select discovered URLs to track. * **Manage sheets**: Click the "+" icon next to the tabs to create a "New sheet". You can copy existing content into it and prepopulate it with agent columns. Click the dropdown arrow on any sheet tab to "Rename", "Duplicate", or "Delete" that sheet. * **Customize columns**: Click "Columns" in the top right to open the column picker and toggle visibility. Use the "Add column" option to create new text, number, date, or AI agent columns. ### Manage column settings Click the dropdown arrow on any custom column header to reveal its menu: * **Rename**: Change the column's display name. * **Edit Settings / Edit Prompt / Edit Query**: Update the configuration or instructions driving an agent column. * **Edit Approvers**: Change who is authorized to check off an Approval column. * **Bulk actions**: Run an agent across multiple rows by selecting "Bulk Athena Agent", "Bulk Search", "Bulk Retrieve", or "Bulk Analyze". * **Delete column**: Permanently removes the column and its data. You will receive an "Are you sure? This cannot be undone." confirmation. ### Edit and publish inside the sidebar Click any content row to open the editor sidebar. * **Fetch page content**: If a tracked URL has no body text yet, click "Fetch content" to scrape the page. * **Revise with Athena AI**: Opens a chat interface to request edits to your document. Proposed changes appear as a highlighted diff in the editor; click "Accept" to apply them or "Reject" to revert. * **Version history**: Click the clock icon to browse past autosaves and accepted revisions. * **Publish / Update / Track**: Connects the document to a CMS or marks it as a live URL. * **Schedule publish / Schedule update**: Opens a dialog to queue the content for future publication. * **Regenerate**: If you are unhappy with an outline, you can regenerate the brief. * **Export**: Open the download menu in the editor's **Content** tab and choose **Export as Word**, **Export as PDF**, or **Export as HTML**. These export the document; the table's CSV export downloads row data. * **Copy**: Copy the text to your clipboard in Markdown, Plain text, HTML, Google Docs, or Word format. * **Share**: Generate a shareable link to the editor. ## Data shown The spreadsheet displays your tracked competitors, your configured prompts, and your owned content inventory. The metrics columns (citations, traffic, rankings) reflect data gathered over the date range specified in the filter bar. Oracle remediation rows display draft corrections for outdated claims found on your live pages. ## Common workflows ### Track existing pages Use **Import URLs** to paste one page URL per line. Continue to **Review URLs**, remove any pages you do not want, and confirm the import. You can also ask Athena to track an existing batch of URLs in Content Hub. Tracking adds pages to your inventory; it does not rewrite or publish them. ### Mark a content change on its performance chart Open the content metrics panel and use its date-marker selector to show a published date or a custom date column on the chart. Choose **No marker** to hide it. Editable markers let you update the underlying date when you have write access; the built-in published-date marker is editable for published content. A marker provides context for the chart, not proof that the content change caused the metric movement. **Generating an AI-optimized article:** 1. Click the "Create" button in the top right. 2. Ensure your preferred "Brand kit" and destination sheet are selected. 3. Choose "Write". 4. Follow the prompts to select topics and generate a brief. 5. Review the brief in the sidebar, edit if necessary, and approve it to generate the full article. **Bulk-running an AI agent:** 1. Add an "Athena Agent" custom column using the "Columns" -> "Add column" menu. 2. Click the dropdown arrow on your new column's header. 3. Select "Bulk Athena Agent". 4. Choose whether to run it for "All rows", "Missing only" (rows with empty cells), "Stale rows", or "Ready rows". 5. Click the "Generate" button. **Moving content to a different sheet:** 1. Select the checkboxes next to the rows you want to organize. 2. In the bulk action toolbar that appears, click "Move". 3. In the "Move to another sheet" dialog, select your "Destination" sheet. 4. Review any warnings about dropped cells, then click "Move". ## Empty, loading, and error states * **Empty**: If no content matches your filters, the calendar displays a "No content to display" message. The spreadsheet displays an empty state prompting you to clear filters or import URLs. * **Loading**: While data is being retrieved, the spreadsheet and sheet tabs display animated skeleton rows and shimmers. The calendar view shows an animated loader. Column lists show skeleton rows while dynamic filter fields load. * **Error**: If an action fails (like saving a cell, moving a row, or importing a CSV), a red error toast appears (e.g., "Failed to update cell value", "Failed to save the marker date. Try again.", "Could not update page discovery status"). If the editor sidebar fails to load, you will see a "Couldn't load this content" message with a "Try again" button. ## Linked from / links to * **Linked from**: You can reach this page from the main navigation menu, or by clicking content drill-downs from the Olympus dashboard and Prompts pages. * **Links to**: The "Share" button generates a link that takes recipients directly to the specific content editor sidebar. The Oracle remediation drawer contains an "Open" button that deep-links into the full content editor. ## Common support questions **Why is the "Export as CSV" button disabled?** If your export includes citation metric columns and the page is still loading that data (or the data is temporarily stale due to a URL change), the export is blocked to prevent you from downloading incomplete or zero-filled data. It will say "Waiting for citation metrics…" until the data settles. **Why are some of my cells missing after moving rows to a new sheet?** If you move rows to a destination sheet that does not have the exact same custom columns configured as your original sheet, the data for those specific columns cannot be transferred and will be dropped. The "Move to another sheet" dialog will warn you about this before you confirm. **Why can't I run my new Athena Agent column?** If you have created multiple agent columns that reference each other, you may have accidentally created a circular dependency (e.g., Column A requires Column B, but Column B requires Column A). You must resolve this in the column dependency workflow dialog before the agents can run. Also, an agent cannot run if the columns it depends on are currently empty. **What does excluding a page from attribution do?** When you use the bulk toolbar to exclude pages from attribution, those pages will no longer count toward your site's overall citation metrics. Because a page either belongs to your brand or it doesn't, this exclusion is retroactive and removes its citations from all past reporting periods as well. A toast will confirm that citations are removed from past periods too. # Create Pitch Source: https://docs.athenahq.ai/guides/create-pitch Two-step wizard that analyzes a website, researches its competitors and prompts, and creates a new pitch report (or clones an existing one). > [card] [Open in AthenaHQ](https://app.athenahq.ai/create-pitch) > > `app.athenahq.ai/create-pitch` ## Purpose The Create Pitch page allows you to generate a new pitch report by analyzing a target website. It uses AI to automatically research the brand's description, discover its direct competitors, and generate a list of relevant search prompts (both branded and non-branded) to analyze. The page operates as a two-step wizard. First, you provide the website URL and target market (country and language). Then, you review and customize the AI's research - adding, editing, or removing competitors and prompts - before finalizing the pitch. This page is also used when you clone an existing pitch, allowing you to tweak the setup before generating a new report. ## What's on the page **Progress steps header** Shows your current position in the setup process. The title reads "Create Pitch Report" (or "Clone Pitch Report") on step one, and "Review & Customize" on step 2. **Step 1: Website details** * **Website URL**: The web address of the brand you want to create a pitch for. * **Country**: A dropdown to select the target country for the research. * **Language**: A dropdown to select the language for the generated research. **Step 2: Brand profile** * **Brand summary card**: Displays the brand's logo, name, and URL. It also includes an identifiers dropdown (e.g., "1 identifier") to manage the specific terms used to identify this brand in search results. * **Name**: An editable field for the brand's name. * **Description**: An editable text area containing the AI-generated description of the company. **Step 2: Customization tabs** A toggle switch between **Competitors** and **Prompts**. * **Competitors list**: Shows the AI-discovered competitors. Each row includes the competitor's logo, name, a clickable URL, an identifiers dropdown, and a **⋯** (More) menu. * **Prompts list**: Shows the AI-generated search queries. Each row includes the prompt text, a badge indicating if it is "Non-Branded" or "Branded", and a **⋯** (More) menu. * **Add button**: Located in the top-right of the customization section, allowing you to manually add a competitor or prompt depending on which tab is active. **Bottom navigation bar** * **Analyze Website**: On step 1, begins the AI research process. * **Back**: On step 2, returns you to step 1. * **Create Pitch Report**: On step 2, finalizes the setup and creates the pitch. * **More**: A small scroll indicator that appears at the bottom of the content area if the page is scrollable. **Drawers** * **Competitor Drawer**: Opens when adding or editing a competitor. Includes fields for Name and URL, plus **Delete** and **Save** / **Add** buttons. * **Prompt Drawer**: Opens when adding or editing a prompt. Includes fields for Prompt (the keyword), Type ("Non-Branded" or "Branded"), and Country, plus **Delete** and **Save** / **Add** buttons. ## What you can do here * **Analyze a website**: Fill out the URL, country, and language on step 1, then click **Analyze Website** to generate the brand profile, competitors, and prompts. * **Edit brand identifiers**: Click the identifiers button (e.g., "1 identifier") on the brand summary card or any competitor row. Here you can type a new identifier and click **Add**, toggle **Match case**, edit an existing identifier by clicking it, or delete one using the **X** icon. * **Add a competitor**: Click **Add** while on the Competitors tab to open the competitor drawer. Fill in the Name and URL, then click **Add**. * **Edit a competitor**: Click a competitor row, or open the **⋯** menu on the row and select **Edit**. Make changes in the drawer and click **Save**. * **Delete a competitor**: Open the **⋯** menu on a competitor row and select **Delete**, or click **Delete** inside the competitor edit drawer. * **Add a prompt**: Click **Add** while on the Prompts tab to open the prompt drawer. Type the keyword, select the Type and Country, then click **Add**. * **Edit a prompt**: Click a prompt row, or open the **⋯** menu on the row and select **Edit**. Make changes in the drawer and click **Save**. * **Delete a prompt**: Open the **⋯** menu on a prompt row and select **Delete**, or click **Delete** inside the prompt edit drawer. * **Retry competitor discovery**: If the AI failed to find competitors, a notice appears in the Competitors tab. Click **Try again** to re-run the competitor search without altering your prompts or brand profile. * **Submit the pitch**: Once you are satisfied with the setup on step 2, click **Create Pitch Report** to finalize it and navigate to your new pitch workspace. ## Data shown The data shown on this page is generated dynamically by AI analyzing the URL you provide. It pulls in a company description, discovers relevant industry competitors, and generates search queries that potential customers might use to find the brand or its competitors. When cloning a pitch, the data is pre-populated from the pitch you chose to clone. ## Common workflows **Create a new pitch report** 1. Enter the target website URL in Step 1. 2. Select the target Country and Language, then click **Analyze Website**. 3. Wait for the research to complete. Step 2 will appear with the generated brand profile, competitors, and prompts. 4. Review the information. Use the **Competitors** and **Prompts** tabs to add, edit, or remove entries as needed. 5. Click **Create Pitch Report**. You will be taken to your new pitch workspace. **Clone and modify an existing pitch** 1. Navigate to clone a pitch (usually via a "Clone" action on an existing pitch). The page will load directly into Step 2 with the original pitch's data. 2. Review the pre-filled description, competitors, and prompts. 3. Make any necessary adjustments (such as adding a missing competitor URL or removing irrelevant prompts). 4. Click **Create Pitch Report** to finalize the cloned copy. **Retry competitor discovery if none were found** 1. If you reach Step 2 and the Competitors tab shows a message that no competitors were found, click the **Try again** button inside the notice. 2. The system will attempt to find competitors again. If successful, they will be appended to the list. 3. If it fails again, you can click **Add competitor** to enter them manually. ## Empty, loading, and error states * **Empty states**: If you delete all competitors or prompts, the list will show a message stating "Add at least one competitor/prompt to create this pitch." If the initial AI discovery found zero competitors or encountered an error, a specific notice appears offering buttons to **Try again** or **Add competitor**. * **Loading states**: A full-page animated loader appears when you first visit the page while the system checks your plan permissions or loads clone data. During website analysis (after clicking "Analyze Website"), skeleton loading rows appear in the competitor and prompt lists, and the main button shows streaming status text like "Analyzing website..." or "Researching competitors and prompts...". * **Error states**: * If your organization does not have access to pitches or you have run out of pitch credits, you will see a "Pitch access required" or "No Pitch Reports Available" screen blocking the form, with buttons to **Contact Support**, go **Back to Dashboard**, or go **Back to Workspace**. * If a cloned pitch has a competitor with a missing URL, an "Add a website URL" warning appears in amber on that competitor's row, and the submit button is disabled until you edit the competitor and add a URL. * Toast error notifications appear if website analysis fails, if you try to add more than the allowed limit of competitors (10) or prompts (25), or if pitch creation fails. ## Linked from / links to * **Linked from**: This page is accessed from the Pitch Workspace (when choosing to create a new pitch or clone an existing one). * **Links to**: * **Create Pitch Report** takes you to the new pitch in the Pitch Workspace. * **Contact Support** (on access-denied screens) opens your email client addressed to support. * **Back to Dashboard** / **Back to Workspace** returns you to the main app interfaces if you lack access. ## Common support questions **Why is the "Create Pitch Report" button disabled?** The button is disabled if required information is missing. You must have a website name, at least one competitor (with a valid URL), and at least one prompt. If you cloned an older pitch, a competitor might be missing its URL - look for the "Add a website URL" warning and edit that competitor to fix it. **Why didn't the system find any competitors?** Sometimes the AI cannot confidently identify direct competitors for highly niche or newly established websites. You can click "Try again" to prompt the system to take another look, or click "Add competitor" to manually enter the competitors you know. **How many competitors and prompts can I add?** You can include a maximum of 10 competitors and 25 prompts per pitch report. If you try to add more through the drawers, you will see an error message. **Can I change the country after the research is done?** The base country selected on Step 1 applies to the entire pitch. However, you can set a specific, different country for individual prompts by editing them in the Prompt tab. If you need to change the overall base country, you must click **Back** to return to Step 1 and re-analyze the website. # Glossary Source: https://docs.athenahq.ai/guides/glossary Provide plain-language, searchable/navigable definitions of every AthenaHQ metric, score, and concept, grouped by category, so customers can look up how numbers are calculated and how to act on them. > [card] [Open in AthenaHQ](https://app.athenahq.ai/glossary) > > `app.athenahq.ai/glossary` ## Purpose The Glossary page provides a centralized, plain-language reference for every metric, score, and core concept used within AthenaHQ. It helps customers understand exactly what the numbers in their dashboards mean, how specific formulas are calculated, and how to act on those insights to improve their generative engine optimization (GEO) strategy. Whether a customer needs a refresher on the difference between a source and a citation, wants to know how their Share of Voice (SOV) is calculated, or needs to understand how AI Search Value translates into real-world dollar amounts, this page acts as the definitive guide. ## What's on the page * **Page Header:** Displays the title "Glossary" along with any standard top-level navigation elements. * **Category Navigation ("On this page"):** A sticky menu that allows customers to jump quickly to specific groupings of terms. On wide screens, this is a vertical list on the left side of the page with an animated highlight tracking the active section. On narrow screens, it appears as a horizontal, scrollable pill bar right below the header. The categories include: * Visibility & rankings * Citations & sources * Sentiment & perception * Value & ROI * How Athena collects data * Prompt strategy * **Hero Section:** Introduces the page with a "Reference" label, the title "The AthenaHQ glossary", and a brief description outlining that the page explains how numbers are calculated and acted upon. * **Category Sections:** The main content of the page, split into the categories listed above. Each section displays its title, a short description, and a matching icon. * **Term Lists:** Inside each category section is a card containing a list of terms. Each term row is collapsed by default, displaying the term's name and a one-line summary. * **Expanded Term Content:** Expanding a term row reveals the complete, detailed definition. Depending on the term, this can include mathematical formulas, styled examples, formatted lists, and embedded flowcharts (such as the QVEM volume estimation diagram). ## What you can do here * **Navigate by category:** Click any category in the left rail (or the top pill bar on narrow screens) to smoothly scroll the page down to that specific section. * **Expand or collapse a term:** Click anywhere on a term's row (e.g., "Mention Rate", "Stream Data", "Funnel stage") to toggle it open or closed. Expanding it reveals the comprehensive definition, formulas, and usage examples. * **Deep-link to a term:** The page supports URL hashes. If a customer visits the page with a specific term ID in the URL (e.g., `/glossary#brand-mention-rate`), the page will automatically scroll to that term and expand it so it is immediately readable. ## Data shown This page displays static, globally applicable reference documentation. It does not display any of the customer's own tracked competitors, personal metrics, or organization-specific data. The content is universal for all AthenaHQ users. ## Common workflows **1. Look up a specific metric definition** 1. Navigate to the Glossary page. 2. Click the relevant grouping in the "On this page" navigation menu (for example, "Visibility & rankings"). 3. The page smooth-scrolls directly to that section. 4. Click the row for the specific metric (like "Share of Voice (SOV)") to expand its full definition and view the mathematical formula. **2. Review definitions from an in-app help link** 1. A customer clicks a "learn more" or information link embedded elsewhere in the product (such as inside the Schedules dialog or a tooltip explaining Volume Estimation). 2. They are taken to the Glossary page via a deep link. 3. The page automatically scrolls to the relevant term and expands it so the customer can read the context immediately without needing to search for it. ## Empty, loading, and error states * **Loading:** Because the glossary text is built directly into the application, it renders almost instantly. * **Empty:** There is no empty state for this page, as the definitions are universal and static. * **Error:** There are no explicit error messages on this page. The Glossary is available on every plan, including Free. ## Linked from / links to * **Linked from:** Typically accessed via the main application help resources or knowledge bases. It is also deep-linked from specific tooltips and modals across the application (e.g., the Schedules dialog or Estimated Impressions tooltips) to explain specific concepts. * **Links to:** This page does not contain links leading away from the glossary, though the expanded terms do offer deep-link anchor IDs for referencing. ## Common support questions * **Is the Glossary available on the Free plan?** Yes. The Glossary is available on every plan, including Free. * **Is there a way to search for a specific term?** AthenaHQ does not currently have a dedicated search bar within the Glossary page. We recommend using your browser's built-in "Find" feature (Ctrl+F or Cmd+F) or using the "On this page" navigation menu to jump to the right category. * **What is the difference between a source and a citation?** You can find the exact distinction by clicking the "Citations & sources" category and expanding the "Sources vs. citations" term. In short, a "Source" is a unique URL the AI references, while a "Citation" is a single occurrence of that source being used in a response. * **How does Athena estimate search volume?** Under the "How Athena collects data" category, expand the "Volume estimation (QVEM)" term. It provides a detailed breakdown of how our Query Volume Estimation Model works, complete with a flowchart diagram. # Group Dashboard Source: https://docs.athenahq.ai/guides/group-id Shows an aggregated, filterable analytics dashboard (share of voice, mention/citation rate, position, dollar value) across all websites in a group, with saved views and scheduled reports. ## Purpose The Group Dashboard provides an aggregated, top-down view of AI search visibility across an entire group of websites. Instead of checking individual sites one by one, customers use this page to see combined metrics for Share of Voice, Mention Rates, Citation Rates, ranking positions, and estimated Dollar Value Captured. This page is essential for teams managing portfolios of brands, regional sites, or enterprise groups, allowing them to track overall market presence against competitors, filter across multiple web properties at once, and schedule group-wide email or Slack reports. ## What's on the page **Page header** Displays the breadcrumb "Group /" followed by the group's name. On the far right is a kebab menu (⋯) containing actions for the group. **Filter bar** A sticky bar that stays at the top of the screen as you scroll. It includes: * **Date Range & Baseline Picker:** Two date selection chips. The first sets the selected period for the dashboard. The second (`vs. baseline`) sets the comparison period for all delta/change badges (e.g., "+2.3%"). * **Websites, Topics & Prompts:** A dropdown that filters data down to specific websites in the group, topics, or individual prompts. * **+ Add filter:** A menu to add specific criteria (Models, Prompt status, Prompt type, Variations, Locations, Personas, Prompt tags, Brand identifiers) or import a saved view. * **Combine websites toggle:** A switch that dictates how data is drawn. When checked (grouped mode), the dashboard aggregates all the group's websites into a single "brand" entity. When unchecked (detailed mode), charts show each group website as its own individual line or slice. * **Views dropdown:** A menu to save the current filter setup, load an existing view, or set a default view. **Dashboard cards grid** A draggable, resizable layout of chart cards displaying the group's data. Note that this dashboard supports a specific subset of 5 charts: * **Share of Voice:** A donut chart and ranked list showing how often AI mentions the group's brand(s) versus competitors. * **Mention Rate:** A line/area chart tracking the percentage of AI responses that mention the brand over time. * **Citation Rate:** A line/area chart tracking how often the brand's tracked content is cited by AI. * **Position Over Time:** A line chart tracking average ranking positions for the brand vs. competitors. * **Dollar Value Captured:** A summary card showing the estimated financial value driven by AI visibility. ### Manage Reports Modal Accessible from the header's ⋯ menu, this modal lets users schedule email and Slack deliveries for the group dashboard. It displays a "Reports" table with the following columns: * **Report:** The name of the report. Clicking the row edits the report. * **Schedule:** The cadence (e.g., "Weekly"), day, and delivery hour in the user's timezone. * **Charts:** The number of charts included in the scheduled delivery. * **Recipients:** The total count of active subscribers, or "None". * **Actions (invisible header):** A kebab menu (⋯) for managing the individual report. ### Import from website view dialog Opened via the "+ Add filter" menu. This dialog lists all saved views belonging to the individual websites within the group. Users can select one or more of these views to instantly pull their specific filters (like specific prompts, tags, or models) into the group dashboard. If the chosen views have conflicting settings (e.g., one looks at "Active" prompts and another at "Paused"), a conflict-resolution screen explains how the merge will be handled. ## What you can do here **Dashboard & Layout Actions** * **Toggle view modes:** Click the "Combine websites" toggle to switch all charts between a single aggregated brand and a detailed per-website breakdown. * **Reorder cards:** Click and drag the grip handle (six dots) in the top-right corner of any chart to move it. * **Resize cards:** Click and drag the bottom-right corner of a card to stretch or shrink it. * **Highlight competitors:** Click a competitor's name in a chart's bottom legend to focus on their data line/slice and dim the others. * **View chart info:** Hover over or click the `[ i ]` icon on a card to open a dialog explaining how that specific metric is calculated. **Filtering Actions** * **Set dates:** Click the "Date Range" chip to pick the primary window. Click "Select baseline..." to add a comparison period. * **Swap periods:** If the baseline period overlaps or sits after the selected period, a warning badge appears. Click the "Swap" or "Swap periods" button on the badge to fix the order. * **Clear baseline:** Click the "X" icon on the baseline chip to remove the comparison. * **Apply filters:** Click "+ Add filter" to add rules. For multiselect options (Models, Locations, Personas, etc.), the filter defaults to "is any of" (inclusion only). * **Clear All:** Click the "Clear All" button (appears when filters are active) to reset everything back to defaults. * **Filter by website/topic:** Click the "Websites, Topics & Prompts" chip to open a nested tree. Check specific websites, expand them to check specific topics, or expand topics to check individual prompts. Click "Apply". **Saved View Actions** * **Save a view:** Click the "Views" button and select "Save as view". Enter a name, pick an icon, and check "Keep end date current" if you want the date window to roll forward automatically. Click "Save". * **Load a view:** Click "Views" and select any saved view from the list to apply its filters. * **Clear selected view:** Click the "X" next to the active view's name in the trigger to revert to the "Default" view. * **Update filters:** Open the "Views" menu, hover over the active view, click the ⋯ icon, and choose "Update filters" to overwrite it with the currently visible filters. * **Set default:** From a view's ⋯ menu, select "Set as default" so it loads automatically when you visit the group. * **Edit view:** From a view's ⋯ menu, select "Edit" to rename it or change its icon. * **Delete view:** From a view's ⋯ menu, select "Delete". This is destructive. * **Import website views:** Click "+ Add filter", select "Import from view", check the desired views, and click "Import N view(s)". If there are conflicts, click "Import anyway" to accept the merged logic or "Back" to change selections. **Report Actions** * **Open reports:** Click the ⋯ menu in the top right of the page header and click "Manage reports". * **Create report:** Inside the modal, click "New report" to open the report builder. * **Edit report:** Click a report row, or click its ⋯ menu and select "Edit". * **Preview report:** Click a report row's ⋯ menu and select "Preview and test" to jump straight to the delivery testing step. * **Delete report:** Click a report row's ⋯ menu and select "Delete". A confirmation dialog will warn: *"This permanently deletes "\" and stops its scheduled deliveries."* Click "Delete report" to confirm. ## Data shown The dashboard pulls AI response tracking data (mentions, citations, position rankings) generated by querying target prompts against AI engines (ChatGPT, Gemini, Perplexity, Claude, Copilot, AI Overviews, AI Mode, Grok, DeepSeek, Meta AI, Mistral). All metrics are aggregated across the websites that belong to the group, and are compared against a capped list of the top 100 competitors found across those websites. ## Common workflows **Analyzing high-level group performance:** 1. Navigate to the Group Dashboard. 2. Ensure the "Combine websites" toggle is checked (Grouped mode). 3. Set a "Date Range" (e.g., Last 30 days) and select "Previous period" as a baseline. 4. Scroll through the cards to see how the overall portfolio's share of voice and citation rates grew or shrank compared to the previous month. **Merging individual site strategies into a group view:** 1. On the Group Dashboard, click "+ Add filter" and select "Import from view". 2. Select specific saved views that were previously created for individual websites in the group (e.g., a view tracking "High Intent Prompts"). 3. Click "Import views". 4. Review any conflicts on the resolution screen, click "Import anyway", and then click "Views" -> "Save as view" to save this combined setup for the whole group. **Scheduling a portfolio report:** 1. Click the ⋯ menu in the top right of the page header and select "Manage reports". 2. Click "New report". 3. The builder will automatically select the 5 group-compatible charts. 4. Give the report a name, set a weekly/monthly cadence, add email or Slack recipients, and save it. ## Empty, loading, and error states * **Loading:** An animated loader appears in the center of the dashboard while group structure and initial metrics initialize. Individual cards display skeleton loaders (gray pulsing shapes) while fetching data. * **Empty:** If the selected filters exclude all data (e.g., no mentions occurred), cards display a blurred sample chart overlaid with a "No data" message. * **Error:** If a chart fails to fetch, it shows a blurred background with a "Something went wrong..." message and a refresh (retry) button. * **No Reports:** If the Manage Reports modal is opened and no reports exist, an empty state displays "No reports" with a "New report" button. ## Linked from / links to * **Linked from:** The main sidebar navigation under the Groups section, Market Landscape pages, and direct group links. * **Links to:** The Report Builder (via the Manage reports modal) which opens in-place to configure scheduled deliveries. ## Common support questions **Why are some of my charts missing from the Group Dashboard?** The Group Dashboard currently supports a focused subset of 5 charts (Share of Voice, Mention Rate, Citation Rate, Position Over Time, and Dollar Value Captured). Other charts available on single-website dashboards (like Brand Traits or Sources Visualization) are not available here yet. **What does the "Combine websites" toggle do?** When checked, it adds all your group's websites together and treats them as one giant "Brand" line on the charts. When unchecked, the charts break out into a detailed view, drawing a separate line or pie slice for each individual website in the group. **Why is there a warning on my baseline date?** If your selected baseline comparison period overlaps with your main date range, or if it takes place *after* your main date range, the dashboard flags it. Comparing against the future makes metrics read backwards (e.g., a drop looks like an increase). You can click "Swap" on the warning badge to easily flip them. **Why can't I export my Group Saved View to CSV?** The CSV export option (usually found in the Views dropdown) is intentionally hidden for Group dashboards. Group filters combine data across multiple sites in a way that the standard prompt CSV exporter doesn't currently support. **Why didn't my date range import when I used "Import from view"?** When importing filters from website-level views into a group, the date range is intentionally ignored. The dashboard always applies the imported criteria (like models, tags, and personas) to the date range you currently have selected on the group page. # Group Billing Source: https://docs.athenahq.ai/guides/group-id-billing Lets a group admin (or billing-capable role) enable and manage shared credit billing for a website group, viewing credit balances and invoices scoped to that group. ## Purpose The Group Billing page allows administrators to manage shared credit billing for a specific website group. By enabling billing on a group, administrators can purchase and assign credits that are shared across all websites within that group. This solves the problem of micromanaging credits for individual websites by letting them draw from a shared group pool once their individual credits are depleted. The page also provides a view of the group's credit usage, remaining balances, and group-specific invoice history. ## What's on the page * **Billing overview header**: Displays the "Group credits" title alongside an info icon. Subtext explains that credits are shared across all websites in the group. If billing is not yet set up, this area prompts the user to enable it. * **Websites in group**: A small strip of logo avatars representing the websites assigned to the group, alongside a count of total websites. Hovering over a logo shows the website's name or URL in a tooltip. * **Action buttons**: In the top right, buttons to "Manage subscription" (for certain custom-billed groups) and "Add credits" (or "Add more credits" if a balance exists). * **Group credits remaining**: A visual breakdown of credit balances split into two distinct areas: * **Group credits**: Credits assigned specifically to this group. * **Organization credits**: The broader, organization-wide credit pool that websites in this group can also draw from. * **Credit buckets**: Each section displays individual cards for different credit cadences (e.g., "Monthly credits", "One-time credits", "Quarterly credits", or a fallback of "Recurring credits"). * **Credit usage progress bars**: A horizontal progress bar for each bucket, showing 0-100% used. The bar turns orange when 66% or more of the bucket is consumed. Below the bar, the exact "used" and "left" (or "over") amounts are listed, alongside the next reset date if applicable. * **Group invoices section**: Displays "Outstanding invoices" (open, pending, or past due) and "Invoice history" (past paid, void, or uncollectible invoices). History is organized into collapsible sections by month. * **How group credits work dialog**: Opened via the info icon next to the "Group credits" title. It explains: * **Credit priority**: "Website credits are checked first. When depleted, usage falls back to group credits." * **Monthly credits**: "Auto-renew at the start of each billing period. Unused monthly credits do not roll over." * **One-time credits**: "Purchased once and consumed until depleted. They don't renew." ## What you can do here * **Enable billing**: If the group does not have billing enabled yet, clicking the "Enable billing" button sets up a billing profile so the group can hold shared credits and receive invoices. * **Add credits / Add more credits**: Opens a dialog to purchase credit packages. * **One-time / Monthly tabs**: Toggles between purchasing a one-time credit package or a recurring monthly package. * **Quantity +/- steppers**: Adjusts the number of credit packages to purchase (from 1 up to 50). The dialog updates the "Credits to add" and "Total cost" summary dynamically. * **Cancel**: Closes the dialog without making a purchase. * **Add \{N} credits**: Confirms the purchase. For standard customers, this redirects to a Stripe checkout page. For customers on custom partner billing, this adds the credits directly and displays a success toast. * **Manage subscription**: Opens the external Stripe subscription portal in a new tab. This is only visible for specific partner groups on custom billing plans. * **View organization billing**: A link at the bottom of the "Organization credits" section that navigates to the main organization billing settings page. * **View 'How group credits work'**: By clicking the info icon next to the heading. * **Try again**: If the invoice section encounters a loading error, clicking this button attempts to fetch the invoices again. ## Data shown * **Group credits**: The balance of credits purchased specifically for this website group. * **Organization credits**: The shared pool of credits available to the entire organization, which these group websites will use if their individual and group-level credits run out. * **Websites**: The specific tracked content websites currently assigned to this group. * **Invoices**: The billing history and outstanding charges billed directly to this group's billing profile. ## Common workflows 1. **Enable billing for a new group** 1. An administrator opens the group's billing page and sees the "Group billing not enabled" message. 2. They click the "Enable billing" button. 3. The system provisions a billing profile for the group, and the page updates to show the standard credit balances and invoice sections. 2. **Purchase additional credits** 1. Click the "Add credits" (or "Add more credits") button in the top right. 2. Select either the "One-time" or "Monthly" tab (if available). 3. Use the `+` and `-` stepper buttons to choose how many credit packages to buy. 4. Review the total credits and calculated cost at the bottom of the dialog. 5. Click "Add \{N} credits" to proceed to checkout or finalize the purchase. 3. **Review credit balances and invoices** 1. Navigate to the page to view the progress bars under "Group credits". 2. Scroll down to the "Organization credits" section to see the broader pool's health. 3. Check "Outstanding invoices" for any unpaid bills, or expand a month under "Invoice history" to download past receipts. 4. **Manage custom-billing subscription** 1. If the group is on a supported partner custom-billing plan, click "Manage subscription". 2. A secure, short-lived link is generated, and the Stripe subscription portal opens in a new tab for payment method management. ## Empty, loading, and error states * **Empty**: * If billing is not yet enabled for the group, a card reads "Group billing not enabled" with an explanation and an "Enable billing" button. * If there are no group-specific credits, the text "No credits assigned to this group yet" appears under the Group credits heading. * If there are no invoices, the sections display "No outstanding invoices" and "No invoice history yet". * **Loading**: While fetching billing details, skeleton placeholders render for the credits header, bucket cards, and invoices. Screen readers announce "Loading credits" and "Loading invoices". * **Error**: If the billing service experiences a transient failure or outage while loading invoices, an "Unable to load invoices" alert is shown alongside a "Try again" button. ## Linked from / links to * **Linked from**: The specific Group settings/detail page, or the Organization groups management page. * **Links to**: * The main organization billing page (`/settings/billing`) via the "View organization billing" link. * External Stripe checkout flows for standard credit purchases. * External Stripe customer portal for managing custom subscriptions. * Redirects to the group overview page if the user lacks billing permissions, or the main dashboard if they have no access to the group at all. ## Common support questions * **Why don't I see the group billing page?** To view and manage group billing, you must be a member of the organization with the "billing write" capability. If you lack this permission, navigating to the page will automatically redirect you back to the group overview. * **How do group credits interact with website credits?** Credit consumption follows a priority order. Athena first checks if the individual website has credits. If those are depleted, it falls back to the "Group credits" pool. If the group pool is also empty, it will finally draw from the shared "Organization credits" pool. * **Why are my group and organization credits shown separately instead of as a total?** Group credits and Organization credits are deliberately kept separate. Summing them together could misleadingly imply that the group "owns" the organization-wide money, when in reality, the organization pool is shared with websites outside the group as well. # Competitor Heatmap Source: https://docs.athenahq.ai/guides/heatmap Show a heatmap grid of each tracked topic against the brand and its competitors so users can spot mention/citation gaps at a glance and drill into supporting prompts. > [card] [Open in AthenaHQ](https://app.athenahq.ai/heatmap) > > `app.athenahq.ai/heatmap` ## Purpose The Competitor Heatmap page gives marketers a high-level, visual overview of how their brand performs against competitors across different topics. Instead of reading through lists of responses or digging through individual prompt metrics, users can scan a color-coded grid to instantly spot strengths and content gaps. By comparing Mention % or Citation % side-by-side, users can quickly identify which topics their competitors are dominating in AI responses and which topics their own brand owns. It serves as a powerful starting point for competitive analysis, allowing users to spot a weak area and immediately drill down into the underlying AI prompts to see exactly what went wrong. ## What's on the page * **Page header:** Displays the title "Competitors vs Topics Heatmap". If the user navigated here from a specific competitor's profile, a back arrow appears allowing them to return to the previous page. * **Filter row:** A standard bar for refining the data shown in the heatmap. Users can filter by date range, AI models, prompt status, locations, countries, personas, prompt variations, specific tags, and owned domains. Users can also apply "Mention %" or "Sentiment %" thresholds to hide competitors that don't meet a minimum performance bar. * **Metric toggle tabs:** Two buttons labeled **Mention %** and **Citation %**. Selecting one updates the entire grid to display that specific metric. * **More options menu (⋯):** Located at the far right of the metric tabs (or in the sticky menu on mobile), containing the "Export as CSV" action. * **Heatmap grid:** * **Rows (Topics):** Listed alphabetically down the left side. These represent the specific topics your brand tracks. * **Columns (Companies):** Your brand is always locked as the first column, followed by your tracked competitors. Each column header features the company's logo and name. * **Cells:** The intersection of a topic and a company. It displays the selected metric percentage. The cell's background color intensifies based on how high the value is, making it easy to spot high-performing areas. * **Footer summary:** A status bar at the bottom of the grid that reads, for example, "Showing 15 topics across 4 competitors." ## What you can do here * **Switch metrics:** Click the "Mention %" or "Citation %" tabs to instantly swap the data populating the heatmap cells. This preference is saved in the URL, so it persists if the page is refreshed or shared. * **Drill down into a cell:** Clicking any percentage cell in the grid will take you directly to the Prompts page. The app automatically applies filters for the clicked topic and the clicked competitor (unless you clicked your own brand's column), allowing you to immediately inspect the AI responses driving that score. * **Sort by column:** Click any column header (a company name) to sort the topics. Clicking once sorts the rows from highest to lowest percentage for that company; clicking again sorts lowest to highest; a third click removes the sorting. * **Reorder columns:** Click and drag a competitor's column header left or right to rearrange the grid. This is useful for placing your closest rival right next to your brand for direct comparison. * **Pin columns:** You can pin a column to the left side of the grid so it stays visible while you scroll horizontally through a long list of competitors. * **Export as CSV:** Open the ⋯ menu and click **Export as CSV**. This downloads the heatmap data exactly as it appears on your screen, honoring your current metric selection, custom column order, and applied filters. ## Data shown * **Topics (Rows):** Derived from the topics configured across your brand's tracked prompts. "Uncategorized" prompts are excluded from this view. * **Competitors (Columns):** Drawn from the list of competitors you have actively added to your workspace. * **Percentages (Cells):** Calculated by aggregating the AI responses for the specific topic and competitor over the selected date range and models. ## Common workflows **Identifying and investigating a competitor's strength:** 1. Ensure the **Mention %** tab is selected. 2. Scan the grid for dark-colored cells under a competitor's column that align with light-colored cells under "Your Brand". 3. Click the high-percentage cell under the competitor. 4. You will be taken to the Prompts page, automatically filtered to show only the prompts for that topic where the competitor was mentioned, allowing you to read the exact AI outputs. **Creating a custom side-by-side export report:** 1. Use the filter bar to narrow the data down to a specific timeframe or AI model (e.g., ChatGPT only). 2. Drag the column headers of your top two competitors to place them immediately next to your brand. 3. Click the ⋯ menu in the top right and select **Export as CSV**. ## Empty, loading, and error states * **No Competitors Yet:** If the workspace has no competitors added, the page displays a blurred, non-interactive mock table in the background. An overlay appears reading "No Competitors Yet" with the description "Add competitors to compare your brand visibility" and an **Add Competitor** button that routes to the Competitors page. * **No Data:** If filters are applied that result in no matching data, the grid disappears and is replaced with the text "No data available for the selected filters." The footer updates to say "No topics or competitors to display." * **Loading:** An animated loading spinner appears in the center of the grid area while the competitor list or metric data is being fetched. * **Errors:** If the data fails to load due to a system issue, the UI generally remains in the empty/loading state, and the error is logged internally for engineering to review. ## Linked from / links to * **Linked from:** The main navigation menu. It can also be reached from the Competitors page via a drilldown link that pre-filters the heatmap to focus on a specific competitor. * **Links to:** The Prompts page (by clicking any cell in the grid) and the Competitors management page (via the "Add Competitor" button in the empty state). ## Common support questions **Why is a specific topic missing from the rows?** The heatmap only displays topics that *your brand* is actively tracking. Even if a competitor performs well in a topic, it won't appear here unless you have assigned prompts to that topic in your own workspace. Prompts without an assigned topic ("Uncategorized") are also excluded. **Why does a cell say 0.1% instead of 0%?** To help users distinguish between a "true zero" (meaning absolutely zero mentions) and an extremely low score, the heatmap sets a minimum display value. Any actual percentage that is greater than 0 but less than 0.1% is rounded up and displayed as 0.1%. **Why am I being asked to upgrade when I try to export?** Exporting the heatmap to a CSV is a premium feature. If you are on the Free plan, clicking the export button will open a dialog outlining subscription options. **Where did my other competitors go?** If you apply a filter for "Mention %" or "Sentiment %" in the top filter bar, any competitor that does not meet that minimum percentage threshold across *any* of the topics will be hidden from the grid to reduce clutter. # Home (Ask Athena chat homepage) Source: https://docs.athenahq.ai/guides/home Landing page where users type or pick a quick prompt to open an Ask Athena AI chat about their brand's AI search presence. > [card] [Open in AthenaHQ](https://app.athenahq.ai/home) > > `app.athenahq.ai/home` ## Purpose The Home page is the primary starting point for users logging into Athena. Instead of navigating through complex menus to find specific data, users can simply type a question into the Ask Athena chat composer right from this page to get immediate insights about their brand's AI search presence. By providing a prominent, distraction-free search interface with quick-start suggestion chips, this page lowers the barrier to entry for users who want to analyze their brand performance, research competitors, or get content recommendations. It sits at the very top of the user's workflow as the default dashboard for natural-language discovery. ## What's on the page * **Greeting header**: A friendly, time-of-day greeting (e.g., "Morning", "Afternoon", "Evening", or "Up late") customized with the user's first name, followed by a subtitle confirming which active website they are asking about. * **Decorative atmosphere background**: A subtle, animated light-and-contour background that adds visual polish to the page. It automatically pauses when the user interacts with the chat box (typing, uploading, dictating) to minimize distractions. * **Composer (chat input box)**: The main text area where users draft messages to Athena. It supports rich text, drag-and-drop file uploads, and voice dictation. * **+ (Add menu)**: Opens options to attach "Files and images" or interact with third-party integrations ("Add connector", "Manage connectors"). * **Mic icon**: Toggles voice-to-text dictation. * **Send icon (Up Arrow)**: Submits the prompt to Athena. * **Quick prompt suggestion chips**: Four preset questions situated below the composer that help users get started with a single click: * "How is my brand performing?" * "Compare my competitors" * "Which sources cite me the most?" * "What content should I create?" **Drilldowns:** * **Submitting a prompt**: Typing a question and hitting Enter/Send, or clicking any of the quick prompt chips, immediately transitions the user into the fullscreen Ask Athena chat window, carrying over their text and attachments, and automatically starts generating the response. ## What you can do here * **Send a message**: Type your question into the text box and press Enter or click the **Up Arrow** button to start a conversation with Athena. * **Use a quick prompt**: Click one of the four suggestion chips below the composer. This immediately opens the chat window and sends the chosen question on your behalf. * **Attach files**: Click the **+** button inside the composer and select **Files and images** to open your computer's file picker, or simply drag and drop a file directly onto the composer box. * **Attach connectors**: Inside the **+** menu, select an available third-party tool (like Google Drive) to feed specific context to Athena, or click **Add connector** / **Manage connectors** to set them up. * **Dictate a message**: Click the **Mic** icon to start voice dictation. Speak your question, and the text will appear in the box. Click the Mic icon again to stop listening, or simply click the Send arrow. * **Remove an attachment**: Click the small **X** on the corner of any file preview chip in the composer to remove it before sending your message. ## Data shown * **Your first name**: Displayed in the welcome greeting (pulled from your user profile). * **Your active website**: The name of the website currently selected in the top-left workspace switcher is displayed in the greeting subtext. ## Common workflows **Ask a free-form question** 1. Click into the "Ask Athena..." input box. 2. Type your question about your brand, competitors, or content. 3. (Optional) Drag a file into the box to include it as context. 4. Press Enter or click the Up Arrow to send. The Ask Athena chat window will open and begin answering. **Use a quick prompt** 1. Review the four suggestion chips below the text box. 2. Click the one that best matches your goal (e.g., "Compare my competitors"). 3. The chat window immediately opens fullscreen and sends the prompt for you. **Attach a file via drag-and-drop** 1. Drag a document, spreadsheet, or image from your computer and hover it over the chat box. 2. A "Drop files here" overlay will appear. 3. Release the file. A loading spinner will appear on the file preview chip while it uploads. 4. Once the upload finishes, you can type any additional instructions and send the message. **Dictate a message** 1. Click the microphone icon in the chat composer. 2. Allow your browser to access your microphone if prompted. 3. Speak your question naturally; the transcribed text will populate the composer. 4. Click the microphone icon again to stop dictation, or just click the Send arrow to submit your spoken question immediately. ## Empty, loading, and error states * **Loading**: When the page is first opened, it remains entirely blank while verifying the active website and the user's access permissions. This prevents flashing incomplete menus or incorrect greetings. * **Empty**: Because this page acts as a search engine landing page rather than a data table, it doesn't have a traditional "empty" state. The composer is always visible and ready to accept input. * **Error**: * If a file fails to upload or exceeds the size limit, a toast notification appears (e.g., "unsupported file type" or "Wait for the current upload to finish"). * If voice dictation fails (e.g., microphone access is blocked by the browser), an error toast appears on screen. ## Common support questions **Why did my file fail to upload?** Check that the file is a supported format (like PDF, Word, Excel, CSV, text, or a standard image) and that it falls under the size limits (generally 10MB for documents and spreadsheets, and 25MB for images). **Can I stop voice dictation without sending the message?** Yes. Just click the microphone icon again to stop listening. You can also manually type or delete text in the composer before you hit send. **Why can't I attach another file right now?** The attach functionality is temporarily disabled while a previous file is actively uploading. Wait a moment for the loading spinner on your current file to finish, and the attach button will unlock. **Why is the home page completely blank?** The page stays blank for a moment while it confirms your active website and checks your permissions. If it stays blank indefinitely, try refreshing your browser or checking your internet connection. **Why don't I see any connectors in the + menu?** If you don't see specific connected tools, your organization may not have enabled them yet. You can click "Manage connectors" to view or set up integrations if your plan allows it. # Insights Source: https://docs.athenahq.ai/guides/insights Show AI-generated proactive insights and content opportunities for a website, letting users act on, resolve, or discard them. > [card] [Open in AthenaHQ](https://app.athenahq.ai/insights) > > `app.athenahq.ai/insights` ## Purpose The Insights page provides actionable, AI-generated recommendations based on your website's search performance, competitor movements, and content gaps. Instead of requiring you to hunt through analytics to figure out what to do next, this page proactively surfaces prioritized tasks that can grow your visibility. It is split into two main sections: **Insights** (which covers prompt performance, technical changes, and competitor shifts) and **Content opportunities** (which recommends specific topics for new or optimized articles). Customers use this page as a daily or weekly to-do list for generative engine optimization. ## What's on the page **Page Header** * **Tabs:** Switches the page between the **Insights** feed and the **Content opportunities** feed. * **Date range filter ▾:** Narrows the insights and opportunities shown below based on when they were first generated. **Connect Integrations Banner** If Google Search Console or Google Analytics 4 (GA4) are not connected, a banner appears at the top prompting you to connect them. If both are missing, it appears as a stack of cards you can flip through. You can dismiss this banner for your current session using the **Dismiss** (X) icon. **Queue Progress** At the top right of the feed, a progress bar shows how many active items you have resolved out of your current batch (e.g., "0/5 resolved" or "0/10 started"). If the queue hits its maximum limit, a **Queue full** badge appears, meaning you must clear some items before the system will generate new ones. **Insights Tab** * **Status filter:** A row of pills (**Open**, **Done**, **Discarded**) that lets you switch which insights you are viewing. Each pill displays the count of items in that state. * **Insight Cards:** Each card represents a single recommendation. It includes: * **Impact / Effort bars:** A visual indicator (e.g., "High impact, low effort") to help you prioritize. * **Category badge:** Labels the type of insight (e.g., Prompt, Content, Competitor). * **Title & Description:** Explains what changed and why it matters. * **Supporting Data:** A button that flips the card to reveal the exact metrics or facts that triggered this insight. * **Action checklist:** A to-do list of steps required to implement the recommendation. * **Mark done:** A button to resolve the insight. * **Ask Athena:** A button that opens the AI chat side-panel with a pre-filled prompt to help you execute the task. **Content opportunities Tab** * **Active recommendations grid:** A grid of cards recommending new content to **Create** or existing pages to **Optimize**. * **Opportunity Cards:** Each card displays: * **Score:** A numerical priority score. Hovering over this shows the tooltip: *"Score is relative across opportunities and doesn't mean much on its own. Use it to compare cards; higher scores are usually higher priority."* * **Status badge:** Indicates if the item is just an idea, if a "Brief ready", or if a "Draft ready". * **Description:** Explains "why now" (why this topic is recommended). * **Start / Continue:** Buttons to begin drafting or return to an in-progress draft. * **Disclosures:** At the bottom, collapsible sections group your **Lower priority**, **Filtered out by date**, **Completed**, and **Deleted** opportunities. ## What you can do here * **View supporting data:** Click the **Supporting Data** link on an insight card to flip it and view the raw metrics backing the recommendation. Click **Back** to return. * **Check off action steps:** Click the checkboxes in an insight card's Action panel as you complete tasks. If you check off every item on the list, a dialog will automatically ask if you want to mark the entire insight as done. * **Edit or add action steps:** Click directly on the text of an action step to edit it. Click **+ Add action** to write your own custom step for the checklist. Click the **×** icon that appears on hover to delete a step. * **Resolve an insight:** Click **Mark done** to clear an insight from your Open queue and move it to the Done tab. * **Discard an insight:** If an insight isn't useful, click the **⋯** (More actions) menu in the bottom right of the card and select **Discard**. A modal will ask you to select a reason (e.g., "Not relevant to my business", "Already addressed"). Once submitted, an 8-second toast appears with an **Undo** button in case you made a mistake. * **Restore a discarded insight:** Go to the **Discarded** tab, click the **⋯** (More actions) menu on a card, and select **Restore** to move it back to your Open queue. * **Start a content opportunity:** On the Content opportunities tab, click **Start** on a card. This triggers Athena to generate a brief/draft and navigates you to the Content Editor. * **Discard a content opportunity:** On a content opportunity card, click **Discard** (or **Delete** inside the **⋯** menu for in-progress items). A modal will explain what happens to the attached content (e.g., published pieces are retained, while unused drafts are hidden from your content grid). * **Check for new insights:** If your Open queue is empty, click the **Check for new insights** button in the empty state to manually trigger an analysis of your latest data. ## Data shown The insights and content opportunities are generated automatically by Athena's AI recipes. The system continually reviews your tracked prompt performance, competitor shifts, search volume changes, and integration data (if connected) to find actionable signals. The queue automatically tops itself up during your scheduled data runs, up to a maximum limit. ## Common workflows **Resolving an open insight** 1. From the **Insights** tab, review the cards in your **Open** queue. 2. Read the description and click **Supporting Data** to understand the context. 3. Check off the items in the Action checklist as you work through them. 4. Once finished, click **Mark done** (or confirm the prompt that appears when all checkboxes are ticked) to move the card to your **Done** history. **Starting a new content opportunity** 1. Click the **Content opportunities** tab at the top of the page. 2. Review the highest-scoring "To do" cards. 3. Click **Start** on an opportunity that fits your strategy. 4. You will be automatically navigated to the Content Editor where Athena has begun drafting a brief based on the opportunity's parameters. **Connecting missing integrations** 1. If you see the "Connect Integrations" banner at the top of the page, click **Connect Search Console** or **Connect GA4**. 2. A drawer will slide out. Click the connect button inside to launch the Google authorization popup. 3. Complete the Google login and consent flow. 4. Select your active property from the dropdown in the drawer to finalize the setup. ## Empty, loading, and error states * **Empty:** If you have no active insights, you will see blurred placeholder cards behind a message like "No active insights." The text explains why (e.g., "The queue was full at that check...", "There were no new signals to review"). If the system is ready, a **Check for new insights** button is provided. * **Loading:** While data is being retrieved, the page displays gray skeleton placeholders matching the shape of the insight cards. * **Error:** If insights fail to load, a red "X" icon appears with a "Failed to load insights" message and a **Retry** button. ## Linked from / links to * **Linked from:** The main sidebar navigation menu (**Insights**). * **Links to:** The Ask Athena chat side-panel (via the **Ask Athena** button on cards). The Content Editor (via **Start** / **Continue** on opportunity cards). Integration settings drawers (via the banner). ## Common support questions **Why don't I see any new insights?** Insights are generated automatically during your regular data runs, but only if the AI finds material changes worth bringing to your attention. The empty state message on the page will tell you exactly what happened during the last check (for example, if changes were too small to act on, or if your queue is already full and needs to be cleared first). **What happens to my drafts if I delete a content opportunity?** When you discard or delete a content opportunity, you won't lose any completed work. Published articles and completed pieces stay visible in your Content Hub grid. Any unused, never-published drafts or briefs attached to that opportunity will be hidden from your grid to keep it clean, but they are not permanently deleted. **Why does my insight say "Expired"?** Insights are meant to be timely. If an insight sits in your Open queue untouched for 21 days, it automatically expires and moves to the Discarded tab so your feed stays fresh. # Knowledge Base Source: https://docs.athenahq.ai/guides/knowledge-base Central workspace for building, curating, and verifying a website's brand knowledge base of pillars (topics), facts (claims), and tracked internal link pages that ground AI-generated content and can be checked against AI responses for accuracy. > [card] [Open in AthenaHQ](https://app.athenahq.ai/knowledge-base) > > `app.athenahq.ai/knowledge-base` ## Purpose The Knowledge Base is the central workspace for building, curating, and verifying the foundational brand facts that power Athena. It is where you manage the "ground truth" about your brand, products, and industry. By organizing information into distinct pillars, tracking specific pages from your website, and managing individual claims (facts), you ensure that Athena has an accurate, up-to-date repository of knowledge. This data directly grounds AI-generated content (ensuring new content stays on-brand and factually correct) and serves as the baseline for checking external AI search responses for inaccuracies or contradictions. ## What's on the page ### Page Header The top bar features the page title and primary global actions for the Knowledge Base. This includes a button to review pending claims, initiate fact verification, view the most recent verification run, and a primary dropdown menu to add new knowledge. ### Token Ceiling Banner When your knowledge base grows too large to be fully audited by the system in a single run, a warning banner appears below the header. It shows your estimated token count against the system limit, advising you to deduplicate or curate your facts to bring the size back under the ceiling. ### Tab Strip The main content area is divided into three primary views: * **Pillars**: Groups of related claims that define a topic. * **Internal links**: Tracked pages from your own website that supply facts. * **Unfiled facts**: Approved facts that have been extracted but aren't currently attached to any published pillar. ### Duplicate Pillars Callout If the system detects multiple pillars sharing the exact same name (often a result of legacy website crawls), a warning callout appears above the data table. It offers a **Merge duplicates** button to consolidate them into a single pillar. ### Pillars Table When the **Pillars** tab is active, you see a list of your content pillars. * **(checkbox)**: Select this pillar to apply bulk actions. * **Pillar**: Displays the pillar's name and description. It also shows a count of approved claims and flags if there are claims "awaiting review". *Tooltip: Content pillars that group related claims and measure content coverage.* * **Content coverage**: A progress bar and percentage indicating how much of this pillar's approved knowledge is actively reflected in your generated content. Shows "No data" if no content has been generated yet. *Tooltip: Percentage of a pillar's claims covered by your existing content.* ### Internal Links Table When the **Internal links** tab is active, this table displays tracked pages from your domain. * **(checkbox)**: Select this link to refresh or delete it. * **URL**: The web address of the tracked page. * **Status**: Shows the current processing state (e.g., Finished, Pending, Failed, Archived, Not scraped). Tooltips explain specific states, such as why a page might have failed to scrape. * **Claims**: The number of live, non-duplicate facts extracted from this specific page. * **Re-check**: A dropdown indicating how often the system re-scrapes the page to check for updated facts (Off, Weekly, Monthly), along with the date it was last checked. *Tooltip: Reads the page again weekly or monthly and updates its facts when the page changes.* ### Unfiled Facts List When the **Unfiled facts** tab is active, this view shows approved claims not attached to any published pillar. * **(checkbox / select-all)**: Select facts to move them or delete them in bulk. * **Fact text + badges**: Shows the text of the claim, a badge indicating its origin (e.g., Upload, Web research), a confidence rating badge, the date added, and an external link to the source if a URL is available. ### Floating Progress Overlays In the bottom right corner, floating cards appear when background tasks are running (such as discovering pillars or verifying facts). They show a progress bar, a status subtitle, and allow you to cancel or hide the overlay. ### Drilldowns * **Pillar dialog**: Clicking a pillar row opens a large dialog focused entirely on that pillar. It features its own header actions (Edit, Regenerate document), tabs to filter claims by status (All, Pending, Approved, Rejected, Archived), a **Sources** tab summarizing where the facts came from, and a full list of claims with individual management menus. * **Internal link details**: Clicking an internal link row opens a dialog listing the pillars that link is associated with, alongside every specific fact extracted from that page. * **Claim dialog**: Clicking a specific fact row anywhere in the interface opens the **Claim** dialog. It displays the full fact text, source quote evidence (if available), origin metadata, and offers an **Edit claim** button. * **Verification sources drawer**: Clicking **Last verification** opens a drawer ranking external domains by how many contradictions they raised against your facts. Clicking a domain drills down further into the exact conflicting AI responses. ## What you can do here ### Global Actions * **Review N pending**: Jumps to the dedicated review queue to approve or reject pending claims. * **Verify facts**: Opens the **Verify your facts** dialog to select pillars and check their claims against third-party AI responses for contradictions. * **Last verification**: Opens the **Verification sources** drawer to review the results of the most recently completed run. * **Add knowledge (dropdown)**: * **Create pillar**: Opens the **Add pillar** dialog to manually define a new topic. Includes an **Auto-research** toggle. * **Discover pillars**: Opens the **Start Knowledge Base research** dialog to automatically crawl your site and generate pillars. * **Add URLs**: Opens the **Add URLs** dialog to paste specific links or crawl a path, add them to your link bank, and extract facts. * **Upload document**: Opens the **Upload to Knowledge Base** dialog to extract facts from a PDF, DOCX, or pasted text. * **Extract from Content Hub**: Opens the **Bootstrap from Content Hub** dialog to pick existing published articles to extract facts from. ### Bulk Actions (Pillars Tab) Select one or more pillars to reveal the command bar: * **Edit** (single selection only): Opens the **Edit pillar** dialog to change the title and description. * **Refresh**: Re-associates pages and regenerates synthesis documents for the selected pillars. * **Export CSV**: Downloads the selected pillars' claims as a spreadsheet. * **Merge**: Opens the **Merge pillars** dialog to select one target pillar to keep, folding the others into it. (Confirmation: "Merge N pillars") * **Delete**: Permanently removes the selected pillars and all claims filed under them. (Confirmation: "Delete N pillars? All claims for these pillars will be deleted.") * **Verify facts**: Quickly starts a verification run pre-scoped to the selected published pillars. * **Reset**: Clears your current selection. ### Bulk Actions (Internal Links Tab) Select one or more links to reveal the command bar: * **Refresh**: Restarts the extraction process for the selected pages to find new facts. * **Delete**: Opens the **Delete N links?** dialog. This dialog provides a "cascade preview" showing exactly which facts will be permanently deleted across all pillars if you remove the links. * **Re-check (inline)**: Use the dropdown in the table row to set a page to automatically refresh Weekly or Monthly (capped at 25 links per site). ### Bulk Actions (Unfiled Facts Tab) Select unfiled claims to reveal the command bar: * **Move to pillar**: Opens the **Move to pillar** dialog to assign the selected facts to an existing published pillar. * **Delete**: Deletes the selected unfiled facts. (Confirmation: "Delete N unfiled facts?") * **Delete all**: A standalone button (visible when viewing unfiled facts) to wipe the entire unfiled bucket or the currently filtered view. (Confirmation: "Delete all N unfiled facts?") ### Inside the Pillar Dialog When viewing a specific pillar, you can manage its facts: * **Regenerate document**: Re-synthesizes the overarching pillar document from the currently approved claims. * **Approve all pending**: Instantly approves all unreviewed claims in the pillar. * **Bulk Claim Actions**: Select claims to Approve, Reject, Archive, Mark as pending, Change pillar, or Delete them. * **Claim Options Menu (⋯)**: Each claim row has a trailing menu to Approve, Reject, Edit, Archive, Restore, or Delete the individual fact. * **Sources filtering**: Click the **Sources** tab, then click a specific source (like a webpage or "Uploaded documents & pasted text") to filter the claims list to only facts originating from that source. Use **Clear source filter** to reset it. ### Fact Editing Clicking **Edit claim** from the **Claim** dialog allows you to fix typos, refine text, or update the source URL and confidence rating. *Note: Editing a fact's text actually archives the old version and creates a new one behind the scenes, ensuring historical AI responses still point to the exact text that generated them.* ## Data shown The Knowledge Base displays pillars and facts (claims) extracted automatically from your website, manually uploaded documents, and direct text entry. It also tracks the pages (Internal Links) monitored for these facts. Content coverage metrics are derived by matching your approved facts against the content you have generated and published using the platform. ## Common workflows **Populating a new knowledge base:** 1. Click **Add knowledge** in the top right and select **Discover pillars**. 2. Read the confirmation and click **Start research**. 3. The system will crawl your site, identify key themes, create pillars, and extract facts automatically. Monitor the floating progress card in the bottom right. **Adding facts from a specific PDF or document:** 1. Click **Add knowledge** and select **Upload document**. 2. Choose your file (PDF or DOCX) or switch to the **Text** tab to paste raw content. 3. Click **Extract claims**. 4. The system will process the document and place the new facts into the Unfiled facts tab or route them to relevant pillars. **Merging duplicate pillars:** 1. If you see the yellow "Duplicate pillars" callout, click **Merge duplicates**. 2. Review the list of duplicate-named pillars and the claims that will be moved. 3. Click **Merge N duplicates** to automatically fold the newer versions into the oldest published version of each pillar. **Deleting an outdated tracked page:** 1. Go to the **Internal links** tab and find the outdated URL. 2. Check the box next to it and click **Delete** in the command bar. 3. Review the cascade preview dialog carefully - it will list every fact that is about to be deleted along with the page. 4. Click **Delete N links** to confirm. ## Empty, loading, and error states * **Empty**: If your site has zero pillars, zero internal links, and zero unfiled facts, you will see a "No knowledge yet" screen with a large **Discover pillars** button. * **Loading**: While fetching initial data, the tables show animated skeleton rows. If a discovery run is active, the empty state is replaced by a live "Discovering pillars" view. * **Errors**: If data fails to load (e.g., inside a pillar dialog), an inline "Couldn't load claims" error appears with a **Try again** button. Destructive actions that fail will display a red error toast in the corner. ## Linked from / links to * **Linked from**: The main sidebar navigation (**Knowledge Base**). Verification run deep links from the legacy Oracle reporting surface also redirect here. * **Links to**: * The **Review N pending** button takes you to `/knowledge-base/review`. * The "Used in N articles" chip on a fact links directly to the content editor for those specific articles. * Source URLs and external page links open in a new browser tab. ## Common support questions **Why is a page stuck on "Pending" or "Not scraped" in the Internal Links tab?** If a page has been pending for an extended period, the original scrape may have failed or timed out. Check the box next to the link and click **Refresh** in the command bar to restart the extraction. **If I delete a pillar, what happens to the facts inside it?** Deleting a pillar permanently deletes the pillar itself AND every claim filed under it. If you want to keep the facts, select them and use **Change pillar** to move them elsewhere before deleting the pillar. **What does "Archiving" a fact do?** Archiving a fact retires it from active use. It leaves the pillar's synthesized document and stops feeding content generation, but it isn't permanently deleted. You can view archived facts in the pillar's **Archived** tab and restore them if needed. **Why can't I select the "Extract from Content Hub" option?** That option relies on having articles published in the platform's Content Hub. If you haven't published any articles yet, or if they are still in draft mode, the list will be empty. **Why is the "Re-check" dropdown disabled for some of my links?** You can only schedule up to 25 links per website for automatic weekly or monthly re-checks. If you are at this cap, you must turn off an existing scheduled link before you can enable a new one. # Knowledge Base Pillar Detail Source: https://docs.athenahq.ai/guides/knowledge-base-pillarId Detailed working view of a single Knowledge Base pillar (topic), its facts/claims, sources, associated pages, generated document, and matching content. > [card] [Open in AthenaHQ](https://app.athenahq.ai/knowledge-base) > > `app.athenahq.ai/knowledge-base` ## Purpose The Knowledge Base Pillar Detail page gives you a deep dive into a specific topic (or "pillar") in your Knowledge Base. It serves as your central workspace to review and manage the individual facts and claims that make up this topic. From this page, you can see where each fact came from, approve or reject pending information, review the AI-generated synthesis document, and see how your website's content overlaps with the pillar. It is an essential tool for keeping your AI's understanding of your brand accurate and up to date. ## What's on the page ### Header The top of the page displays the pillar's title, description, and the date it was last researched. It includes a status dropdown to change the pillar's state and a `⋯` (kebab) menu containing pillar-level actions. ### Tabs Bar The page is organized into five main tabs, each showing a live count of items: * **Claims (N)**: The main view, listing all live facts associated with this pillar. * **Sources (N)**: Groups all approved facts by their originating source, showing the source name, an icon/favicon, and the count of facts from that source. * **Associated pages (N)**: Lists internal pages from your site that match this pillar, sorted by confidence match. * **Document**: Displays the AI-generated synthesis document for the pillar, formatted in markdown. * **Matching articles (N)**: Shows existing content on your site that overlaps with this pillar's claims, displaying a match percentage and the number of matched claims per article. ### Claim Cards On the **Claims** tab, each fact is displayed as a card containing: * **Fact text**: The actual claim text. * **Source chip**: A link to the URL or a badge indicating how the fact was captured (e.g., Web search, Upload). * **Status badge**: Indicates if the fact is "Approved", "Rejected", or "Pending review". * **Confidence**: Indicates the system's confidence level in the fact (e.g., "high confidence"). * **Usage chip**: Reads "Used in N articles". Hovering over this chip reveals a list of content articles grounded by this fact. * **Timestamp**: Shows when the fact was added or last reviewed. ### Fact Details View Clicking anywhere on the body of a claim card opens a dialog titled "Claim". This view displays the full fact text, the exact supporting excerpt ("Evidence"), any contextual notes, source links, and a link reading "View AI response →" if the claim originated from an AI response. ## What you can do here **Pillar-level actions** * **Change pillar status**: Use the dropdown in the header to switch the pillar between "Draft", "Published", "Researching", and "Archived". * **Edit pillar**: Inside the header's `⋯` menu, click "Edit" to open a dialog where you can change the pillar's title and description. * **Regenerate document**: Inside the header's `⋯` menu, click "Regenerate" to rebuild the synthesis document using the current set of approved facts. * **Export facts (CSV)**: Inside the header's `⋯` menu, click "Export facts (CSV)" to download a spreadsheet of the pillar's facts. * **Delete pillar**: Inside the header's `⋯` menu, click "Delete". You will be asked to confirm before permanently deleting the pillar and its facts. **Claim-level actions** * **Search facts**: Use the "Find in this pillar…" search box to filter the visible cards by matching text or source quotes. * **Add a claim**: Click the floating "Add claim" button in the bottom right of the Claims tab to manually enter a new fact and source URL. * **Filter by source**: On the Sources tab, click any row. This switches you back to the Claims tab and filters the list to show only approved facts from that specific source. A chip reading "Source: \[name] · approved only" will appear. Click the "Clear source filter" button (the X icon on the chip) to remove the filter. **Claim kebab menu actions (`⋯` on each card)** * **Approve**: Moves a pending claim to Approved. * **Reject**: Moves a pending or approved claim to Rejected. Rejecting an already-approved claim requires confirmation. * **Mark as pending**: Moves an approved or rejected claim back to the pending queue. * **Edit fact**: Opens the "Edit fact" dialog to modify the text, source URL, source excerpt, or confidence. (Not available for rejected facts). * **Change pillar**: Opens a dialog to re-file the claim to a different published pillar. * **Delete**: Permanently removes the fact. ## Data shown The information on this page comes from your Knowledge Base imports, automated site scanning, and manual fact additions. Usage chips reflect exactly where your approved facts have been utilized to generate content articles within the platform. ## Common workflows **Reviewing new facts** 1. Open the **Claims** tab. 2. Look for claim cards badged "Pending review". 3. Click the `⋯` menu on the card. 4. Select **Approve** to accept it or **Reject** to dismiss it. **Filtering facts by source** 1. Click the **Sources** tab. 2. Click a specific source row. 3. Review the filtered list of facts on the **Claims** tab. 4. Click the "Clear source filter" (the X) on the filter chip to return to the full list. **Correcting a fact** 1. On the **Claims** tab, click the `⋯` menu on the fact you want to fix. 2. Click **Edit fact**. 3. Make changes to the text, source URL, or confidence. 4. Click **Save**. **Re-filing a claim to a different pillar** 1. Open the `⋯` menu on a claim card. 2. Click **Change pillar**. 3. Search and select a target published pillar in the dialog. 4. Confirm the move. ## Empty, loading, and error states * **Empty**: * Claims tab: "No claims yet. Add claims below or run pillar research." * Document tab: "No document generated yet" alongside a "Generate document" button. * Matching articles tab: "No matching articles found". * Associated pages tab: "No pages linked yet" alongside a button to search the site. * Sources tab: "No sources yet". * Search: "No claims match this search." or "No facts from this source." if a filter yields nothing. * **Loading**: Gray skeleton blocks appear while the pillar data, tabs, and facts load. * **Error**: If the pillar ID does not exist or fails to load, a "Pillar not found." message is displayed with a link to go "Back to Knowledge Base". ## Linked from / links to * **Linked from**: The main Knowledge Base page (by clicking a pillar card), deep links from the content editor's claims sidebar, and links from verification reports. * **Links to**: The main Knowledge Base page (via the "Back" link or after deletion), content articles (via the "Used in N articles" hover links), and external source websites (via source chips and associated pages). ## Common support questions **Why can't I edit a rejected fact?** Rejected facts must be marked as pending before they can be edited. Click the `⋯` menu, select "Mark as pending", and then you can choose "Edit fact". **Where did my archived facts go?** Archived facts are hidden from the active pillar view to keep the workspace clean. You can view them in the main Knowledge Base by accessing the pillar's Archived tab there. **Why can't I delete a claim?** Only organization administrators have permission to permanently delete claims. If you are not an admin, the "Delete" action will be denied. **Why does exporting facts ask me to upgrade?** Exporting facts to a CSV file is a premium feature. If you are on a free subscription plan, clicking the export option will open a dialog to view paid plans instead of downloading the file. # Review Pending Claims Source: https://docs.athenahq.ai/guides/knowledge-base-review Lets a team review, approve, reject, delete, or re-file the queue of claims Athena extracted but couldn't auto-verify before they count toward published knowledge base pillars. > [card] [Open in AthenaHQ](https://app.athenahq.ai/knowledge-base/review) > > `app.athenahq.ai/knowledge-base/review` ## Purpose When Athena extracts factual claims from sources like web research, AI responses, or document uploads, it doesn't always automatically add them to your Knowledge Base. Athena holds back claims that it can't confidently verify on its own - such as low-confidence extractions, claims from pages outside your domains, or statements comparing your brand to competitors. Your domains are your brand's **Domains** on the Competitors page plus pages and domains marked **Owned** on the Sources page. `example.com` covers `www.example.com` but not other subdomains such as `help.example.com`; add the subdomain, or `*.example.com`, to include it. The **Review pending claims** page acts as a holding queue for these unverified facts. It allows customers to review the extracted claims, decide which ones belong in their published pillars, and clear out irrelevant or incorrect extractions by rejecting or deleting them. ## What's on the page **Page header** Features the page title "Review pending claims" and a "Back to Knowledge Base" link to return to the main Knowledge Base view. **Intro copy** Explains why claims end up in this queue and displays the current pagination range (e.g., "Showing 1–100 of 250."). **Filter & scope bar** When no claims are selected, this bar provides tools to narrow down the queue: * **Confidence tabs:** Filters claims by Athena's extraction confidence ("All", "High", "Medium", "Low"). * **Source tabs:** Filters claims by their origin ("All sources", "Web research", "AI responses", "Uploads", "Your site"). * **Pillar filter:** A dropdown labeled "All pillars" (with a "Search pillars…" prompt) that restricts the view to claims suggested for a specific pillar. * **Search claims:** A search input to filter claims by specific keywords. **Selection toolbar** When one or more claims are checked, the pillar filter and search input swap out for a bulk action toolbar. It shows the number of selected claims (e.g., "2 selected"), a "Clear" button (with an "Esc" shortcut badge), and bulk action buttons for "Approve", "Reject", and "Delete". **Select-all-matching banner** If a user checks the "select all visible" checkbox in the list header, a banner appears below it. If the filtered queue spans multiple pages, the banner states "All \[N] claims on this page are selected" and provides a link to "Select all \[Total] matching claims". Once activated, it switches to "All \[Total] claims matching this filter are selected" with a "Clear selection" link. **Pending claims list** The main area displaying the claims to be reviewed. The table header contains a master checkbox to select all visible claims and text summarizing the page (e.g., "100 reviewable · 5 without pillar"). Each row represents one claim. * **Checkbox:** Selects the claim for bulk actions. * **Claim text:** The full extracted statement. * **Pillar link / Assign a pillar:** If the claim was auto-suggested for a pillar, the pillar's name is shown as a clickable link. If the claim is unfiled, a dashed "+ Assign a pillar" button appears instead. * **Confidence badge:** Shows "high confidence", "medium confidence", or "low confidence". * **Source badge:** Displays the claim's origin (e.g., "Web research", "AI response", "Upload", "Your site", "Manual"). * **Source link:** An external link to the original webpage, if a URL was recorded. * **Source quote:** An italicized quote from the source text that supports the claim. * **Row actions:** Inline buttons to "Approve", "Reject", or "Delete" the specific claim. **Pagination footer** Provides "Previous" and "Next" buttons to page through the queue, 100 claims at a time. **Assign a pillar dialog** A popup that opens when clicking "+ Assign a pillar" on an unfiled claim. It contains a searchable list of published pillars and an "Assign" button to file the claim. ### Drilldowns * **Clicking a pillar name:** Navigates to the detail page for that specific pillar. * **Clicking "Assign a pillar":** Opens the "Assign a pillar" dialog. * **Clicking the "Source" link:** Opens the original source webpage in a new browser tab. ## What you can do here * **Filter claims:** Use the confidence tabs, source tabs, pillar dropdown, and search box to narrow the queue. Changing any filter resets your current selection and returns you to page 1. * **Select claims:** Check the box next to individual claims, or click the master checkbox in the header to select all claims on the current page. * **Select all matching claims:** After selecting all visible claims on a page, click the "Select all N matching claims" link in the banner to reject or delete across the entire filtered queue. Approval works on the selected page only. * **Bulk Approve:** Click "Approve" in the selection toolbar to approve the selected claims on the visible page into their respective pillars. Approval is disabled in all-matching mode. Tooltips explain the action (e.g., "Approve 5 claims across 2 pillars"). If claims lack a pillar, the tooltip notes "N selected claims can't be approved without a pillar". * **Bulk Reject:** Click "Reject" in the selection toolbar to discard the selected claims. If in "all matching" mode, you will be asked to confirm "Reject all N matching claims?". The button changes to "Rejecting… X of N" while processing. * **Bulk Delete:** Click "Delete" in the selection toolbar. A confirmation dialog asks "Delete N claim(s)?" (or "Delete all N matching claims?"). The button changes to "Deleting… X of N" while processing. * **Approve (per row):** Click the inline "Approve" button to move a single claim into its assigned pillar. Disabled if the claim has no pillar. * **Reject (per row):** Click the inline "Reject" button to discard a single claim. * **Delete (per row):** Click the inline "Delete" button (trash icon). You will be asked to confirm "Delete claim?". * **Assign a pillar:** Click "+ Assign a pillar" on an unfiled claim, select a published pillar from the dropdown, and click "Assign". The claim remains in the queue but can now be approved. * **Clear selection:** Click the "Clear" button in the toolbar, click the "Clear selection" link in the banner, or press the `Escape` key on your keyboard. * **Undo a rejection:** When rejecting a selection on the current page, a success toast appears saying "Rejected N claims" with an "Undo" button. Clicking it restores the claims back to the pending queue. ## Data shown The list displays pending (unreviewed) factual claims extracted by Athena for your tracked website. The pillar dropdown and assignment dialog display your published Knowledge Base topics. ## Common workflows **Review and approve a batch of high-confidence claims** 1. Click the "High" confidence tab to show only high-confidence extractions. 2. Check the master checkbox in the list header to select all visible claims. 3. Click the "Approve" button in the selection toolbar. 4. A toast confirms the approval, and the list refreshes to show the next batch. **Mass-reject an entire filtered queue** 1. Apply filters (e.g., source: "AI responses" and a specific pillar). 2. Check the master checkbox in the list header to select the current page. 3. Click "Select all \[N] matching claims" in the banner that appears. 4. Click "Reject" in the toolbar and confirm the prompt. 5. The system processes the rejections in batches, updating the button progress until finished. **File an unfiled claim into a pillar** 1. Locate a claim displaying the "+ Assign a pillar" button. 2. Click the button to open the assignment dialog. 3. Search for and select an existing published pillar. 4. Click "Assign". The claim row updates with the new pillar name and the "Approve" button becomes active. **Delete a single claim permanently** 1. Click the trash icon on the claim's row. 2. Read the confirmation dialog warning that deleted claims can be re-imported later. 3. Click "Delete" to permanently remove the claim. **Undo an accidental rejection** 1. After clicking "Reject" on a selection, look for the "Rejected N claims" toast notification. 2. Click "Undo" on the toast before it disappears. 3. The claims reappear in the pending list under their original pillars. ## Empty, loading, and error states * **Empty:** If the entire queue is empty, the page 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 or another search." * **Loading:** While fetching claims, the page displays a stack of skeleton placeholder rows. * **Errors:** If a bulk action (approve, reject, delete) fails completely or partially, a red error toast or a yellow warning toast appears. The list automatically refreshes to show the actual remaining claims. ## Linked from / links to * **Linked from:** The main Knowledge Base page (via the "Review N pending" call-to-action button). * **Links to:** Pillar detail pages (via topic links in the rows), external source URLs (via the "Source" links), and back to the main Knowledge Base (via the top-left "Back to Knowledge Base" link). ## Common support questions **What's the difference between Reject and Delete?** Rejecting a claim keeps it hidden in the background so Athena knows never to extract or import that specific fact again. Deleting a claim removes it entirely, freeing up space, but means Athena might re-extract the same fact during a future research run. **Why is the "Approve" button grayed out on some claims?** Claims must belong to a pillar before they can be approved. If a claim doesn't have a pillar, you must click "+ Assign a pillar" to file it first. **Why can't I bulk approve all matching claims across multiple pages?** "Select all N matching claims" lets you mass-reject or mass-delete, but bulk approval is disabled in this mode. Because claims are approved directly into their assigned pillars, you must review and approve them page-by-page. **Where did the "Select all matching claims" button go?** If you uncheck any individual row, or if you change pages or filters, the selection drops back to just the visible items on your current page. # Olympus Dashboard Source: https://docs.athenahq.ai/guides/olympus The main analytics dashboard showing AI search visibility metrics (mentions, citations, share of voice, position, and business value) for the active website, with customizable cards, saved views, and export/reporting tools. > [card] [Open in AthenaHQ](https://app.athenahq.ai/olympus) > > `app.athenahq.ai/olympus` ## Purpose The Olympus dashboard is the primary analytics hub for tracking how a brand performs across major AI search engines and conversational models. It aggregates data into customizable cards that measure brand mentions, citations, share of voice, positioning against competitors, and estimated financial impact. Marketers use this page to understand their competitive stance in AI search, see the direct results of their content optimization efforts, and extract actionable reports to share with their teams. ## What's on the page **Filter Bar** * A row of filters including Date range, Schedule, Models, Competitors, Prompts, Personas, and Locations. * **Saved Views**: A dropdown to save the current filter combination or load a previously saved one. **Stat Cards** * **Responses Analyzed**: Total AI responses analyzed across all tracked prompts and models. * **Sources Tracked**: Number of unique sources cited in AI responses. * **Attributed Citations**: Percentage of responses that cite your tracked content. **Metric Cards** * **Share of Voice**: A donut chart and ranked list showing how often AI mentions the brand versus competitors. * **Share of Voice by Model**: Shows the brand's visibility on each individual AI model. Includes a "Simple" and "Detailed" toggle. * **Daily Share of Voice**: A line chart tracking daily Share of Voice trends over time. * **Mention Rate**: An area chart showing the brand's and competitors' mention rates. Includes a "Show Absolute" and "Show Relative" toggle. * **Mention Rate by Model**: A line chart showing the share of each model's responses that mention the brand. * **Citation Rate**: An area chart showing how often AI cites the brand's content versus competitors. * **Citation Rate by Model**: A line chart showing the share of each model's responses that cite the brand. * **Position over Time**: Tracks the brand's ranking among mentioned brands in AI responses. * **Position by Model**: The brand's rank against tracked competitors, broken down per model. * **AI Search Value**: A gauge estimating what the brand's presence in AI answers is financially worth, based on search volume and CPC data. * **Dollar Value Captured**: A legacy stat card showing estimated advertising value captured from AI presence. * **Competitor Heatmap**: A matrix comparing brand versus competitor visibility across topics. When a baseline period is selected, cells with data in both periods also show the change against that baseline. * **Sources Visualization**: A Sankey diagram connecting source domains to the brands they drive mentions for. * **Attributed Citations Growth**: Tracks the growth of citations to tracked content over time. * **Top Attributed Content**: Source URLs most frequently cited by AI models. * **Most Cited Content**: Top pages from the website appearing in AI responses. * **Brand Traits, Positive Mentions**: Distribution of positive mentions of brand traits in AI responses. * **Brand Traits, Negative Mentions**: Distribution of negative mentions of brand traits in AI responses. Every metric card includes an info icon. Hovering shows a "Click for details" tooltip; clicking it opens a dialog explaining exactly what the metric means and how it is calculated. ## What you can do here * **Filter Data**: Apply filters to update all charts and metrics to reflect specific dates, models (e.g., ChatGPT, Claude, Gemini, Perplexity, Grok, Copilot, Meta AI, DeepSeek, Mistral), or competitors. * **Export as PNG / Export as PDF**: Found under the Export button. Exports your selected dashboard cards in their configured order, including cards below the current viewport. PNG and PDF use the same chart captures. PDF export is gated behind a paid subscription plan. * **Export as CSV**: Found under the Export button. Downloads the raw metrics data as a spreadsheet. Gated behind a paid subscription plan. * **Customize Dashboard Layout**: Under the "More actions" menu, click "Dashboard settings" to open a modal where you can toggle specific cards on or off. * **Reorder Cards**: Drag any card by the grip handle in its top-right corner to change the dashboard's layout. * **Resize Cards**: Drag the bottom-right corner of compatible cards to make them span multiple columns or rows. * **Manage Reports**: Under the "More actions" menu, click "Manage reports" to open a dialog. Here you can configure automated recurring reports to be delivered via email or Slack. You can click "New report" to create one, or use the row menu (⋯) to select "Preview and test", "Edit", or "Delete". * **Drill Down into Data**: * Clicking the "Responses Analyzed" card takes you to the Responses page. * Clicking the "Sources Tracked" card takes you to the Sources page. * Clicking the "Attributed Citations" card takes you to the Responses page filtered by attributed citations. * Clicking a cell on the "Competitor Heatmap" drills down into the Prompts page for that specific topic and competitor. * Clicking the "What's Working" card opens the full win analysis report. ## Data shown The dashboard aggregates AI response data collected for the website's tracked prompts. When calculating financial metrics like "AI Search Value", it combines the brand's measured AI share of voice with real-world Google keyword search volume and cost-per-click data. Traffic metrics (used in "What's Working") incorporate connected website analytics like sessions, impressions, and clicks. ## Common workflows ### Compare share of voice by model Open the **Share of Voice by Model** card. Choose **Simple** to compare your brand across models or **Detailed** to see your brand and tracked competitors in each model's stacked column. Models that answered without mentioning a tracked brand can still appear with zero share of voice; this does not mean their responses are missing. ### Share a filtered dashboard Set the date range, schedule, models, and other filters, then copy the browser URL. The link preserves the active filter selection for another user with access to the website. Save a view for a reusable dashboard scope. Rolling date ranges move forward over time; fixed date ranges stay on their chosen dates. **Exporting an executive report** 1. Use the filter bar to set the desired Date range and Schedule. 2. Click the Export button (⬇) in the page header. 3. Select "Export as PDF" to download a PDF of all selected dashboard cards. **Setting up a recurring automated report** 1. Click the "More actions" menu (⋯) in the header. 2. Select "Manage reports". 3. Click the "New report" button. 4. Configure the delivery cadence, recipients (Slack or Email), and select which charts to include. **Adding the "By Model" charts to the dashboard** 1. Click the "More actions" menu (⋯) in the header and select "Dashboard settings". 2. Locate the "Visibility" section in the sidebar. 3. Toggle on "Share of Voice by Model", "Mention Rate by Model", or "Position by Model" (these are hidden by default). 4. Click "Done" to save the layout. ## Empty, loading, and error states * **Loading**: A centered animated spinner appears with screen-reader text saying "Loading Olympus" while the dashboard probes to see if data exists. * **Empty (No data ingested)**: If the site hasn't collected any data yet, the dashboard skips loading card skeletons and directly shows an empty state reading "No data yet for this website" (or "No results yet for this schedule") alongside a "Stream Data" button. * **Empty (Filters exclude data)**: If data exists but the current filters are too narrow, the dashboard displays "No data matches the selected filters" with a "Clear Filters" button. * **Error**: If the dashboard fails to load data availability, it displays "Could not load Olympus. Check your connection and try again." with a "Try again" button. ## Linked from / links to * **Linked from**: The main sidebar navigation, the onboarding completion redirect, and the global tour system. * **Links to**: The Responses page, Sources page, Prompts page, Wins page, and tracked content pages via card drilldowns. ## Common support questions **Why don't I see the "Mention Rate by Model" or "Position by Model" cards?** To prevent the dashboard from becoming too cluttered, the per-model breakdown cards are hidden by default. You can enable them at any time by clicking "More actions", selecting "Dashboard settings", and toggling them on. **Why is my AI Search Value percentage lower than my Share of Voice percentage?** The AI Search Value card uses a position-weighted, value-weighted share over non-branded commercial topics to reflect true commercial impact. The main Share of Voice chart counts every mention equally across all topics, including branded queries where you naturally dominate. **Why does clicking "Export as PDF" prompt me to upgrade?** Exporting data via PDF or CSV is a premium feature. If you are on a free plan, clicking these options will display an upgrade dialog detailing the plans available to unlock data exports. **What does the "Show Absolute" vs "Show Relative" toggle do on the Mention Rate card?** "Show Relative" divides your mentions by only the AI responses that contained at least one tracked brand (yours or a competitor's). "Show Absolute" divides your mentions by *all* AI responses analyzed, giving you a sense of total market penetration. # Oracle Source: https://docs.athenahq.ai/guides/oracle Scan AI-generated responses against the knowledge base to surface confirmed inaccuracies, knowledge-base inconsistencies, and model disagreements, and let the customer review/resolve them. > [card] [Open in AthenaHQ](https://app.athenahq.ai/oracle) > > `app.athenahq.ai/oracle` ## Purpose Oracle is an automated QA and verification tool for your brand's AI search presence. It scans the AI-generated responses collected from your tracked prompts and cross-references them against your Knowledge Base. By automatically checking what AI models (like ChatGPT, Claude, and Gemini) say about your brand against your verified facts, Oracle surfaces confirmed inaccuracies, internal contradictions within your Knowledge Base, and disagreements between different AI models. This allows you to quickly triage AI hallucinations and take action to correct the record. ## What's on the page **Page Header** The top bar includes the page title, a brief description, a clock icon for the **Run history** menu, and the main **Run Oracle** (or **Cancel**) button. **Run Status Banner** Visible only while an Oracle scan is actively running. It displays the current stage (e.g., "Gathering responses", "Verifying claims"), the number of responses scanned so far, and an estimated time remaining. **Overview Dashboard** When a run is complete (or while it's processing but has finished verifying claims), you will see the main results dashboard: * **Inaccuracy stat card:** Shows the percentage of scanned responses that contained a confirmed inaccuracy, along with the raw count of flagged responses. * **Responses scanned stat card:** Shows the total number of AI responses analyzed in this run. If the system hit a limit and couldn't scan every eligible response, a "Stream capped" note will appear here. * **Priority findings:** A list of up to 5 high-impact (Critical or Major) inaccuracies found during the run. Each row displays the severity, the false AI claim, and the true Knowledge Base fact. You can click "See all" to view the full queue. * **Knowledge base issues:** A collapsible section showing places where your Knowledge Base contradicts itself. * **Model disagreements:** A collapsible section showing instances where two different AI models provided conflicting answers to the same prompt. **Charts** * **Accuracy by model:** A bar chart showing the percentage of sampled responses that had *no* confirmed findings, broken down by AI model (e.g., ChatGPT, Claude). Tooltips reveal the exact number of flagged vs. scanned responses for that model. * **Topics AI gets wrong:** A bar chart grouping confirmed findings by the model-generated Knowledge Base topic tag on the contradicted fact. (e.g., "Features", "Pricing"). * **Prompt topics:** A bar chart grouping confirmed findings by the taxonomy topic of the prompt that originally surfaced the bad response. **Finding Review Overlay (Drilldown)** Clicking a priority finding or the "See all" button opens a full-screen review flow. It displays the full detail for a single finding, including the false claim, the true fact, and cited evidence. From here, you can step through findings and triage them. **AI Response Drawer (Drilldown)** Clicking "View response" inside a finding opens a side drawer displaying the complete text of the AI response, with the problematic quote highlighted. **Fact Editor (Drilldown)** Clicking "Open fact" or "Edit fact" inside a finding opens the Knowledge Base editor, allowing you to update the underlying truth immediately without leaving Oracle. ## What you can do here * **Run a scan:** Click the **Run Oracle** button in the top right to start a new analysis of the latest completed prompt run against your current Knowledge Base. * **Cancel a scan:** Click **Cancel** in the top right if you need to stop an in-progress run. * **Switch between past runs:** Click the clock icon (Run history) to open a dropdown of your past scans. Select any date/time to load that run's dashboard. * **Review a finding:** Click any row in the "Priority findings" list to open the detailed review overlay. * **Acknowledge a finding:** Inside the review overlay, click **Acknowledge** to mark the finding as reviewed. Oracle will reconsider it on the next run. * **Ignore a finding:** Click **Ignore** to dismiss a finding if it is not actionable. * **Reopen a finding:** If you previously acknowledged or ignored a finding, click **Reopen** to move it back to Pending for review. * **Edit a Knowledge Base fact:** While reviewing a finding, click **Edit fact** to fix the underlying Knowledge Base entry. ## Data shown Oracle data is built from the latest completed prompt run and cross-referencing their claims against the verified facts you've added to your Knowledge Base. Findings are generated using AI to detect genuine contradictions between the two datasets. ## Common workflows **Running a new Oracle scan** 1. Navigate to the Oracle page. 2. Click the **Run Oracle** button in the top right corner. 3. Wait for the scan to progress through its stages (Gathering responses, Comparing, Verifying, etc.). 4. Once complete, review the Overview Dashboard to see your inaccuracy stats and prioritize findings. **Reviewing and resolving a finding** 1. On a completed run's dashboard, click any row under **Priority findings** or click **See all**. 2. In the review overlay, read the false AI claim alongside your true Knowledge Base fact and the cited evidence. 3. If the fact needs updating, click **Edit fact**. 4. When you are done investigating, click **Acknowledge** or **Ignore** to clear the finding from your pending queue. ## Empty, loading, and error states * **Setup Empty State:** If your Knowledge Base has fewer than 25 facts, the page shows "Set up your knowledge base first." You cannot run Oracle until this minimum is met. * **First-run Explainer:** If your Knowledge Base is ready but you haven't run Oracle yet, you'll see an explainer reading "Find what AI gets wrong about your brand" with a button to trigger your first run. * **Loading:** While switching runs or waiting for a run to finish, a skeleton placeholder of the dashboard cards is shown. * **Errors:** If a run fails, a red warning box appears explaining why. Specific reasons include: * *Knowledge base too large/small to audit.* * *No responses to scan* (if recent prompt runs yielded no readable responses). * *This website tracks more than 2,000 live prompts* (the supported scope was exceeded; contact AthenaHQ support). * *The last scan failed* (generic failure). * **Access Error:** If the billing service is unreachable, a "Couldn't verify access" error screen appears with a "Retry" button. ## Linked from / links to * **Linked from:** The main sidebar navigation, and the Knowledge Base page (which directs users here for verification flows). * **Links to:** The Knowledge Base (to fix facts/topics), and Content pages (to view remediation drafts). ## Common support questions **Why can't I click "Run Oracle"?** The button will be disabled if you do not have enough verified facts in your Knowledge Base (you need at least 25), or if you have just added prompts and the system is still waiting for your first round of AI responses to finish collecting. **What does "Stream capped" mean on my responses scanned?** To protect performance and manage limits, Oracle can only pull up to a certain maximum number of responses per run (usually 100,000). This limit applies to the latest completed prompt run, not to every response collected since the last Oracle scan. If it is reached, the dashboard warns that the stream was truncated; interpret the results as incomplete and contact support. **Why does a past run say "Imported history" and show no accuracy rate?** Runs that were backfilled from older versions of Oracle do not have the raw response samples needed to calculate an exact accuracy percentage. They will only show the total count of findings discovered on that date. # Outreach Source: https://docs.athenahq.ai/guides/outreach Triage pages AI cites as outreach opportunities: find authors, draft pitches, and track outreach status through a Kanban pipeline. > [card] [Open in AthenaHQ](https://app.athenahq.ai/outreach) > > `app.athenahq.ai/outreach` ## Purpose The Outreach page helps customers leverage their AI search performance for link-building and PR. It serves as a triage center for the web pages that AI models are citing in response to the customer's tracked prompts. From this page, users can discover which high-impact pages already cite them (or their competitors), use AI to find the authors of those pages, draft personalized outreach emails, and track the entire pitch process from "New" to "Done" using a built-in Inbox and Kanban board. ## What's on the page **Page Header** Displays the page title, a brief description of its purpose, and a toggle to switch between the **Inbox** tab (a list-based triage view) and the **Board** tab (a Kanban pipeline view). **Filter Bar** Contains saved views and a standard set of filters (Search, Date range, Prompt tags, Models, etc.) that control which opportunities appear. On the right, it features a **Tags** button and a **⋯** (More options) menu. **Opportunity List (Inbox Tab)** A scrollable, sortable table listing all cited pages that match the current filters. * **(checkbox):** Used to select specific rows for bulk actions. Checking the top header checkbox selects or deselects all currently loaded rows. * **Page:** Shows the website's favicon, root domain, and specific URL path. * **Status:** The current stage of the opportunity in the pipeline (`New`, `Todo`, `In Progress`, `Done`, or `Rejected`). * **Citation %:** The percentage of responses that cited this specific URL. * **Est. impr.:** Estimated monthly impressions for this URL, based on the search volume of the prompts that cited it. * **Citations:** Total absolute number of times this URL was cited. * **Mentioned:** Indicates whether the customer's brand was mentioned in the responses citing this URL. Values are `Yes`, `No`, or `No data`. Tooltip for No data: *"Page could not be scraped, so brand presence is unknown."* * **Competitors:** Displays logos of tracked competitors mentioned alongside this URL. Also uses the `No data` badge and tooltip if the scrape failed. **Opportunity Detail Panel (Inbox Tab)** Appears on the right side of the screen when a row is selected. * **Header:** Shows the domain, path, a link to **View analytics**, and buttons to open the URL in a new tab or close the panel. * **Properties:** Dropdowns to change the pipeline **Status** and assign a teammate via the **Assignee** picker. * **Metrics summary:** Shows Citation rate, Est. impressions, Citations, AI access status, First seen date, Brand mentioned, and Competitors. * **Author section:** Tools to find or manually enter the author's name, email, and LinkedIn profile. * **Message section:** Tools to draft, edit, and send a personalized pitch email. **Kanban Board (Board Tab)** Organizes outreach targets into draggable columns representing their status: **Todo**, **In Progress**, **Done**, and **Rejected**. **Bulk Action Bar** A floating bar at the bottom of the screen that appears when one or more rows are checked in the Inbox list. Shows the count of selected items and available bulk actions. ## What you can do here **Navigation & View Management** * **Switch views:** Click the **Inbox** or **Board** tabs in the top header to change how opportunities are displayed. * **Manage Tags:** Click the **Tags** button in the filter bar (or inside the mobile overflow menu) to open the Source Tags drawer. Here you can create, edit, or delete custom tags for domains and pages, either manually or by uploading a CSV. * **Export as CSV:** Click the **⋯** menu (More options) in the filter bar and select **Export as CSV** to download the currently filtered list of opportunities. **Inbox Triage & Bulk Actions** * **Open detail panel:** Click any row in the Inbox list (or press `Enter` while the row is highlighted) to view the Opportunity Detail panel. * **Sort list:** Click the Sort dropdown in the list header (e.g., "Citation %") to change the sorting criteria. Clicking the active criteria again flips it between ascending and descending. * **Bulk actions:** Select rows using the checkboxes. From the floating bulk bar, you can: * **Find authors:** Runs AI extraction for all selected rows to find author names and contact info. * **Draft messages:** Generates AI pitch emails for all selected rows. * **Start:** Moves selected rows to the "In Progress" status. * **Reject:** Moves selected rows to the "Rejected" status (removing them from the default active queue). * **Clear selection:** Deselects all rows (can also be done by pressing `Escape`). * **Cancel bulk progress:** If a bulk "Find authors" or "Draft messages" task is running, click **Cancel** to stop any remaining pages in the queue from processing. **Working in the Detail Panel** * **Change Status & Assignee:** Use the dropdowns at the top of the panel to update the status or assign the opportunity to a teammate. Both actions are recorded in the Activity history. * **Find author:** Click **Find author** to automatically search the page for contact details. * **Edit author:** Click **Edit** in the Author section to manually type or fix the author's Name, Email, or LinkedIn URL, then click **Save**. * **Customize prompt:** Click the gear icon (**Customize the generation prompt**) in the Message section to add specific instructions for the AI on how to write your pitch (e.g., tone, product highlights). * **Draft message:** Click **Draft message** to have the AI write a pitch email based on the website's content and your custom instructions. * **Edit message:** Click **Edit** (or press `⌘E`) to manually adjust the Subject line or Message body. Click **Save** (or press `⌘S` while typing) to keep your changes. * **Send email:** Once a draft is saved, click **Open in mail client** (or press `⌘⏎`) to open your computer's default email app with the To, Subject, and Body fields pre-filled. * **Copy contents:** Click the copy icon next to the email address to copy just the email. Press `⌘⇧C` to copy the full composed email (To, Subject, and Message). * **Check AI Access:** Click the AI access badge to scan whether the target domain blocks AI bots from reading it. **Working on the Kanban Board** * **Move cards:** Drag and drop cards between columns to update their status (e.g., from Todo to In Progress). * **Reorder priorities:** Drag cards up or down within the same column to reorganize priorities. This sort order is shared team-wide. * **Assign teammates:** Click the circular avatar icon on any card to quickly assign or reassign it. * **Open detail panel:** Click anywhere else on a card to immediately switch to the Inbox tab with that opportunity's detail panel open. **Keyboard Shortcuts (Inbox)** * `j` or `↓` / `k` or `↑`: Move the cursor highlight up and down the list. * `Enter`: Open the detail panel for the highlighted row. * `x`: Reject the highlighted row (or bulk-reject if rows are checked). * `s`: Start (mark "In Progress") the highlighted row or selection. * `a`: Bulk "Find authors" (only works when rows are checked). * `d`: Bulk "Draft messages" (only works when rows are checked). * `o`: Open the highlighted row's URL in a new browser tab. * `Escape`: Clears row selections. If no rows are selected, closes the detail panel. ## Data shown The page displays distinct URLs cited by AI models across the prompts the customer is tracking. The citation and impression metrics align with whatever date range, prompt, or model filters the user has applied in the top filter bar. Contact information (author name, email, LinkedIn, message drafts, status, and assignee) is saved specifically to the customer's workspace. Competitor logos populate based on the competitors the customer has configured for their brand. ## Common workflows **Triage a new opportunity** 1. Go to Outreach and ensure you are on the **Inbox** tab. 2. Click a promising row to open its detail panel. 3. Click **Find author** to automatically extract contact info, or click Edit to enter it manually. 4. Click **Draft message** to generate an AI outreach pitch. 5. Click **Open in mail client** to send the email from your own outbox. 6. Change the status dropdown from "Todo" to "In Progress", and eventually to "Done" once the placement is secured. **Bulk enrich and draft for many pages** 1. In the Opportunity List, check the boxes next to multiple target rows (or use the header checkbox to select all). 2. In the floating bulk action bar at the bottom, click **Find authors** to enrich all selected rows at once. 3. Next, click **Draft messages** to pre-write pitches for all of them. 4. A progress indicator will appear, followed by a toast summarizing how many succeeded or failed. 5. Use the bulk bar to click **Start** to move them all into the "In Progress" pipeline. **Track outreach on the Kanban board** 1. Click the **Board** tab in the page header. 2. Review opportunities currently in the "Todo" column. 3. Drag a card into "In Progress" as you begin working on it. 4. Click the avatar icon on the card to assign it to the team member handling the outreach. 5. Once the outreach is successful or concluded, drag the card into "Done" or "Rejected". ## Empty, loading, and error states * **Loading:** A centered animated loader appears while opportunity lists or Kanban data are being fetched. * **Empty Inbox:** Shows a "No opportunities match these filters" message with advice to widen the date range, clear filters, or check the Opportunity status filter if looking for rejected items. * **Empty Board:** Shows "Nothing in the pipeline yet" and explains that starting or drafting an opportunity in the inbox will make it appear on the board. * **Error:** Displays "Unable to load outreach data. Please try again." along with a "Try again" button to attempt reloading the data. ## Linked from / links to * **Linked from:** The main sidebar navigation ("Outreach"). Can also be reached via deep links (e.g., URLs containing `?tab=board` or `?sel=` to auto-open a specific opportunity). * **Links to:** The Source Analytics page (via the "View analytics" button in the detail panel). Also links out to external target URLs and native email clients. ## Common support questions **Why are some opportunities labeled "Rejected"?** Opportunities you mark as "Rejected" are removed from the default active queue so you can focus on viable targets. You can still view them by changing the "Opportunity status" filter in the top bar to include canceled/rejected items. **How are credits used here?** The "Find authors" and "Draft messages" actions each cost 0.1 credits per successful row. You are billed in whole-credit increments as successes add up. If the AI fails to find an author or fails to write a draft for a row, you are not charged for that row. **I accidentally rejected a page. Can I bring it back?** Yes. Immediately after rejecting, an "Undo" option appears in a toast notification. If you miss the toast, open the filter bar, change the "Opportunity status" filter to include rejected items, find the row, click it, and change its status back to "Todo" or "New". **Why don't I see any metrics for my selected opportunity?** If you navigate directly to a URL link for an opportunity that doesn't match your current date range or prompt filters, the panel will display a message reading: *"This page isn't in the current opportunity feed."* You can still edit the contact info and drafts, but citation metrics won't display until you adjust your filters to include it. **Why can't I access the Outreach page?** The Outreach workflow is a premium feature. Organizations on a Free plan will see an upgrade lock screen instead of the tool. You will need to upgrade your subscription plan to unlock it. # Pitch Workspace Report Source: https://docs.athenahq.ai/guides/pitch-workspace Shows the AI-visibility report for the organization's currently active pitch (brand vs. competitors across AI search engines), redirecting to pitch creation if no pitches exist. > [card] [Open in AthenaHQ](https://app.athenahq.ai/pitch-workspace) > > `app.athenahq.ai/pitch-workspace` ## Purpose This page displays the AI search visibility report for your currently selected pitch. It gives you a snapshot of how your brand and your competitors appear across various AI search engines (like ChatGPT, Gemini, and Perplexity) for the prompts you tracked. The report helps you understand your market position, which AI models favor your brand, what traits are associated with you versus your competitors, and which sources AI models cite most frequently. It also provides a detailed breakdown of every individual AI response collected during the pitch analysis. ## What's on the page **Page header** Shows the company name and logo for the pitch, along with a **Copy link** button. The page title itself indicates when the report was audited. **Zero mentions notice** If the report legitimately found zero brand and competitor mentions across all responses, a notice card appears to explain that this is a real finding and not an error. It clarifies that AI models currently answer the tracked prompts with general advice or other brands. **Landing page CTA** If this pitch was generated as a "landing page" preview report, a promotional banner appears at the top encouraging visitors to book a demo or view pricing. **Metric cards row** Four top-level statistics summarizing the report. These cards can be dragged and dropped to reorder them. * **Share of voice**: Displays your percentage of mentions compared to all brands. Includes an info icon tooltip: "The percentage of mentions your brand receives compared to all brands. Click for details." Clicking the icon opens a dialog explaining the Share of Voice calculation. * **Brand mentions**: Displays the percentage of responses mentioning your brand. Includes an info icon tooltip: "Percentage of AI responses that mention your brand. Click for details." Clicking the icon opens a dialog explaining Brand Mention Rate. * **Responses analyzed**: The raw count of responses processed. Includes an info icon tooltip: "Total AI responses collected and analyzed for this report". * **Models tested**: The number of distinct AI models queried. Includes an info icon tooltip: "AI models queried while building this report". **Share of voice** A pie/donut chart comparing your brand's percentage share of AI mentions versus your competitors. The legend lists each brand, its logo, and its percentage. You can drag and drop this card to reorder it. **AI model performance** A ranked list showing how often each AI model (e.g., ChatGPT, Gemini, Perplexity) mentioned your brand, complete with a percentage and a progress bar. You can drag and drop this card. **Positive brand traits / Negative brand traits** Radar charts comparing the frequency of positive and negative attributes mentioned about your brand versus all competitors. These cards only appear if there is data for them. You can drag and drop these cards. **Top citation sources** A ranked list of domains that AI models cited most frequently when answering the prompts in this pitch. You can drag and drop this card. **Competitive landscape** A list ranking your brand and every tracked competitor by their share of all brand mentions. Displays logos and percentage bars. You can drag and drop this card. **Responses table** A searchable, infinitely scrolling table listing every individual AI response collected for the pitch. ### Responses table columns * **Model**: Which AI model generated this response (e.g. ChatGPT, Gemini, Perplexity, AI Mode), accompanied by its icon. * **Mentioned**: Whether your tracked brand was mentioned in this specific AI response (indicated by a "Yes" or "No" pill). * **Competitors Mentioned**: Displays logos of competitor brands mentioned in the response. If more than four competitors are mentioned, a "+N" overflow indicator appears. * **Prompt**: The specific prompt variation that was sent to the AI model. Search terms are highlighted in yellow if you use the search bar. * **Response**: A truncated preview of the raw AI response text. Search terms are highlighted in yellow. ### Drilldowns * **Share of voice or Brand mentions info icons**: Clicking the info icon on these two metric cards opens an in-page dialog explaining the metric, how it is calculated, and why it matters. * **Response detail drawer**: Clicking any row in the **Responses** table opens a side panel ("Response Details") containing the full metadata for that response. It shows the Date, Model, Prompt Type, Mentioned status, Market Position, and Competitors Mentioned. It also displays the Base Prompt, the specific variation used, and the full response text with highlighted citations and source chips. For Google AI Overview responses, it adds collapsible sections for **Organic Results**, **People Also Ask**, and **Related Searches**. You can navigate to adjacent responses using the up/down arrows in the header or your keyboard. ## What you can do here * **Copy public link**: Click **Copy link** in the top right to copy a public, shareable URL for this report. You can send this link to anyone, and they can view the report without logging in. * **Reorder cards**: You can click and drag the top-level metric cards to rearrange them within their row. You can also drag and drop the larger report cards (charts, tables, lists) to customize the layout of the page. * **Search responses**: Type in the **Search responses** input field above the Responses table to filter the list. This matches your text against the prompt variation and the raw response text. * **View response details**: Click any row in the Responses table to open the Response Details drawer. Inside the drawer, you can click on source citation links to visit the cited websites, or click through to Organic Results (for AI Overviews). * **Navigate responses**: While the Response Details drawer is open, use the up/down arrow buttons in the drawer header, or the up/down arrow keys on your keyboard, to quickly move to the previous or next response. ## Data shown Data on this page comes from the specific AI search visibility pitch you have selected. It includes the AI responses collected across all configured models (like ChatGPT, Gemini, Claude, Perplexity, etc.), the prompts that were tested, the competitors you opted to track, and the brand attributes identified in the AI answers. ## Common workflows **Reviewing AI visibility performance** 1. Navigate to the Pitch Workspace from the sidebar. 2. The page loads the report for your currently active pitch. 3. Scan the top-level metric cards for Share of Voice, Brand Mentions, Responses Analyzed, and Models Tested. 4. Review the Share of Voice chart, AI model performance, brand traits, top citation sources, and competitive landscape cards. 5. Scroll down to the Responses table to inspect the individual AI responses that make up the report. **Inspecting a specific AI response** 1. Scroll down to the **Responses** table. 2. Type a keyword into the **Search responses** field to filter the table. 3. Click a specific response row to open the Response Details drawer. 4. Review the full response text, the prompt used, and any citations or sources the AI model provided. 5. Use the up and down arrow keys to quickly flip through adjacent responses. **Sharing the report** 1. Click the **Copy link** button in the top right of the page header. 2. The link to the public version of this report is copied to your clipboard. 3. Paste and share the link with external stakeholders, who can view the report without needing an account. **Recover from no pitches** 1. A user navigating to the Pitch Workspace when their organization has zero pitches will be automatically redirected. 2. The page loads and detects the empty list. 3. It automatically forwards to the create pitch flow to start a new workspace. ## Empty, loading, and error states * **Empty**: If your organization has no pitches at all, navigating to this page will automatically redirect you to the pitch creation flow. If a pitch legitimately detected zero mentions for your brand and all competitors, a "Zero Mentions Notice" card explains this is a real finding, not an error. * **Loading**: While pitch data is loading, or while switching between pitches, a report-shaped placeholder skeleton appears, mimicking the layout of the header, metric cards, and charts. * **Processing**: If the pitch is still being analyzed by the AI models, a full-page "Building your report" screen appears. It will automatically update when the report is ready. * **Error**: If the pitch data fails to load, a "Couldn't load this report" screen appears with a **Try again** button. If the pitch failed during processing, a "Report processing failed" screen appears with a **Create another pitch** button. ## Linked from / links to **Linked from:** * Sidebar **Pitch Workspace** navigation item. * The pitch workspace dropdown/switcher in the sidebar. **Links to:** * The **Copy link** button copies a link to the public, shareable `/report/[pitchId]` version of this report. * Automatically redirects to the create pitch page if the organization has no pitches. ## Common support questions **Why don't I see any brand traits on my report?** The Positive and Negative brand traits radar charts are hidden entirely if there are zero mentions of any attributes for your brand and your competitors. If no traits were detected in the AI responses, the charts are removed to save space. **Why does my report show all zeros for mentions?** If your report shows 0% share of voice and 0 brand mentions, it means none of the brands tracked in this pitch (yours or competitors) were named in any of the AI responses. This is a real finding - often, AI models answer niche or educational prompts with general advice instead of naming specific brands. Try tracking prompts that explicitly ask for recommendations. **Why is my search not finding a response I know exists?** The Responses table loads 50 rows at a time via infinite scroll. The search bar only filters the responses that have already been loaded into your browser. You may need to scroll down to load more rows before your search term will match them. **Who can see the link I copied?** The link copied via the **Copy link** button is a public URL. Anyone who has the link can view the report without needing to log in or have an Athena account. **Can I change the order of the charts?** Yes, if you are logged in and viewing your own workspace, you can click and drag the metric cards and the larger report charts to reorder them to your liking. (Viewers of the public shared link cannot reorder cards). # Pitch Setup Source: https://docs.athenahq.ai/guides/pitch-workspace-setup Read-only overview of the active pitch's basic info, identifiers, competitors, and prompts configuration. > [card] [Open in AthenaHQ](https://app.athenahq.ai/pitch-workspace/setup) > > `app.athenahq.ai/pitch-workspace/setup` ## Purpose The Pitch Setup page provides a read-only overview of how your currently selected pitch is configured. It allows you to quickly verify the core details, tracked competitors, search identifiers, and prompts being used to analyze AI mentions for this specific pitch. This page serves as a convenient reference point to ensure your pitch is set up correctly before you review its analysis or reports, gathering all configuration settings into one consolidated view. ## What's on the page The page is divided into distinct, collapsible sections grouping your pitch settings: * **Basic Information**: A panel displaying the core details of your pitch. * **Company Name**: The primary brand or company being tracked. * **Company URL**: The website of the company, featuring a link icon to open it in a new tab. * **Description**: The summary or description provided for the company. * **Created**: The date the pitch was originally created. * **Status**: The current state of the pitch (e.g., Draft, Processing). * **Identifiers**: A panel showing the exact names and keywords used to detect the company and its competitors in AI responses. Identifiers are displayed as distinct badges grouped under the company name and each competitor's name. * **Competitors**: A panel listing all competitors tracked within this pitch, showing their configured name and an external link to their website. * **Prompts**: A panel listing the specific AI queries configured to analyze mentions for this pitch. Each prompt includes a badge indicating its category (e.g., Discovery or High Intent). ## What you can do here * **Expand or collapse sections**: Click the section headers (Basic Information, Identifiers, Competitors, Prompts) or the arrow icon next to them to show or hide their contents. * **Visit external websites**: Click the external link icon next to the Company URL or any Competitor URL to open that website in a new browser tab. ## Data shown The page displays the configuration details of the currently active pitch selected in your Pitch Workspace. This data refreshes automatically every 30 seconds to reflect any background updates. ## Common workflows 1. **Verify your pitch configuration**: * Navigate to the Pitch Workspace and ensure the correct pitch is active. * Open the Pitch Setup page. * Expand the **Basic Information**, **Competitors**, and **Prompts** sections to review your setup. 2. **Confirm detection keywords (Identifiers)**: * Expand the **Identifiers** section. * Review the badges listed under your company and each competitor to ensure all relevant brand names and aliases are being tracked. 3. **Check competitor websites**: * Expand the **Competitors** section. * Click the link under a competitor's name to open their website and verify the URL is correct. ## Empty, loading, and error states * **Loading**: The page will appear completely blank for a moment while the pitch data initially loads. * **No pitch selected**: If there is no active pitch selected in the workspace, the entire page displays a centered "No pitch selected" message. * **Empty sections**: If a specific configuration is missing, the section will display a fallback message instead of a list: * "No identifiers" (under a company or competitor name) * "No competitors configured yet" * "No prompts configured yet" ## Linked from / links to * **Linked from**: This page is accessed via the Pitch Workspace navigation menu. * **Links to**: Clicking on company or competitor URLs opens those external websites in a new browser tab. ## Common support questions * **Why can't I edit my pitch settings on this page?** This page is designed as a read-only summary of your current configuration. Edits to the pitch, competitors, or prompts must be made through the pitch creation or editing flows elsewhere in the workspace. * **I just updated my pitch, why aren't the changes showing up here?** The Setup page automatically refreshes its data every 30 seconds. If you just made a change in another tab or window, it may take up to 30 seconds to appear here. * **Why is my prompt badge gray?** Prompts categorized as "Discovery" are highlighted in purple, and "High Intent" prompts are highlighted in indigo. Any other custom prompt types will appear with a neutral gray badge. # Pitch Workspace Usage Source: https://docs.athenahq.ai/guides/pitch-workspace-usage Shows an agency org's Pitch Reports usage (used/remaining or unlimited) and a summary of pitch report limits. > [card] [Open in AthenaHQ](https://app.athenahq.ai/pitch-workspace/usage) > > `app.athenahq.ai/pitch-workspace/usage` ## Purpose The Pitch Workspace Usage page provides agency users with a clear summary of their Pitch Reports consumption. Because Pitch Reports are a premium, often metered feature for agencies, this page helps users track how many reports they have generated and how many remain on their current subscription plan. It sits alongside the main Pitch Workspace and Content sections, serving as an administrative overview so account managers know when they are nearing their quota limit and can plan accordingly. ## What's on the page ### Pitch usage details card The main, wider card on the page shows the organization's current pitch report consumption. * **Pitch Reports Label:** A simple header identifying the usage metric. * **Usage Progress Bar:** A horizontal bar illustrating how much of the quota has been consumed. The bar changes color to warn users as they use up their quota: * Blue/Indigo for normal usage (under 33%). * Purple for medium usage (33% to 65%). * Orange for high usage (66% and above). * **Metered Plan Text:** If the organization is on a metered plan, the card displays exactly how many pitches are **"\[X] used"** and how many are **"\[X] left"**. * **Unlimited Plan Text:** If the organization's plan has no strict cap on pitches, the progress bar is hidden. The card instead displays a large **"Unlimited"** header, a subtitle showing **"\[X] pitches created"** (or "1 pitch created"), and a label stating **"No limits"**. ### About Pitch Reports card A smaller informational card on the right side of the page outlining the system limits applied to every individual pitch report. * **"About Pitch Reports"**: Card title. * **"• Analyze up to 10 competitors per pitch"**: Reminds users of the maximum number of competitors they can include when generating a single report. * **"• Include up to 10 custom prompts"**: Reminds users of the limit on custom AI prompts per pitch. ## What you can do here This is a read-only dashboard. Users visit this page exclusively to check their remaining pitch quota or verify the limits of the feature. To generate new pitches or view existing ones, users navigate back to the main Pitch Workspace. ## Data shown * **Pitch Quota:** The total allowance of Pitch Reports granted by the organization's current subscription plan. * **Pitch Count / Usage:** The actual number of Pitch Reports that have been generated across the user's entire organization. This includes all pitches created by any member of the team. ## Common workflows ### Check remaining pitch quota 1. From the Pitch Workspace navigation rail, the user clicks the **Usage** tab. 2. The user reviews the main card to see if their account says **Unlimited** or displays a progress bar. 3. If metered, they can read the exact number of pitches **used** and the number they have **left** before they need to upgrade or wait for a quota reset. ## Empty, loading, and error states * **Loading:** While the system checks the organization's subscription limits and counts the pitches, the usage numbers and progress bar are replaced by gray pulsing skeleton placeholders. * **Error:** If the system fails to verify the usage limits due to a temporary billing service outage, the card displays warning text: **"Couldn't verify pitch quota - please refresh."** * **No Access:** If the user manages to navigate here but their organization does not actually have the Pitch Workspace feature enabled, the card displays: **"Pitch workspace access is not available for your organization."** ## Linked from / links to * **Linked from:** This page is accessed via the "Usage" navigation link within the Pitch Workspace rail/header. * **Links to:** This page has no outbound links. Users must use the sidebar or top navigation to return to their reports. ## Common support questions **Why is the progress bar orange?** The progress bar automatically changes colors to give you a quick visual indicator of your usage. It turns purple when you've used a third of your quota, and orange once you've used 66% or more of your available Pitch Reports. **Can I add 15 competitors to a single pitch?** No. As noted on the "About Pitch Reports" card on this page, the system enforces a strict limit of 10 competitors per pitch report to ensure the AI analysis remains focused and reliable. **Why does my usage say "Unlimited" instead of showing how many I have left?** Your organization is on a subscription plan that includes unlimited Pitch Reports. Because there is no quota to deduct from, we just show you the total number of pitches your team has created so far. **How do I get more pitch quota?** If you have run out of pitches, an organization administrator will need to reach out to their account manager or use the billing settings to upgrade the plan or purchase an add-on. # Prompts Source: https://docs.athenahq.ai/guides/prompts Manage tracked prompts, topics, personas, locations, and discover new prompt opportunities for the active website > [card] [Open in AthenaHQ](https://app.athenahq.ai/prompts) > > `app.athenahq.ai/prompts` ## Purpose The Prompts page is the central hub for managing and analyzing the questions and searches you are tracking across AI models. This page allows you to organize your tracked prompts into topics, assign specific geographic locations or target audience personas, and monitor how often your brand is mentioned or cited in AI responses for those specific queries. Customers use this page to monitor performance over time, edit prompt configurations, discover new prompt opportunities, and export data for external reporting. By grouping prompts into topics and applying specific filters, you can easily drill down into exactly how your brand is performing for specific segments of your market. ## What's on the page **Page Header & Navigation** * **Page Title:** Displays "Prompts" alongside a small info icon (ⓘ) that launches a guided product tour. * **Navigation Tabs:** Switch between "Manage" (the main prompts table), "Personas" (audience segments), "Locations" (geographic targeting), and "Discover" (for finding new prompt opportunities). Note: A small lock icon appears next to tabs if they are not included in your current subscription plan. **Filter Bar** * **Filters:** Contextual drop-downs to filter the table by Date range, Models (e.g., ChatGPT, Claude, Gemini, Perplexity), Schedule, Competitors, Personas, Locations, Countries, Prompt Tags, Prompt status (active/paused), and various performance thresholds. * **Action Buttons:** Includes an "Add More" menu (to add prompts, topics, locations, or tags), a "Columns" menu to show/hide specific data points, and an "Export as CSV" button. **Prompts Table (Manage Tab)** The main spreadsheet-style table lists all your tracked prompts, automatically grouped into collapsible rows by their assigned Topic. The table includes the following columns: * **Select:** A checkbox column used to select individual prompts or entire topics for bulk actions. * **Base Prompt:** The actual text of the query being tracked. Clicking this opens a detailed analytics panel for the specific prompt. Includes a small "View responses" button to drill down further. * **Countries:** Displays flags for the countries assigned to the prompt. Clicking this area allows you to quickly edit the country settings. * **Mention Gap:** The difference between your brand's mention rate and your competitor's. 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:** 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:** The estimated brand appearances in AI. Tooltip: *"Estimated number of times your brand appears in AI responses (Monthly Queries × Mention %)"* * **Tags:** Displays badges indicating the prompt's type (e.g., Branded / Non-branded) and any custom tags. Tooltip: *"Custom tags assigned to this prompt"* * **Variations:** Tooltip: *"Number of query variations tracked for this prompt"* * **Actions:** A three-dot menu (⋯) for individual row actions. **Bottom Command Bars** * **Uncategorized Prompts Bar:** If you have active prompts without an assigned topic, a fixed bar appears at the bottom of the screen showing the count of uncategorized prompts, alongside options to view them or automatically categorize them. * **Bulk Selection Bar:** When you check the box next to one or more prompts, a command bar pops up at the bottom of the screen offering bulk actions like Stream Data, Write Content, Pause, Delete, and a More Actions menu. **Drilldown Panels (Drawers & Dialogs)** * **Prompt Analytics Panel:** Clicking on a prompt's text opens a side panel with two tabs: * **Overview:** Displays metric cards and a "Prompt Variations" table outlining the base prompt versus any tracked variations. * **Search queries:** Shows a list of actual web and map searches captured behind the AI responses, expanding to show specific responses when clicked. * **Edit Prompt Panel:** Opened via the table row actions. Allows you to edit the prompt text, assign tags, set geographic rules (Locations/Countries), change the assigned topic, and pause/unpause the prompt. * **Response Details:** When exploring the "Search queries" tab in the analytics panel, clicking "View response" opens a nested drawer showing the full text, model, and citation data for that specific AI response. ## What you can do here **Top-level Actions** * **Switch Tabs:** Click "Manage", "Personas", "Locations", or "Discover" to navigate between different configuration areas. * **Add More:** Click the "Add More" button to open a menu where you can click "Add Prompts" (manual or CSV import), "Add Topic", "Add Location", or "Add Tag". * **Show empty topics:** Open the **Prompt Status** dropdown and turn on **Show empty topics** below the status options to reveal topics with no prompts. It is off by default and is preserved in shared links and saved views. Clear text, tag, or segment filters to manage the complete topic list. This only changes the view; all underlying data is retained. * **Toggle Columns:** Click "Columns" to show or hide specific data columns in the table. * **Export as CSV:** Click to download the currently filtered view of your prompts as a CSV file. **Individual Row Actions (⋯ Menu)** * **Edit:** Opens the "Edit Prompt" panel to modify the prompt's configuration. * **Refresh Volume:** Triggers a background recalculation of the prompt's monthly search volume and estimated value. * **Pause / Unpause:** Temporarily stops or resumes tracking for the specific prompt. * **Delete:** Opens a confirmation dialog to permanently remove the prompt. **Topic Group Actions** * **Reorder Prompts:** Drag and drop prompts using the handle (six dots) to reorder them within a topic, or drag them into a different topic group entirely. * **Edit Topic:** Click the ⋯ menu on a Topic group row to rename the topic or update its description. * **Delete Topic:** Click the ⋯ menu on a Topic group row to delete the topic. Choose **Delete Prompts Only** to keep the empty topic, or **Delete Topic & Prompts** to remove both. Empty topics are hidden by default; enable **Show empty topics** to find a retained topic. **Bulk Actions (Selection Bar)** Check the boxes next to multiple prompts to reveal the bulk action bar: * **Stream Data:** Immediately re-runs the selected prompts across AI models. * **Write Content:** Sends the selected prompts (up to 100) into the content creation workflow. * **Pause / Unpause:** Suspends or resumes tracking for all selected prompts. * **More Actions (M):** Opens a menu with additional bulk commands: * **Tags:** Apply custom tags to all selected prompts. * **Locations / Countries:** Bulk-edit geographic targeting. * **Assign topic:** Move all selected prompts into a specific topic. * **Refresh volume:** Recalculate search volume for the selection. * **View in Olympus / Brand Visibility:** Navigates to the main analytics dashboard, automatically filtered to only show data for the selected prompts. * **Create view:** Save the current selection as a named "Saved View" for easy access later. * **Export as CSV:** Download only the selected prompts. * **Delete:** Permanently delete the selected prompts. * **Reset (Esc):** Clears your current selection. **Categorize Uncategorized Prompts** * **View prompts:** Click to see a list of all active prompts currently lacking a topic. * **Categorize:** Click to have the AI automatically evaluate your uncategorized prompts and sort them into existing topics (or create new ones). * **Dismiss (Esc):** Hide the categorization bar until new uncategorized prompts are added. ### Inspect and export captured search queries Open a prompt's analytics panel and select **Search queries** to inspect the web and map searches captured behind its AI responses. The summary shows **Unique searches** and **Responses checked** for the selected dates, models, and schedule. Identical searches count once per response, and some responses do not include captured searches. Expand a search to inspect the responses that used it, then choose **View response** for the full answer. Use **Export CSV > Summary CSV** for the aggregated searches, or **All searches CSV** for the detailed records. These are searches the model performed while answering; they are distinct from the prompts you asked Athena to track. ## Data shown The data on this page reflects the performance of the exact questions and searches you have configured the platform to run against AI engines. The percentages (Mention %, Citation %, etc.) represent how often your brand or your competitors appeared in the AI responses generated during the selected date range. Search volumes and estimated impressions are calculated by combining third-party keyword data with your actual AI mention rates. ## Common workflows **Organizing newly added prompts:** 1. Look for the "uncategorized prompts" bar at the bottom of the screen. 2. Click "Categorize" to have the system automatically group them into relevant topics. 3. Review the newly assigned topics in the table. If a prompt is in the wrong place, click the drag handle on the row and drop it into the correct topic group. **Bulk updating geographic targeting:** 1. Use the filter bar to isolate a specific set of prompts (for example, by Topic or Tag). 2. Check the "Select all" box at the top of the table. 3. In the bulk action bar that appears, click the "More actions" menu (M) and select "Countries". 4. Choose the new countries you want to track, select a primary country, and click "Save changes". **Investigating dropped performance:** 1. Set your date range to include a comparison period. 2. Look at the "Mention Gap" or "Mention %" columns for orange badges indicating a drop. 3. Click the specific prompt text to open the analytics panel. 4. Review **Search queries** to inspect searches captured behind the answers, then click **View response** to read an answer in full. ## Empty, loading, and error states * **Empty:** If you have no data yet, metric columns will display "No data yet". Empty topics are hidden by default. Turn on **Show empty topics** to display them as placeholder rows containing "(0)" when no text, tag, or segment filters are active. Topics containing only paused prompts remain hidden under **Active**. An active prompt with zero responses or missing metrics still appears unless another selected filter excludes it. * **Loading:** While data is being retrieved, you will see skeleton shimmers across the table cells. Drawers and panels use spinning loading circles ("AnimatedLoader") while fetching details. * **Errors:** If a panel fails to load data (such as prompt details or search queries), it will display an inline message stating the data could not be loaded, alongside a "Try again" button. If an action fails (like attempting to delete or edit a prompt), a red error toast will appear at the top of the screen. ## Linked from / links to * **Linked from:** The main app navigation sidebar, the onboarding flow, and "View prompt" links inside specific chat or response views. * **Links to:** The Responses page (via "View responses" buttons), the Olympus dashboard (via "View in Olympus"), and the Discover, Personas, and Locations tabs. ## Common support questions **Why can't I edit the text of my prompt?** Once a prompt has been run and has recorded responses, its core text becomes read-only to preserve historical data integrity. You can still edit its topic, volume, and geographic settings, or you can pause it and create a new prompt with the desired text. **Why does the Mention Change filter keep resetting?** The "Mention change" filter (which lets you filter for prompts that gained or lost mentions) relies on historical comparison. It will automatically reset to "all" if you disable the comparison date range in your date picker. **Why are there locks on the Personas and Discover tabs?** These tabs represent advanced features that may not be included in your current subscription plan. Clicking a locked tab will show you an overview of the feature and provide options to upgrade. **Why can't I use the "Refresh volume" bulk action?** The ability to bulk-refresh keyword search volume in the background is reserved for Enterprise subscription plans. If you do not have access, you can still refresh volume individually via a prompt's row menu. # Discovery Run Detail (Discover) Source: https://docs.athenahq.ai/guides/prompts-discover-id Review, filter, edit, track, or remove AI-suggested prompt candidates produced by a single prompt-discovery run. > [card] [Open in AthenaHQ](https://app.athenahq.ai/prompts?tab=discover) > > `app.athenahq.ai/prompts?tab=discover` ## Purpose This page displays the detailed results of a single AI prompt discovery run. When you use the Discover feature to find new search queries your audience is asking, the suggestions are collected here for your review. From this page, you can analyze the suggested prompts, filter them by search intent or funnel stage, organize them into topics, and select which ones you want to actively monitor in your workspace. You can also dismiss irrelevant suggestions to keep your lists clean. ## What's on the page **Page header** Features a back button pointing to the main Discover tab and the name of the run. You can click the pencil icon next to the run name to rename it inline. **Discovery context** Shows the target country and language used for this run, along with a list of the sources used to collect evidence (e.g., Website analysis). It displays the status for each source (such as "completed", "empty", or "failed"), how many evidence records were found, and why the source was added (e.g., "Added to ground your custom instructions"). **Leg progress panel** If the discovery run is still actively collecting and analyzing data, a "Discovering prompts..." progress panel appears. It displays horizontal progress bars for each source being analyzed, giving you real-time status updates. **Candidates table toolbar** Allows you to search and narrow down the list of suggested prompts. * **Filters**: A dropdown menu to filter by "Top volume", Source, Funnel, Intent, or Type. * **Signal chips**: Toggle buttons (e.g., "Competitor Gap", "Social Signal") that appear if any suggested prompts carry these specific market signals. * **Reset**: Clears all active filters and search terms. * **Export**: A download icon button that exports the currently filtered list to a CSV file. * **Search box**: Quickly find specific text within the prompt or its assigned topic. **Discovery Candidates Table** Groups the suggested prompts by topic. Each topic group can be expanded or collapsed by clicking its row. If you hover over a topic name, a pencil icon appears allowing you to rename it. * **Checkbox (select)**: Used to select individual rows or entire topic groups for bulk actions. Supports shift-clicking to select a range. * **Prompt**: The suggested prompt text. A signal badge may appear next to it. Hovering over an info icon here reveals "Why this prompt was suggested". * **Source**: Displays the origin of the suggestion. The tooltip explains: * "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. The tooltip explains: * "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**: The user's search behavior. The tooltip explains: * "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. The tooltip explains: * "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" * **Value**: "Estimated keyword value (CPC)" **Already tracked section** Located at the bottom of the table, this expandable section holds prompts that closely match queries you are already monitoring. Current discovery compares question meaning and supporting evidence with your existing tracked prompts. Do not interpret this section as a fixed similarity-percentage rule. **Removed section** An expandable section for prompts you have dismissed from this run. * *Tooltip*: "Suggestions you removed from this run. They stay out of the suggestion list; restore one to review it again." **Selection command bar** A floating bar that appears at the bottom of the screen when one or more rows are selected. It displays the total selection count and offers bulk actions. ## What you can do here * **Edit run name**: Click the pencil icon next to the run title in the page header. Press `Enter` or click away to save. * **Rename topic**: Hover over a topic row and click the pencil icon. If you enter a name that matches an existing topic, you will be prompted to merge the two groups. * **Select rows for bulk action**: Check the boxes next to individual prompts or click the checkbox on a topic row to select all prompts within it. * **Start tracking**: With rows selected, click **Start tracking** in the command bar (or press `T` on your keyboard). This opens a dialog confirming how many new prompts will be monitored, skipping any that are already tracked. It also provides a preview of your estimated monthly credit cost. Clicking "Start tracking" in the dialog finalizes the action. * **Remove**: With rows selected, click **Remove** in the command bar (or press `Backspace`). This moves the selected prompts into the "Removed" section. * **Restore**: Expand the "Removed" section and click the **Restore** button next to a prompt to bring it back to the active list. * **Export as CSV**: Click the download icon near the search bar to export your current filtered view. * **Resize columns**: Drag the invisible handle on the right edge of any column header to adjust its width. * **Sort**: Click any column header (like Volume or Value) to sort the table. * **Expand/Collapse all topics**: Click the "Prompt" column header to toggle all topic accordions open or closed at once. ## Data shown This page displays data generated specifically for your website during a targeted AI prompt discovery run. The search volume and CPC values are market estimates for those specific search queries. The credit estimates in the "Start tracking" dialog are calculated using your workspace's configured models, locations, and schedule frequency. ## Common workflows **Reviewing and tracking new prompts** 1. Open a completed discovery run. 2. Browse the suggested prompts, expanding topics that interest you. 3. Check the boxes next to the highest-value or highest-volume prompts. 4. Click **Start tracking** in the floating command bar. 5. Review the credit estimate in the dialog and confirm to add them to your active monitoring list. **Cleaning up irrelevant suggestions** 1. Find prompts or entire topic groups that don't fit your strategy. 2. Select their checkboxes. 3. Click **Remove** in the floating command bar to dismiss them. 4. (Optional) If you made a mistake, open the "Removed" section at the bottom and click **Restore** on the prompt you want back. ## Empty, loading, and error states * **Loading**: While the run's data is being fetched, a full-page animated loader is displayed. * **Empty state (No data)**: If the run finishes but finds nothing, you will see a file icon and the message "No prompts discovered". If the run encountered an issue, it adds: "This run could not finish. Run discovery again later." * **Partial progress**: If the run is still executing, a progress panel shows the percentage completed for each source. A shimmering animation indicates active processing. * **Error**: If the run ID doesn't exist or there was a network failure, the page displays a "Run not found" message. * **Missing Estimates**: If search volume or value cannot be fetched for certain rows, they display "No data" rather than \$0, and a warning banner appears stating, "Volume and value estimates are temporarily unavailable for some prompts." ## Linked from / links to * **Linked from**: The main **Discover** tab in the Prompts page. * **Links to**: The tracking success dialog provides a "View in Manage" button that takes you to the main **Prompts** dashboard to view your actively tracked queries. ## Common support questions **Why are some suggestions hidden under "Already tracked"?** These suggestions are already covered by prompts you monitor. Current discovery uses meaning, intent, and supporting evidence to decide coverage rather than one fixed similarity percentage. A question about discovering a suitable product and a question evaluating a named product can serve different needs. **Why can't I click Start Tracking or Remove?** To track new prompts, remove suggestions, or rename topics/runs, you must have `Write` permissions for Prompts. If you only have `View` permissions, these actions will be disabled, and hovering over "Start tracking" will explain that you need write access. **Why does a topic rename ask me to merge?** If you rename a topic to a name that already exists within the same run, the system will ask if you want to merge them. Confirming will combine all prompts from both groups under the single topic name. **Why are some rows displaying "No data" for Volume or Value?** Search volume and keyword value are provided by external data estimates. If those estimates are temporarily unavailable or don't have sufficient historical data for a specific long-tail query, they fall back to "No data" instead of inaccurately showing zero. # Public AI Search Report Source: https://docs.athenahq.ai/guides/report-pitchId Publicly-shareable, read-only AI search visibility report for a pitch (brand mentions, share of voice, competitor analysis, and sampled AI responses) that anyone with the link can view. > [card] [Open in AthenaHQ](https://app.athenahq.ai/pitch-workspace) > > `app.athenahq.ai/pitch-workspace` ## Purpose The Public AI Search Report is a read-only, shareable dashboard that gives anyone a high-level view of a brand's AI search visibility. It allows customers to share key insights - such as share of voice, competitor analysis, and actual AI responses - with clients, executives, or team members without requiring them to log into Athena. This page solves the problem of distributing findings. When a pitch analysis completes, this URL serves as a clean, presentation-ready deliverable that anyone with the link can view. ## What's on the page **Page header** Shows the brand's logo and name, ensuring the viewer knows exactly which brand the report is tracking. Includes a "Copy link" button. **Report header** Displays the "AI search preview report" title, the audit date, and a "Powered by AthenaHQ" link. **Landing page CTA** If this report was generated via a public marketing tool, a banner appears reading "Track this brand across every AI surface." It invites viewers to "See pricing" or "Book a demo." **Zero mentions notice** If the report finds absolutely no mentions for the brand or its competitors across all responses, a notice explains that these zeros are an accurate finding, not an error - meaning models answered with general advice instead of recommending brands. **Metric cards** A row of four summary numbers at the top of the report: * **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** A donut chart and ranked legend comparing how often AI mentions the tracked brand versus each configured competitor. **AI model performance** A ranked bar list showing how frequently each specific AI model (e.g., ChatGPT, Claude, Gemini) mentions the brand. **Positive brand traits** A radar chart comparing the frequency of positive attributes mentioned in relation to the brand versus all competitors. (Hidden if there is no data to plot). **Negative brand traits** A radar chart comparing the frequency of negative attributes mentioned for the brand versus all competitors. (Hidden if there is no data to plot). **Top citation sources** A ranked list showing which domain URLs AI models cite most frequently when answering the tested prompts. **Competitive landscape** A ranked bar list displaying each brand's (including the tracked brand's) percentage share of all detected mentions. The tracked brand receives a "You" badge. **Responses table** A searchable list of every individual AI response collected during the analysis. * **Model**: The AI model that generated the response, alongside its product icon (e.g., ChatGPT, Claude, Perplexity). * **Mentioned**: Indicates if the tracked brand appeared in this specific response ("Yes" or "No"). If "No" but competitors were mentioned, the badge is highlighted in orange. * **Competitors Mentioned**: Stacked logos of any competitors named in the response. Hovering over a "+N" badge shows the rest if there are many. * **Prompt**: The specific prompt text sent to the AI model. * **Response**: A snippet of the raw AI response text. Search keywords are highlighted in yellow if a search is active. **Response Details drawer** Clicking any row in the Responses table opens this side panel, revealing the full context of that single AI response: * **Date**: When the response was generated. * **Model**: The AI model used. * **Prompt Type**: The category of the prompt (e.g., Branded, Non-Branded). * **Mentioned**: "Yes" or "No" for the tracked brand. * **Market Position**: The numeric rank of the brand compared to competitors in the text. * **Competitors Mentioned**: A list of competitor chips. * **Base Prompt**: The original prompt template. * **Variation**: The exact variation of the prompt submitted to the model. * **Response text**: The full, unabridged answer from the AI, with brands and competitors highlighted. * **Sources**: A list of citation chips (e.g., "\[1] example.com") linking to referenced websites. * **Organic Results / People Also Ask / Related Searches**: These expandable sections appear *only* if the response came from Google AI Overviews and Google displayed those features alongside the answer. ## What you can do here * **Copy link**: Click the "Copy link" button in the top right to save the report's URL to your clipboard for easy sharing. * **Learn about metrics**: Click the info icon on the Share of Voice or Brand Mentions cards to open a dialog explaining how the metric is calculated. Hover over the info icons on other cards for brief definitions. * **Search responses**: Type into the "Search responses" box above the table to filter the list for specific keywords in the prompt or response text. * **View response details**: Click any row in the Responses table to open the Response Details drawer for a deep dive into that answer. * **Navigate responses**: While the Response Details drawer is open, use the up and down arrow buttons in the top right (or your keyboard's up/down arrows) to flip to the previous or next response without closing the drawer. * **Visit a citation**: Inside the Response Details drawer, click any numbered source chip (e.g., "\[1] domain.com") to open that webpage in a new tab. * **Load more responses**: Scroll to the bottom of the Responses table; the next page of responses will load automatically. * **Try again**: If the report fails to load, click "Try again" to re-fetch the data. * **Create another pitch**: If the report processing failed entirely, click "Create another pitch" to return to the creation flow (if you are an authenticated user). ## Data shown The information on this page is generated from a single, completed pitch analysis. It represents the competitor list, the AI models tested, the prompts asked, and the actual AI answers received at the exact time the pitch was run. ## Common workflows **Share the report** 1. Open the public report URL. 2. Click "Copy link" in the top-right corner. 3. Paste the link into an email, Slack, or presentation to share it. **Investigate a specific AI response** 1. Scroll down to the Responses table. 2. Type a topic or competitor name into the "Search responses" box to filter the list. 3. Click a relevant row to open the Response Details drawer. 4. Read the full text, noting highlighted brand mentions and checking the cited Sources at the bottom. **Understand brand's AI visibility at a glance** 1. View the four metric cards (Share of voice, Brand mentions, Responses analyzed, Models tested). 2. Click the info icon on Share of voice or Brand mentions to see the calculation methodology. 3. Review the Share of Voice donut chart and Competitive landscape ranking for deeper context. ## Empty, loading, and error states * **Loading**: While the pitch is still running, viewers see a "Building your report" screen with a spinner. For live data, you may briefly see gray placeholder skeletons while charts and logos load. * **Empty**: If no positive or negative brand traits were detected, those radar charts are hidden. If the entire analysis found zero mentions for the brand and all competitors, a "Zero mentions" notice appears explaining the result. If a search matches no responses, the table reads "No responses found." * **Error**: If the pitch analysis failed entirely, a "Report processing failed" screen appears. If data cannot be retrieved, a "Couldn't load this report" screen shows a "Try again" button. ## Linked from / links to * **Linked from**: This page is usually accessed via a direct link shared by an Athena user, or after completing a scan on the public landing page. * **Links to**: Links to external citation websites. If the landing page CTA is visible, it links to the AthenaHQ pricing page and demo booking calendar. ## Common support questions **Why are all the numbers 0%?** If the AI models responded to your prompts with general advice, educational info, or completely unrelated products, neither your brand nor your tracked competitors were mentioned. The report displays this accurately with a "Zero mentions" notice. **Can I reorder the cards or edit the competitors here?** No. This is a read-only, public view designed for sharing. Changes to the layout or competitor list can only be made by authenticated users inside the main Athena app. **Why do I see "Organic Results" on some responses but not others?** The "Organic Results", "People Also Ask", and "Related Searches" sections only exist for responses generated by Google AI Overviews. Other models, like ChatGPT or Claude, do not output these features. **Why doesn't the search box find a word I know is in the table?** The "Search responses" box looks through the data currently loaded into the table. Because responses load in batches as you scroll down, you may need to scroll further to load more rows before searching if you have hundreds of responses. # Report Builder (Edit Report) Source: https://docs.athenahq.ai/guides/reports-id Lets a user edit a scheduled report's charts, settings, recipients, and send it immediately or export it as a PDF. ## Purpose The Report Builder page allows customers to view and edit the contents, scheduling, and delivery configurations of an existing scheduled report. It serves as a visual layout editor where users can preview exactly what their report will look like before it goes out. From this page, users can customize which charts are included, apply filters to narrow down the data (like specific AI models or locations), modify the delivery frequency and recipients, send a test email, export a PDF, or trigger an immediate delivery to all scheduled recipients. ## What's on the page * **Page header:** Displays the report's name (e.g., "Edit Weekly brand visibility"). It contains primary actions for the report, including **Export PDF**, **Settings**, and **Send now**. If a background save fails, a **Retry save** button will also appear here. * **Chart types (Left palette):** A sidebar listing all available chart types for the report (e.g., Share of Voice, Mention Rate, Citation Rate, Position over Time). Each has a toggle switch to add or remove it from the report. * **Miscellaneous (Left palette):** For website-level reports, this section includes a **Competitor lines** toggle that turns the competitor-average overlay line on or off for supported charts. * **Report filter bar:** A horizontal bar sitting above the report canvas used to apply shared filters to every chart in the report. It includes a **Saved Views** dropdown to instantly apply the filters from a saved dashboard view. * **Report canvas:** A drag-and-drop grid displaying live previews of the selected charts. The charts preview the data based on the report's configured frequency (e.g., showing the last 7 days of data if it is a weekly report). * **Report Settings modal:** Accessed via the **Settings** button. It is a two-step modal with **Build** (a condensed version of the chart editor) and **Send** tabs. The Send tab allows users to edit the report's name, frequency, delivery time, time zone, and recipients. The Send step includes a delivery preview and **Test recipients**. **Export PDF** is available in the settings header from either step. * **Send now confirmation dialog:** Appears when clicking **Send now**, confirming the exact number and breakdown of active recipients (emails, Slack channels, direct messages) that will receive the report immediately. ### Report filter bar * **Websites:** (Group reports only) Determines which group member websites' data is included. * **Topics & Prompts:** Restricts chart data to selected topics or prompts. * **Models:** Restricts chart data to selected AI models. * **Prompt Status:** Determines whether the charts look at Active, Paused, or Both types of prompts. * **Prompt Variation:** Filters by original prompt or variations. * **Competitors:** (Website reports only) Selects which competitors are included and compared in the charts. * **Personas:** Restricts chart data to specific target personas. * **Locations:** Restricts chart data to specific geographic locations. * **Prompt Tags:** Restricts chart data to prompts carrying specific tags (supports "Is any of", "Is not any of", "Has all of"). * **Target Identifiers:** Restricts chart data by target identifier (supports "Is any of", "Is not any of"). ## What you can do here * **Toggle charts on or off:** In the left sidebar, flip the switch next to any chart name to add it to or remove it from the report canvas. * **Reorder charts:** On the main canvas, click and drag any chart card to change the order in which it will appear in the final email and PDF. * **Filter report data:** Use the filter bar above the canvas to apply constraints (like specific models or locations). Click **Add filter** to choose a new constraint, or **Clear All** to remove them. You can also select a saved view from the **Saved Views** dropdown. * **Toggle Competitor lines:** (Website reports only) Toggle this switch in the left sidebar to overlay competitor averages on supported charts. * **Export PDF:** Click **Export PDF** in the top right header to download a generated PDF of the current report configuration. * **Open Settings (Edit Schedule & Recipients):** Click **Settings** to open the modal. Switch to the **Send** step to: * Edit the report name. * Change the **Frequency** (Weekly, Monthly, Quarterly), day, delivery time, and time zone. * Change the **Delivery method** (Email, Slack direct message, Slack channel) and search for a person/channel to add them as a recipient. * Remove a recipient by clicking the **X** on their name tag. * Click the **Connect** button if Slack is not integrated yet (redirects to the integrations settings). * **Send a test email:** In the Settings modal's Send step, add up to 10 email addresses under **Test recipients**, then click **Send test email**. Only organization admins can send to other people; other users can send to their own email address. This delivers a sample report with a PDF attachment without altering the scheduled recipient list. * **Send now:** Click **Send now** in the main page header to immediately deliver the report to all configured active recipients. A confirmation dialog will appear; click **Send now** to confirm. * **Retry save:** If a chart or filter edit fails to save in the background, click **Retry save** in the page header or on the red error banner to re-attempt the save. ## Data shown The data displayed in the chart previews is generated from the target website or group's tracked prompts, competitor configurations, and AI model responses. The date range reflected in the preview matches the report's configured cadence (e.g., if set to "Weekly", the charts show the most recent 7-day period and its previous 7-day comparison window). ## Common workflows 1. **Edit report charts and filters:** 1. Open **More actions > Manage reports** on Olympus (or the group dashboard menu for a group report), then open the report you want to edit. 2. Toggle desired chart types on or off in the left chart palette. 3. Adjust shared filters in the top filter bar, or apply a pre-configured saved view from the dropdown. 4. Drag and drop chart cards on the canvas to place them in the perfect order. 5. Changes save automatically; watch the page header to ensure the save state completes. 2. **Update delivery schedule and recipients:** 1. Click the **Settings** button in the top right of the page header. 2. Click the **Send** step indicator at the bottom of the modal. 3. Edit the report name, delivery cadence, time, and time zone as needed. 4. Add new recipients via the Delivery method dropdown, or remove existing ones by clicking the X on their tag. 5. Click **Schedule** to close the modal. 3. **Send report immediately:** 1. Click **Send now** in the page header. 2. Review the recipient count and channel breakdown in the confirmation dialog. 3. Click **Send now** to confirm delivery. 4. Look for the success or partial-failure toast in the bottom right corner. ## Empty, loading, and error states * **Loading:** Skeleton placeholders appear in the header, and two large skeleton blocks mask the canvas while the report loads. * **Empty (No charts):** If a user removes all charts from the report, the canvas displays a "No charts yet" graphic with instructions to switch on chart types in the sidebar. * **Empty (Group report):** If a group report targets a group that has no valid tracked websites, a "Group has no reportable websites" message replaces the canvas. * **Error (Missing Report):** If the report is deleted or the user lacks access, a brief "Report unavailable." message appears before redirecting the user to the Olympus dashboard. * **Error (Failed Save):** If a background save fails, a red banner stating "Report content did not save." appears at the bottom of the canvas with a **Retry** button. A "Retry save" button also appears in the page header, alongside a red "Failed to save report content" toast notification. ## Linked from / links to * **Linked from:** **Manage reports** on Olympus or a group dashboard. * **Links to:** * The Olympus dashboard (as a fallback if the report doesn't exist). * The Settings Integrations page (`/settings/integrations?provider=slack-reports`) if the user clicks **Connect** to set up Slack delivery. ## Common support questions **Why is the "Send now" button disabled?** The "Send now" button will be disabled if there are zero active eligible recipients configured on the report, or if you recently made chart changes that haven't finished saving yet. Hovering over the button will display a tooltip explaining exactly which condition is blocking it. **Why is the "Export PDF" button disabled?** Exporting a PDF requires at least one selected chart and, for group reports, at least one reportable website. It also requires any recent edits to finish saving in the background. If the save state is "saving" or "error", the export button will remain grayed out. **Why can't I edit the shared filter bar?** If the charts in your report have individual, differing filters applied to them, the shared filter bar is disabled to prevent accidentally overwriting those specific settings. The UI will display a message reading: "Charts have individual saved filters. Shared filter editing is disabled to avoid overwriting them." **Why can't I add a specific teammate as a recipient?** Unless you are an organization administrator, you can only manage your own email subscription for a report. Organization admins have the required permissions to add, remove, or toggle other recipients (including Slack channels and direct messages). **Why don't I see "Competitor lines" or Brand Traits charts on my report?** Group-level reports only support a specific subset of charts (Share of Voice, Mention Rate, Citation Rate, Position over Time, Dollar Value Captured). The Competitor lines toggle and specific charts like Positive/Negative Brand Traits and Attributed Citations Growth are exclusive to single-website reports. # Responses Source: https://docs.athenahq.ai/guides/responses Lets a customer browse, search, filter, sort, export, and drill into every individual AI-model response collected for their tracked prompts. > [card] [Open in AthenaHQ](https://app.athenahq.ai/responses) > > `app.athenahq.ai/responses` ## Purpose The Responses page is the raw data engine of Athena. It lets customers browse, search, filter, sort, export, and drill into every individual AI-model response collected for their tracked prompts. While other pages (like Olympus or Prompts) aggregate data to show high-level trends and metrics, the Responses page allows users to see exactly what the AI models (like ChatGPT, Claude, and Gemini) said. This is crucial for deeply investigating why a competitor was mentioned, reviewing the exact sentiment of an answer, or seeing exactly which sources an AI model cited to generate its response. ## What's on the page **Page header** Shows the "Responses" title and optionally a back arrow if the customer navigated here from a specific drilldown (like an Ads or Prompts page analysis). **Filter bar** A contextual row of filter chips. The "Date Range" and "Response" search filters are always shown by default. Customers can use the "Add filter" button to attach more conditions, or use the saved-views selector to load a previously saved combination of filters. **Responses table toolbar** Located on the right side of the filter bar, this toolbar contains a "Columns" button for configuring table visibility and an "Export as CSV" button to download the data. **Responses table** A large, customizable spreadsheet-style table displaying individual AI responses. The table features infinite scrolling (loading more records as you scroll down) and highlights text that matches active search terms. The table includes the following columns (some are hidden by default and must be toggled via the "Columns" button): * **Date:** The exact date and time the response was collected. * **Model:** The AI model that generated the response (e.g., ChatGPT, Claude, Gemini, Perplexity). * **Mentioned:** Displays "Yes" or "No" indicating if the customer's tracked brand was mentioned. * **Competitors Mentioned:** Shows the logos of any tracked competitors mentioned in the response. * **Sources:** Displays "Yes" or "No" indicating if the AI response provided citable sources. * **Cited:** Displays "Yes" or "No" indicating if the response actively cited anything. * **Attributed Citation:** Displays "Yes" or "No" indicating if the response cited the customer's specifically tracked content. * **Market Position (Brand Rank):** The numeric rank position of the brand within the response. * **Sentiment:** The sentiment of the mention (Positive, Neutral, Negative, or Not analyzed). * **Prompt Type:** Categorizes the prompt as Branded or Non-branded. * **Prompt:** The actual text of the prompt that was asked. * **Prompt Variation:** Indicates whether this was a base prompt or a generated prompt expansion variation. * **Country & Location:** Geographic context for the response (Location is only available for accounts with the location offering). * **Attributes:** Qualitative tags or attributes assigned to the response. * **Personas:** Displays the audience segment (often empty by default). * **Response:** A snippet of the raw text returned by the AI. **Table footer** Displays the number of responses currently loaded on the screen compared to the total matching the current filters. **Responses drawer** Clicking any row in the table opens a side drawer. This drawer displays the full, unabridged text of the AI's response, the exact sources cited, competitor details, and qualitative attributes. **Export Responses dialog** Triggered by the "Export as CSV" button, this modal lets the customer choose how many responses to export. It offers quick-select amounts (e.g., 1,000, 5,000) and an "Export all" option based on the live total of filtered responses. ## What you can do here * **Filter the list:** Click "Add filter" to restrict the data by Model, Source, Cited Page, Prompt Status, Sentiment, Competitors, Tags, and many more metrics. * **Save filter views:** Click the saved-views dropdown to save the current filter combination for future use, or load a previously saved view. * **Change visible columns:** Click the "Columns" button in the top right to show, hide, or reorder table columns. * **Export to CSV:** Click "Export as CSV" to download the filtered response data. In the resulting dialog, choose the volume of rows to export and confirm. * **Sort the table:** Click on specific column headers (like Date) to re-sort the table ascending or descending. * **Resize columns:** Drag the edge of any column header to resize it. Double-clicking the resize handle automatically fits the column width to its content. * **Read full responses:** Click any row in the table to open the details drawer. * **Navigate between responses:** While the drawer is open, use the Up/Down arrow keys on your keyboard to rapidly move to the previous or next response in the list without closing the drawer. * **Mobile actions:** On mobile devices, the Export and Columns controls are tucked inside a mobile overflow menu (represented by a menu icon). ## Data shown This page displays the exact prompt responses collected by AI models (like ChatGPT, Claude, Gemini, Perplexity, Copilot, Grok, DeepSeek, Meta AI, etc.) for the customer's tracked content and competitors. The table also pulls in brand and competitor logos based on the tracked entities in the customer's account. Filter dropdowns (like competitors, personas, locations, countries, tags) are populated dynamically based on the data configured for the active website. ## Common workflows ### Inspect the searches behind an answer Open a response and expand **Search queries** when captured queries are available. These are searches the model issued while preparing its answer, not your monitored prompt text. Missing captured queries do not prove the model performed no search. For counts across responses and CSV exports, open the prompt's search-query view on the Prompts page. **Investigate why a competitor is mentioned in AI answers** 1. Open the "Add filter" menu and select "Competitors". 2. Choose the specific competitor of interest. 3. Optionally, add a "Model" or "Date Range" filter to narrow the scope. 4. Scroll through the table and click on a row to open the response drawer. 5. Read the full response text and review the cited sources to understand the context of the competitor's mention. **Export a filtered slice of responses to CSV** 1. Apply the desired filters (e.g., Models, Date Range, Brand Mentioned = Yes). 2. Click the "Export as CSV" button in the top right toolbar. 3. In the Export Responses dialog, choose a quick-select amount, type a custom amount, or click 'Export all'. 4. Click Export and wait for the progress toast to complete to receive your CSV download. **Drill into a specific prompt's responses from the Prompts page** 1. While reviewing analytics on the Prompts page, click a metric or response count for a specific prompt. 2. You are automatically navigated to the Responses page, which is now temporarily scoped strictly to that prompt. 3. Browse, sort, and filter within this narrowed list. 4. Click the "Back" arrow in the page header to seamlessly return to the Prompts page. **Customize which columns are visible** 1. Click the "Columns" button in the toolbar. 2. Toggle the checkboxes to show or hide columns (e.g., turning on "Market Position" or "Attributed Citation"). 3. Click and drag the handles next to column names in the picker to reorder how they appear left-to-right. 4. These layout preferences are saved locally for your next visit. ## Empty, loading, and error states * **Empty:** If the applied filters yield no results, the table body displays the message "No responses found." * **Loading:** While data is being fetched or filters are initializing, a centered animated loader appears in the table area. The table headers remain visible. * **Error:** If response data fails to load, the system relies on standard query error handling (logging to the console and standard fallbacks). If an export fails, a toast notification reading "Export failed" appears. If the total number of exportable rows cannot be calculated, the Export dialog displays "Unable to load total" in the amount field. ## Linked from / links to **Linked from:** * **Prompts page:** Via drilldowns on prompt analytics cards. * **Ads tab:** Via drilldowns focusing on sponsored placements. * **Competitors page:** Via links exploring specific competitor mentions. * **Action Center:** Through attributed citation links. * **Dashboards (Olympus, Sankey):** Through temporary filter handoffs. **Links to:** * **Previous pages:** If the user arrived via a drilldown link, a "Back" button appears in the header returning them to their origin (e.g., the Prompts or Ads page). ## Common support questions **Why can't I click the "Export as CSV" button?** CSV exports are only available on paid subscription plans. If you are on a free plan, clicking the export button will open a prompt to upgrade your subscription instead of downloading the file. **Why are some columns missing from my table?** To keep the view clean, several columns - such as Market Position, Attributed Citation, Cited, Personas, and Attributes - are hidden by default. You can reveal them at any time by clicking the "Columns" button in the top right and checking their boxes. **How are sponsored ChatGPT placements counted?** Sponsored ChatGPT placements are reported separately and do not count as organic mentions or citations. If an advertiser also appears in the answer text or organic sources, only that organic occurrence contributes to organic metrics. # Activity Log (Settings → Activity) Source: https://docs.athenahq.ai/guides/settings-activity Search, filter, and export your organization's audit trail > [card] [Open in AthenaHQ](https://app.athenahq.ai/settings/activity) > > `app.athenahq.ai/settings/activity` ## Purpose The Activity Log provides a searchable, filterable, and exportable audit trail of every change made across your organization. It allows teams to track who performed specific actions, what resources were affected, and when those changes occurred. This feature sits within the settings area and is exclusively available to customers on the Enterprise plan. It is primarily used by organization administrators and team leads for security, compliance, and troubleshooting workflows. ## What's on the page * **Toolbar / filter bar**: A band below the page header containing the date range picker, filter controls, a "Clear all" link (when filters are active), and the "Export CSV" button. * **Audit Log Timeline**: A table displaying a chronological list of all audit-logged actions, grouped by calendar day. * **Time**: Displays how long ago the event occurred (e.g., "2 hours ago"). Hovering over the relative time reveals the absolute date and time (e.g., "Jan 5, 2025 at 3:45 PM"). * **Actor**: Shows who performed the action. This can be a user's name or email, an API key, or "System" for automated tasks. It includes a badge indicating the actor's role (e.g., Owner, Admin, Viewer, External, or a custom role). If a website-only member views the page, actors they do not have permission to see are masked as "Organization member" or "Organization API key". * **Website**: Indicates the specific website the action applied to, or displays "Organization" if the action affected the entire organization. * **Action**: A plain-language summary of the event (e.g., "Created prompt"), often followed by the name of the affected resource or extra context. * **(Unlabeled chevron column)**: A right-arrow that appears when hovering over rows that contain deeper details. Clicking the row opens the event details. * **Table Footer**: Sits below the timeline, displaying a count like "Showing 50 of 300 events" and an animated loading indicator when fetching more rows. * **Event details dialog**: A popup that opens when clicking a supported row. It displays: * **Resource**: The type, ID, and name of the affected item. * **Changes**: A color-coded breakdown showing exactly what changed, labeled "Before" and "After". * **Metadata**: Raw, advanced information related to the event. ## What you can do here * **Filter the activity log**: Click the "Filter" button to narrow down events by specific criteria: * **Actor role**: Filter by Owner, Admin, Viewer, or External. * **Actor**: Select specific people from a dropdown. * **Website**: Filter by one or more websites, or select "Organization" for org-wide events. * **Event categories**: Filter by broad categories like "User management", "Content", "Billing", "Integration", etc. * **Event**: Type an action pattern (e.g., "user:*", "prompt:*") into a text field to find specific technical events. * **Status**: Filter by "Success", "Failed", or "Pending". * **Filter by date**: Click the date picker to choose a preset ("Last 7 days", "Last 30 days", "Last 90 days", "All time") or select a custom date range. * **Clear filters**: Click the "Clear all" button to instantly remove all active filters. * **Export CSV**: Click the "Export CSV" button to download a spreadsheet of the currently filtered events. * **Expand/collapse days**: Click on a date heading in the timeline (e.g., "Today, Oct 24, 2024") to collapse or expand the list of events for that day. * **View event details**: Click on a specific row in the timeline to open a detailed modal showing what changed. * **Load more events**: Scroll to the bottom of the timeline to automatically fetch and display older events. * **Upgrade plan**: If you are not on the Enterprise plan, click the "Upgrade plan" button in the empty state to navigate to your billing settings. * **Retry loading**: Click the "Retry" button if the page fails to verify your subscription access. ## Data shown The data displayed on this page represents your organization's historical audit trail. It pulls from a centralized log of all supported changes made by your team members, API keys, and automated system jobs. The dropdown filters pull from your organization's list of members and your tracked websites to provide accurate filtering options. ## Common workflows 1. **Investigate what changed on a resource** 1. Navigate to the Activity page in Settings. 2. Use the date picker to narrow the timeline to the suspected timeframe. 3. Click the Filter button to isolate the changes (e.g., filter by "Website" or "Event categories"). 4. Locate the specific action in the timeline and click the row to open the Event details dialog. 5. Review the "Before" and "After" data in the Changes section to see what was modified. 2. **Export a filtered slice of the audit log** 1. Apply filters and a date range to isolate the events you need. 2. Check the tooltip or table footer to ensure the total number of matching records is 10,000 or fewer. 3. Click the "Export CSV" button in the top right. 4. Your browser will download a file named `audit-logs-[date].csv`. 3. **Upgrade to unlock the Activity log** 1. Navigate to the Activity page. 2. If your organization is on a non-Enterprise plan, read the "Activity log" description outlining the feature. 3. Click "Upgrade plan". 4. You will be redirected to the Billing page where you can change your subscription tier. ## Empty, loading, and error states * **Loading**: While fetching your data, the page shows a skeleton placeholder outline of the filter bar and several empty rows in the table. * **Empty (No events)**: If there are no events matching your filters, the table shows "No activity in this period" and suggests adjusting your filters or date range. If the organization has absolutely no logged activity, it simply shows "No activity available". * **Upgrade empty state**: Customers on non-Enterprise plans see a locked screen titled "Activity log" explaining that the feature is "Available on the Enterprise plan", accompanied by an "Upgrade plan" button. * **Error**: If the page fails to verify your plan access, it displays a "Couldn't verify access" card with a "Retry" button. If an error occurs while fetching the actual log data, a red toast notification will appear in the corner of the screen. ## Linked from / links to * **Linked from**: The "Activity" item in the Settings sidebar. * **Links to**: The "Upgrade plan" button takes customers to the Settings → Billing page. ## Common support questions **Why is the "Export CSV" button disabled?** Exports are capped at 10,000 records to ensure system performance. If your active filters match more than this limit, the button is disabled. Hovering over it will show a tooltip reading: "Export is limited to 10,000 records (\[Number] match). Narrow the date range or filters." You must apply stricter filters to export the data. **Why can't I click on a specific log row to see details?** Rows are only clickable if they contain deeper details, such as before/after changes or extra metadata. If an action didn't log any specific data modifications, the row will not open a dialog. Hovering over a row reveals a chevron arrow on the right side only if details are available. **Why are some actor names showing as "Organization member" or "Organization API key"?** If you are an external member invited only to specific websites, the identities of people and API keys outside of those accessible websites are hidden to maintain organizational privacy. **What does the "System" actor mean?** "System" indicates that the action was performed automatically by Athena's background processes (such as automated data syncing or maintenance tasks) rather than by a specific user. # API & Embed Settings Source: https://docs.athenahq.ai/guides/settings-api Manage AthenaHQ API keys, MCP/Looker Studio integration guides, and embeddable-dashboard credentials for the organization. > [card] [Open in AthenaHQ](https://app.athenahq.ai/settings/api) > > `app.athenahq.ai/settings/api` ## Purpose The API Settings page allows customers to manage programmatic access to their organization's data. From this page, customers can generate and revoke API keys, access integration guides for Looker Studio and Model Context Protocol (MCP), and configure iframe embed credentials to display the dashboard within their own applications. ## What's on the page **View-only banner** If a user lacks permission to manage API keys, a banner reading "View-only · API" appears at the top of the page. Hovering over it displays the tooltip: "Ask an org admin for API write access to make changes here." ### API keys tab **Header Controls** * **Key Count**: Displays the total number of keys (e.g., "3 keys"). * **Guides dropdown**: A menu offering quick setup instructions for specific integrations. * **Create API Key button**: Opens the dialog to generate a new key. **API keys table** Lists all existing API keys the user has permission to view. * **Name**: The display name given to the API key. * **Key**: A preview of the key, showing the prefix followed by a masked suffix (e.g., `sk_live_••••••`). * **Websites**: Displays which websites the key is authorized to access. It shows an "All Websites" badge for global keys, a "None" badge for empty scopes, or up to 4 website logos. If there are more than 4, a `+N` overflow chip appears (hovering shows a tooltip with the remaining website names). * **Created**: The date the key was generated. * **Created By**: The email address of the user who generated the key. * **`...` (Actions menu)**: A kebab menu on the far right of each row containing **Edit** and **Delete** actions. **Locked / Empty States** * **Locked API Upsell**: If the customer's plan does not include API access, the entire panel is replaced by a "Put your AthenaHQ data to work" upsell. Depending on their role, they will see a **Subscribe** button (which opens a live quote and checkout flow) or a **Contact Team** button. * **Empty State**: If the organization has API access but no keys exist, an illustrated card reads "Create your first API key" with a primary **Create API Key** button. ### Embed tab **Allowed domains** * A section listing all web domains permitted to embed the dashboard via iframe. * **Add Domain button**: Opens a setup wizard to authorize a new domain. * **Domains List**: Shows the authorized domain URL and the date it was "Added". Each row has a `...` menu with a **Delete** action. **Embed tokens** * A section listing the secure tokens used by the customer's backend to authenticate embed sessions. * **Create Token button**: Opens a dialog to generate a new token. * **Tokens List**: Shows the token's name, a status badge ("Active" or "Paused"), and "Last used \[date]" (or "Never used"). Hovering the row reveals the creation date. Each row has a `...` menu with **Pause** (or **Unpause**) and **Delete** actions. **How to embed Athena** An expandable accordion at the bottom of the tab containing reference documentation. It includes the exact HTML `