API v2 Overview

What’s New in V2

The V2 API provides comprehensive data export capabilities that mirror the CSV export functionality in the Knowatoa web application. Key improvements include:

• Multiple Output Formats: Every endpoint supports JSON (nested and flat) and CSV formats
• Site-Level Exports: 6 endpoints for individual site data
• Account-Level Exports: 6 endpoints for aggregated data across all sites
• BI Tool Integration: Flat JSON format optimized for Looker Studio and similar tools
• Consistent Data Structure: Matches CSV exports exactly for seamless migration

Base URL

All V2 API endpoints are relative to:

https://knowatoa.com/api/v2/

Authentication

Same as V1 - include your API key as a query parameter:

?api_key=YOUR_API_KEY

Output Formats

Nested JSON (Default)

Standard hierarchical JSON structure:

https://knowatoa.com/api/v2/sites/questions?site_id=tpc_abc123&api_key=YOUR_API_KEY

Flat JSON (for BI Tools)

Flattened array format for Looker Studio, Tableau, etc. Add the flat=true   parameter:

https://knowatoa.com/api/v2/sites/questions?site_id=tpc_abc123&api_key=YOUR_API_KEY&flat=true

CSV Export

CSV format matching web application exports:

https://knowatoa.com/api/v2/sites/questions?site_id=tpc_abc123&api_key=YOUR_API_KEY&format=csv

Period Comparison

By default every endpoint returns the latest refresh. sites/visibility, sites/sentiment, sites/sources, and sites/competitors also accept a period, and then return totals across every refresh in that period compared to a previous period. sites/question_performance always reports a period (the last 30 days unless you pass one), broken down per question and series:

https://knowatoa.com/api/v2/sites/visibility?site_id=tpc_abc123&api_key=YOUR_API_KEY&start_date=2026-09-01&end_date=2026-09-30

Every metric is returned as:

"mention_rate": { "current": 42.5, "previous": 35.0, "change_points": 7.5, "change_percent": 21.4 }

• change_points is the absolute change (percentage points for rates).
• change_percent is the change relative to previous, or null when previous is 0.
• null means no completed AI responses in that period (none ran, or they are still running or failed), not zero. A completed response that does not mention the site counts as 0. Check refresh_count on period and compare_to.
• Mention rate is mentions ÷ completed AI responses, so with weekly refreshes a one-month period has about four samples per question and AI service.
• Only tracked questions and the AI services on your plan are counted, so period totals (including citation counts) can differ from the latest-refresh output, which counts every response in the refresh.
• History is grouped by AI service (series), so it carries across model upgrades within a service. If an upgrade leaves both models on one refresh, only the newer model counts.
• Sentiment counts use: negative ≤ -0.1, neutral ≤ 0.1, positive above 0.1.
• Flat JSON and CSV return one row per series, domain, or brand (no rollup row, so count columns can be summed; rates, averages, and coverage cannot), with <metric>_current, <metric>_previous, <metric>_change_points, and <metric>_change_percent columns.

Available Endpoints

Site-Level Exports

• GET /sites/questions - Questions with mentions and sentiment
• GET /sites/rankings - AI responses with ranks and citations
• GET /sites/sentiment - Sentiment analysis per series
• GET /sites/sources - Citation domains from AI responses
• GET /sites/visibility - Appearance rates across series
• GET /sites/competitors - Competitor visibility analysis
• GET /sites/question_performance - Per-question, per-series performance over a period
• GET /sites/series_performance - Per AI service mention rate, sentiment, citations, and prompt coverage over a period vs. the previous period

Account-Level Exports

• GET /account/questions - All questions across all sites
• GET /account/rankings - All rankings across all sites
• GET /account/sentiment - All sentiment data across all sites
• GET /account/sources - All sources across all sites
• GET /account/visibility - All visibility data across all sites
• GET /account/competitors - All competitor data across all sites

Terminology

• Site: A business/website being monitored (internally called “topic”)
• Series: Collection of AI models (ChatGPT, Perplexity, etc.)
• Question: Search query used to test AI responses
• Rank: Position where site appears in AI response
• Mention: Whether the site appears in an AI response
• Sentiment: Tone of mention (Positive, Neutral, Negative, Mixed)