AthenaHQ

Tools

• open_ai_accessOpen the AthenaHQ AI crawler access panel. Enter a public HTTPS domain to inspect crawler responses and robots.txt permissions without an AthenaHQ account.
• check_public_ai_accessCheck HTTP responses to AI crawler user agents and robots.txt permissions for a public website. No AthenaHQ account required. Search, retrieval and training are separate. Requests originate from AthenaHQ, not verified crawler IPs. Unknown responses are inconclusive; this does not measure visibility or guarantee indexing, citations or real crawler access. Use nullable evidence and diagnostics.
• get_prompt_schedulesList the 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; archived schedules retain results. To combine schedules, pass several selection values as an array in the schedule field of query_metrics and query_rows, or use a saved view that stores several schedules. Partner REST filters take one schedule. starts_on and ends_on bound a custom schedule's active period as UTC days (null means no bound); an active schedule outside its period does not run.
• get_ai_search_valueAI Search Value for a website: topic-market value, captured value range, headroom, coverage, value-weighted AI share of voice, per-topic detail, and modeled attributed contribution.
• get_promptsList prompts (search queries) tracked for a website
• get_prompt_tagsList prompt tags for a website with per-tag prompt counts. Tag IDs can be used with the prompt_tags filter on the prompts endpoint.
• get_personasList personas configured for a website with per-persona prompt counts. Use it to resolve persona_id values returned by other tools to persona names and descriptions.
• get_topicsList topics (groupings of prompts) for a website, with the count of prompts in each
• get_competitorsList competitors tracked for a website
• get_content_hub_sheetsList the Content Hub tabs/sheets configured for a website. Use to discover available tabs (e.g. 1st-party content, 3rd-party placements, Reddit) before calling get_tracked_content with a specific sheet_id (metrics; excludes in-flight pipeline items) or list_content (every item including unpublished drafts).
• get_tracked_contentList tracked content (1st-party drafts, imported pages, 3rd-party placements) with citation, mention, and impression metrics for the supplied date range and filters. Supports pagination via page_num / page_size and optional filtering by Content Hub sheet_id or content_type. A sheet_id of a view-type tab (see get_content_hub_sheets sheet_type) lists the shared main pool: content not filed in any sheet. In-flight pipeline items (drafts, briefs, running generations) never appear here; enumerate those with list_content. A returned item can still lack a url (pipeline finished but not published anywhere yet).
• list_contentEnumerate every content item in a website's Content Hub, published or not: in-flight drafts, briefs, snipes, optimize and slice runs, scheduled and failed items, plus tracked pages. Returns identity fields only (id, title, type, stage, sheet, URL, timestamps, target prompt ids), no metrics. Uncached and Postgres-backed, so an item created by create_content is listable immediately. Filter by sheet_id, content_type, stage, or prompt_id. stage is the raw pipeline workflow state, not a publication flag: null = no pipeline record (most tracked external / imported pages), and manual editor items carry 'generated'. Treat an item as published only when its stage is done (or it is an external / imported page) AND it has a url; done without a url is an unpublished orphan. A sheet_id of a view-type tab (see get_content_hub_sheets sheet_type) lists the shared main pool without the view's saved filters. Use get_tracked_content for citation and impression metrics on published content; use this tool to discover what exists. Each row carries prompt_ids: the prompts that item was WRITTEN FOR (what create_content was given), capped at 25 with the true size in prompt_count — resolve the ids to text with get_prompts rather than calling get_content_detail per row, and drill in with get_content_detail where prompt_count exceeds the ids returned (that read carries up to 100; associations past 100 are not currently readable). prompt_ids includes soft-deleted prompts, which get_prompts does NOT list — an id that fails to resolve there is a deleted prompt, and get_content_detail returns its text and status: "deleted". Empty prompt_ids means no targeting was recorded, which is normal for imported or externally tracked pages. This is not the same as being cited for a prompt — see get_content_citation_prompts for that. Filter by prompt_id for the reverse question: which content already targets a given prompt (coverage gaps).
• get_content_detailFetch the full detail of a single tracked content item — its brief and body text (drafts, optimize rewrites, snipes, authored and scraped pages), plus status, cited source URLs, and links. Use after get_tracked_content to read the actual text behind a content_id. A status of generated_brief means the brief is ready while the article is still being written. Pages registered via track_content_urls return a null body and null status until their page text is fetched from the app — a null body on an external page means not fetched yet, not missing content; citation tracking does not need the body. `prompts` lists the prompts this page was WRITTEN FOR (the same ids create_content takes), newest-linked last, capped at 100 with the true size in `prompts_total`. When prompts_total exceeds 100 the rest are not currently readable through any tool — report the total, do not imply the list is complete. Entries carry status active, paused or deleted: a deleted prompt is still part of what the page was written for and still shows in the Content Hub, but get_prompts will not list it, so use the text returned here. An empty array means the page has no prompt targeting, which is normal for imported or externally tracked pages. That is a different question from get_content_citation_prompts, which lists prompts whose AI responses CITED the page. To see the reworded variants actually asked of the models for these prompts, pass their ids to get_responses (each row carries base_prompt plus the variation as prompt) or query the responses cube via query_rows on the prompt_variation dimension.
• get_content_citation_promptsFor a single tracked content item, list every prompt whose AI responses cited it — with citations, citation %, and estimated impressions. Use after get_tracked_content to drill into which prompts a given URL is appearing for. This is CITED-BY, measured over the requested date range, not the targeting the page was written for: an empty prompts array means no AI response cited this URL in that window, which is expected for new or never-cited pages and is not missing data. For the prompts a page was written to target, read `prompts` on get_content_detail (or prompt_ids on list_content) — those come from the content record itself and do not depend on any citation having happened.
• list_websitesList every website accessible to the calling session. Works with any API key (global or scoped) and with MCP/OAuth sessions. Call with an empty argument object `{}`. Each item includes `baseCountry`, the country market the website targets: use it to tell same-brand websites for different countries apart.
• get_locationsList geo-locations configured for a website
• get_date_rangeGet the earliest and latest response dates for a website
• get_responsesGet LLM responses for a website. Shows how AI models answer queries, with sources, sentiment, and ranking data. Filter by whether a model used search queries or by text within those queries. For a variation-level export at volume, pair filters.variation_filter with include_response: false and compact_sources: true. That keeps the prompt, its variation, the model, the mentioned/cited flags and the cited domains while dropping the answer text, cutting each row to roughly a tenth of its size.
• get_response_streaming_statusRead the latest (or a specific) response-streaming run's whole-run state and response-queue progress. Only completed means downstream analysis has finished
• get_response_detailFetch a single LLM response by id with full sources, mentions, and rank details.
• get_saved_viewsList saved views (filter presets) for a website
• get_group_saved_viewsList group-level saved views (filter presets) shared across the websites in a group
• get_credits_organizationGet credit balance for the organization
• get_credits_websiteGet credit balance for a specific website
• get_groupsList all groups in the organization (global API key only)
• get_group_detailFetch a single group by id with its member websites.
• get_share_of_voice_cumulativeGet cumulative share of voice — overall SOV for each competitor across the date range. Each entry also includes relative_mention_rate: the share of responses mentioning any tracked brand that mention this entity.
• get_share_of_voice_time_seriesGet share of voice over time — how often the website is mentioned vs competitors, grouped by day. Each entry also includes relative_mention_rate: the share of that day's responses mentioning any tracked brand that mention this entity.
• get_citation_rate_cumulativeGet cumulative citation rate — average citation rate for each competitor across the date range.
• get_citation_rate_time_seriesGet citation rate over time — how often AI models cite (link to) the website, grouped by day.
• get_mention_rate_cumulativeGet cumulative mention rate — average mention rate for each competitor across the date range. mention_rate is absolute (share of all responses); relative_mention_rate is the share of responses mentioning any tracked brand.
• get_mention_rate_time_seriesGet mention rate over time — how often AI models mention the website by name, grouped by day. mention_rate is absolute (share of that day's responses); relative_mention_rate is the share of that day's responses mentioning any tracked brand.
• get_position_cumulativeGet cumulative position — average ranking position for each competitor across the date range.
• get_position_time_seriesGet ranking position over time — average position of the website in AI model responses, grouped by day.
• get_position_distributionGet position distribution: share of responses where the brand ranks top/middle/bottom across the date range.
• query_metricsQuery aggregated metrics for brand performance, competitors, sources, citations, and response trends. Use query_rows for individual records. Mentions: from "response_mentions". Citations: from "citations". On either, where { is_website: true } selects the brand; { is_competitor: true } selects competitors; { entity_id: { eq: "<uuid>" } } selects one entity. Filter/group models by model_category (display names like "ChatGPT", "Claude"), never "model". Dimensions vary by cube; source_mentions has no prompt/model dimensions. Group by week (Monday start) or month wherever date groups. prompt_status is the paused flag (true = paused). Measures: count, count_distinct, avg, sum, min, max; per-measure where enables conditional aggregation. Use compare for two date ranges. When grouping by IDs, use alsoSelect for names: entity_id/entity_name, prompt_id/prompt_text, prompt_topic_id/topic_name (prompts uses topic_id). Cited pages mentioning competitors but not the brand: from "sources", where { source_mentions_entity: { hasSome: [competitorIds], hasNone: [brandId] } }. Also works on "source_mentions". Checks all stored page mentions per URL/website. Date/model on sources scope AI responses; extracted page content may be older than the live page. Content-hub attribution: on "sources", where { is_attributed_content: true }; by: ["content_id"], alsoSelect: ["content_title"]. Add content_type to by for type, or group by content_type alone. Read articles from "contents" via query_rows. Schedule: select one "default" or custom/archived UUID from the catalog, or an array of them to combine schedules. Omit for caller default (current page in Ask Athena); explicit schedule overrides it. Top-level prompt_schedule_kind/id equality filters remain supported but must not conflict with schedule. Historical provenance is independent of current prompt membership; website-level cubes are unaffected.
• query_rowsQuery individual analytics rows. Use for qualitative data like response text, specific identifiers, or individual mentions. Schedule selection: pass schedule: "default" or a custom/archived UUID from the schedule catalog, or an array of them to combine schedules. Omit to use the caller default (Ask Athena uses the current page selection). Explicit selection overrides that default. Existing top-level equality predicates on prompt_schedule_kind/id remain supported, but cannot conflict with schedule. Historical provenance does not change with current prompt membership. Website-level cubes are unaffected. Cubes (same set as query_metrics): attributes, citations, competitors, contents, prompts, response_mentions, responses, source_mentions, sources, topics, websites. Returns { rows, nextCursor, hasMore }. Pass nextCursor back as "after" to paginate. prompt_status is the prompt's paused flag (boolean, true = paused), not a status string. On the responses cube, content is hydrated from Postgres and can only be selected. Do not filter or sort by content. Use search_terms_in_responses for text frequency analysis. Use query_metrics for aggregates instead.
• list_pitchesList pitch workspace reports for the organization. Returns all non-deleted pitches with their status and metadata.
• get_pitchGet a pitch report by ID including competitors, prompts, attributes, top citing sources, and aggregate metrics (brand mentions, sentiment, response rate).
• get_sourcesList top cited sources (root domains) for a website with citation, mention, brand-mention, and impression metrics. Each row is classified as owned / competitor / partner / third_party. Supports filters (date range, models, prompts, competitors, locations, personas), sort, and pagination via page_num / page_size.
• get_source_pagesList individual cited URLs (pages) for a website with citation, mention, and impression metrics plus a per-URL daily sparkline. Each row is classified as owned / competitor / partner / third_party. Companion to get_sources (root-domain-level). Supports filters (date range, models, prompts, competitors, locations, personas), search, sort, and pagination.
• get_attributesList the brand traits (called attributes in the API) tracked for a website: brand-perception keywords such as 'Affordable' or 'Slow Support'. Athena extracts these from AI model responses. Brand traits are direction-neutral; `positive` selects the directional series and defaults to true when omitted. Use this to discover attribute ids, then get_attribute_metrics for how often each is mentioned, or get_attribute_time_series for one attribute's trend over time.
• get_attribute_metricsGet cumulative brand trait (attribute) metrics: for each brand-perception keyword (e.g. 'Affordable', 'Slow Support'), how many AI responses mentioned it across the date range, and the percentage. `positive` selects the observation direction and defaults to true when omitted. `total_responses` is the denominator: responses in the date range that mention the brand AND had attribute extraction run on them. It is NOT every response for the website — responses that never mention the brand are excluded, and Athena samples which responses get extraction, so un-analyzed ones are excluded too. Compute rates from the returned `percentage` / `total_responses` rather than against a response count from another endpoint. Attributes nobody mentioned come back with response_count 0. Use get_competitor_attribute_metrics for the same breakdown per competitor.
• get_competitor_attribute_metricsGet brand trait (attribute) metrics per tracked competitor: for each competitor and each brand-perception keyword (e.g. 'Affordable'), how many AI responses mentioned that keyword for that competitor, and the percentage. Use with get_attribute_metrics to compare the brand against competitors. `total_responses` is per-competitor: responses in the date range that mention THAT competitor and had attribute extraction run on them. Each competitor therefore has its own denominator, and none of them is the website's total response count. `positive` selects the observation direction and defaults to true when omitted. Returns one row per competitor per attribute, so results can be large — filter with competitor_ids. Competitors with no responses in the date range are omitted entirely rather than returned with zeros.
• get_attribute_time_seriesGet the daily trend for ONE brand trait (attribute), brand and competitors side by side — how mentions of a keyword like 'Affordable' moved over time. Requires an attribute_id: call get_attributes first to discover ids. `positive` selects the observation direction and defaults to true when omitted. Days with no data are returned as zeros, so the series is gap-free and chartable. Denominators are per-side, not the day's whole response set: brand_percentage divides by that day's responses that mention the brand (and had attribute extraction run), and competitor_percentage by responses that mention the tracked competitors. brand_total and competitor_total return those denominators explicitly. Competitor figures aggregate all tracked competitors unless competitor_ids narrows them.
• get_attribute_observationsGet individual brand trait (attribute) observations: each row is one AI response describing one entity (the brand or a competitor) with one brand trait, including the response excerpt as `text_span`. `score` runs from -1 to 1 and its sign always matches `positive`; its magnitude (0.1 to 1.0) is how strongly the wording praises or criticizes. `score` is null when the observation was not scored (extracted before scoring existed, or no valid value was recorded); for direction only, use `score ?? (positive ? 1 : -1)`. Omit `positive` for both directions. `sort: "intensity"` (the default) returns the strongest observations first with unscored ones last; `sort: "recent"` returns the newest first. Narrow with entity_ids and attribute_ids (from get_attributes). Paginate with page_num and page_size; a page can hold fewer than page_size rows when an excerpt is no longer available, so use `has_more` to decide whether to fetch the next page. Use get_attribute_metrics for how often each trait is mentioned.
• get_user_by_emailLook up a user by email address, scoped to the caller's organization. Returns 404 when the email does not belong to a member of the organization or of one of its websites.
• get_oracle_findingsWhen grounding is present, use its complete team-confirmed statement and all supporting facts as joint evidence; the legacy fact ID/text are only a compatibility anchor. List Oracle accuracy findings for a website: places where an AI response contradicted a verified brand fact (type 'inaccuracy' or 'kb_issue', with quote, claim, and reason) or where two knowledge-base facts conflict ('kb_duplicate' / 'kb_contradiction', pairing fact_text with related_fact_text). Findings from every status are included by default (pending, acknowledged, ignored, ...), each row carrying its status — pass the status filter for pending items only. Filters (run_id, fact_id, lineage_id, response_id, prompt_id, source_url, type, kind, severity, status) AND-compose; source_url matches evidence URLs exactly after normalization (protocol and trailing slash ignored). 'total' is the pre-limit count. 'latest_run' is the newest scan of any kind and is null only when the website has never been scanned, so latest_run plus empty findings means it scanned clean, while latest_run null means never scanned, not clean. Archived findings from before the current scanner ARE included: their run carries 'is_imported': true and keeps its original started_at, so an import can be the newest run — say the history is archived rather than calling it a current scan. 'has_imported_history' is true when any such archived run exists, and every finding row carries 'run_is_imported' so archival and current rows stay distinguishable in one list. Returns status 'no_access' if the brand does not have Oracle v2; that response carries the status alone, with no counts or findings.
• get_oracle_findingWhen grounding is present, use its complete team-confirmed statement and all supporting facts as joint evidence; the legacy fact ID/text are only a compatibility anchor. Load one Oracle finding in full: the flagged claim with its verified fact and prompt text, the run it came from, a ~2000-character response excerpt centered on the quoted claim, the cited-page evidence captured during the run (url, quote, snippet, scrape_hash), and its lineage: sibling findings sharing its lineage_id across runs, newest first. Use after get_oracle_findings to interrogate a specific finding. Returns a not-found error for an unknown finding id, and status 'no_access' if the brand does not have Oracle v2.
• list_api_keysList the organization's API key metadata, including creator and creation date, oldest first. Includes revoked keys so polling can detect keys revoked between checks. Never returns secrets or hashes. Requires a global API key or an organization admin's MCP connection. For polling, keep since/until fixed while paging, overlap successive windows and deduplicate by id. This is an inventory, not a durable event log; deleted creator accounts remove their keys.
• add_brand_factsAdd brand facts to a website's Knowledge Base in bulk (1-50 per call). Each fact runs the full ingestion pipeline (deduplication, approval gates, pillar routing); there is no way to force-approve. Returns one outcome per fact (approved | pending | duplicate; extensible) with the created fact id and the pillar it was filed under. Facts without a pillar_id are routed automatically and may land unfiled. A fact similar to facts already in the Knowledge Base is not added: its outcome is duplicate and lists them under matches, and the response carries a match_token. To resolve, call again with those facts, the match_token, one decision per listed match (approve, optionally with new text, or delete) and save_submitted (true adds the facts as written, false only applies the decisions).
• add_competitorsStart tracking competitors on a website, 1 to 25 per call, under the same rules as the Competitors page. Each competitor needs a name and its website url, or no_website: true for a brand with no website of its own; identifiers and additional_urls are optional. Returns one result per competitor, in order: added, already_tracked (the website already tracks that url; nothing changes), or rejected with the reason (a url on the website's own domains, an invalid url, or the limit of 500 competitors per website). New AI responses count mentions of an added competitor right away. Past responses are reanalyzed only when someone runs the backfill on the Competitors page, which costs credits; this tool never starts it and costs no credits.
• add_contentAdd an article that is already written (for example, one drafted in this conversation) to the website's Content Hub as an editable draft. Same as pasting it into the Content Hub's blank editor: no AI model runs and no content credits are spent. Use create_content instead when Athena should research and write the piece. body is the full article in Markdown and is stored as given, except that link and image destinations with an unsafe scheme (javascript:, data:) become #. 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. Pass title, or it is taken from the body's first heading (else its first line). sheet_id must be a tab from get_content_hub_sheets: a sheet-type tab keeps the item, a view-type tab or no sheet_id puts it in the shared pool. The item is not published. Once it is live on the site, call publish_content with its URL to start citation tracking.
• approve_briefApprove a content brief and start writing the article from it. Only valid while the piece is at status generated_brief. The article is generated from the brief exactly as it currently stands, including any revisions made with revise_brief or edits made in the app. Consumes content credits; poll get_content_status afterwards, then read the result with get_content_draft.
• create_contentGenerate an article or content brief in AthenaHQ. Fetches source URLs, sends source material to external AI providers, and consumes content credits. Obtain user approval before calling. Does not publish to a website or CMS. For draft mode, auto_approve defaults to true; set false to generate only a brief and wait for approve_brief. Poll get_content_status using each returned content_ids value. Slice mode returns slice_titles and an empty content_ids array; generated items appear in list_content. To save an already-written article without generation or credit use, call add_content.
• create_locationCreate a location for a website
• create_pillarCreate a Knowledge Base pillar (a subject area that groups brand facts) from a name and optional description. Get-or-create semantics: if a pillar with the same name already exists, it is returned with created: false instead of failing, so retries are idempotent.
• create_prompt_tagCreate a prompt tag on a website, or return the existing tag when its name matches case-insensitively. Trims surrounding whitespace and rejects reserved prompt-type names. Returns the tag ID and whether it was created. Use the returned ID to assign the tag to prompts; creating a tag does not assign it to any prompts.
• create_promptsCreate one or more prompts on a website
• create_saved_viewCreate a saved view (filter preset) for a website. Saved views appear in the dashboard filter bar for every member of the website. filters is an object keyed by filter field key, each value shaped {"id": "<unique string>", "field": "<same field key>", "operator": "is_any_of", "values": [...]}. Common field keys: "models" (slugs like "chatgpt", "perplexity", "google_ai_overview"), "competitors", "prompts", "personas", "locations", "promptTags", "attributes" (arrays of UUIDs from the matching list tools), "countries", "sourceTag". "promptTags" also accepts the builtin tokens "type:high_intent" (branded prompts) and "type:discovery" (non-branded) alongside tag UUIDs. "sourceTag" values are the builtin categories "owned", "competitor", "partner", "third_party" or custom source tag UUIDs, not display labels; custom source tag ids appear on existing saved views (list the website's saved views to find them). When unsure, list the website's saved views and mirror their filter shapes. icon, when set, must be a supported Remix icon name (e.g. "RiStarLine"); invalid names are rejected with the full list. When talking to the user about a view or its filters, use the dashboard names (Branded / Non-branded prompts, Owned / Competitor / Partner / Third party sources), never internal tokens, field keys, operator strings, or icon identifiers.

Updated：2026-10-29 (tools/list verified)

Configure in Claude / Cursor

{
  "mcpServers": {
    "remote-ai-athenahq-mcp": {
      "type": "http",
      "url": "https://api.athenahq.ai/api/mcp"
    }
  }
}