Metrics API

The AnswerixAI Metrics API is a read-only set of endpoints under /api/v1/* for reporting tools. It returns the same numbers the dashboard shows (visibility, trends, competitors and share of voice, citations, AI traffic, prompt performance and shopping cards), so you can combine AnswerixAI data with other sources in Looker Studio, a spreadsheet or your own dashboard. The Looker Studio connector uses this API.

How does the Metrics API relate to the REST API?#

Each Metrics API endpoint returns exactly the same response as the REST API endpoint of the same name under /api/mcp/*. The Metrics API is a deliberately smaller, read-only subset: it has no topics, prompts, content opportunities or site audits. Use the REST API when you need those.

How do I authenticate?#

Send an ans_ API key as a bearer token. Create one in Settings → API Keys; it is shown once.

curl "https://answerixai.com/api/v1/brands" \
  -H "Authorization: Bearer ans_YOUR_KEY" \
  -H "Accept: application/json"

Replace https://answerixai.com with the host of the AnswerixAI app you sign in to (shown in the MCP endpoint in Settings → API Keys). A key reads every brand in its owner's organization, and revoking it takes effect immediately. Requests are limited to 250 per 15 minutes per IP address. Details and error codes are in Authentication.

What conventions does the Metrics API follow?#

Every AnswerixAI Metrics API endpoint is a GET request that returns JSON. brand_id is required on every endpoint except whoami and brands, and date_from and date_to take YYYY-MM-DD dates in UTC. Visibility, trend, competitor, citation and prompt numbers exclude ChatGPT Shopping answers.

• Every endpoint is GET and returns JSON.
• brand_id is required on every endpoint except whoami and brands. Without it you get 400 {"error": "brand_id is required"}.
• date_from and date_to take YYYY-MM-DD in UTC. A bare date_to includes the whole day, through 23:59:59.999 UTC. Leave both out for all history.
• model is a comma-separated list of model identifiers; use the model_used values from competitor-comparison.
• region is a region code such as US. topic_id is a topic UUID from the dashboard or the REST API.
• Errors return {"error": "<message>"} with 400, 401, 402, 404, 429 or 500.
• Visibility, trend, competitor, citation and prompt numbers exclude ChatGPT Shopping answers.

Which endpoints does the Metrics API have?#

The AnswerixAI Metrics API has nine GET endpoints under /api/v1/: whoami, brands, visibility-summary, visibility-trend, competitor-comparison, citations, ai-traffic, prompt-performance and shopping-cards. Every endpoint except whoami and brands requires brand_id.

GET /api/v1/whoami#

GET /api/v1/whoami returns the userId, email and organizationId that your API key resolves to, and needs no parameters. Use it as a connection test.

GET /api/v1/brands#

GET /api/v1/brands returns every brand in your organization as a bare JSON array, newest first, and needs no parameters. Each brand has id, name, slug, industry, region and created_at. Use id as brand_id everywhere else.

[
  { "id": "5d1c2f0e-8a4b-4c3e-9f6a-2b7d1e0c9a88", "name": "Acme", "slug": "acme", "industry": "Software", "region": "US", "created_at": "2026-08-02T09:14:31+00:00" }
]

GET /api/v1/visibility-summary#

GET /api/v1/visibility-summary returns the headline Visibility score, mention and citation totals and top competitors for a brand over a date range, and requires brand_id. This endpoint has no topic_id filter.

• totals.aiVisibilityScore: the Visibility score, 0–100, or null without answers.
• totals.resultCount, totalMentions, totalCitations, mentionAnswers, citationAnswers, positionFactor, avgVisibility.
• topCompetitors: up to 5 competitors with name, mentions, avgVisibility and score.

How is the visibility score in the trend calculated?#

GET /api/v1/visibility-trend returns a brand's visibility as a series of daily or weekly buckets, { "granularity": "...", "buckets": [...] }, and requires brand_id. Each bucket has date, result_count, avg_visibility_score, ai_visibility_score, total_mentions, total_citations and avg_competitor_score.

• ai_visibility_score is the headline Visibility score for that day: 100 × (0.6 × mention rate + 0.25 × citation rate + 0.15 × position factor). The position factor is damped when few answers mention the brand. See Visibility scoring.
• avg_visibility_score is the rounded average of per-answer visibility scores, and avg_competitor_score the same for competitors (null when none appeared).
• granularity=day (default) gives one bucket per UTC day. granularity=week gives one bucket per ISO week, dated to the Monday it starts; weekly buckets have ai_visibility_score: null because the score's parts can't be summed across days.

GET /api/v1/competitor-comparison#

GET /api/v1/competitor-comparison returns your brand's visibility next to each tracked competitor's, plus share of voice, as brand, competitors and share_of_voice. It requires brand_id.

• brand and each entry in competitors carry avg_visibility_score, ai_visibility_score, total_mentions, total_citations and appearance_count; competitors also have competitor_id and name.
• share_of_voice.overall_sov_pct is your mentions as a percentage of your mentions plus competitor mentions. share_of_voice.by_platform repeats it per platform and model_used.

GET /api/v1/citations#

GET /api/v1/citations returns the sources cited in AI answers about a brand as totals, source_type_breakdown, top_domains and top_urls, and requires brand_id.

• source_filter: all (default), owned, competitor or external.
• limit: 1–200, default 50, applied to top_domains and top_urls.
• Every domain and URL has a category: you, competitor, editorial, forum, social, review, institutional or other. Your own domains are always you (the owned filter selects them).
• source_type_breakdown counts each domain once, with category, count and pct.

GET /api/v1/ai-traffic#

GET /api/v1/ai-traffic returns the AI-referred visits recorded by a brand's tracking script, and requires brand_id. Only date_from and date_to filter this endpoint. It returns total_visits, platform_breakdown (platform, visits), top_pages (up to 10, url, visits) and country_breakdown (country, visits).

GET /api/v1/prompt-performance#

GET /api/v1/prompt-performance returns per-prompt visibility, mentions and citations for a brand as brand, window and prompts, and requires brand_id. Each prompt has prompt_id, prompt_text, topic_name, result_count, avg_visibility, total_mentions, total_citations and avg_competitor_score.

• sort_by: visibility (default), mentions, citations or appearances.
• order: desc (default) or asc.
• limit: 1–100, default 10.

GET /api/v1/shopping-cards#

GET /api/v1/shopping-cards returns the product cards from AI shopping answers for a brand with Shopping mode on, newest first, as cards and next_cursor. It requires brand_id.

• role: own, competitor or other.
• platform: the platform slug on the card, for example chatgpt-shopping.
• region: region code.
• limit: 1–200, default 50.
• cursor: pass the previous response's next_cursor to get the next page. It is null on the last page.

Full response examples for every endpoint are in the REST API reference.