Docs

GET /sites/question_performance

Returns performance for each tracked question on each series (AI service) over a period, compared to a previous period: whether the site was mentioned, mention rate, average position, sentiment, competitors mentioned, and top cited domains.

Request

Endpoint

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

Query Parameters

Parameter Type Required Description
site_id string Yes Site prefix ID (e.g., tpc_abc123)
api_key string Yes Your API authentication key
flat string No Set to "true" for flat JSON format
format string No Set to "csv" for CSV export
start_date string No Period start (YYYY-MM-DD). Without start_date and end_date, the period is the last 30 days through today. See Period Comparison
end_date string No Period end (YYYY-MM-DD), inclusive. Required with start_date
compare_start string No Comparison period start. Defaults to the equal-length period before start_date
compare_end string No Comparison period end, inclusive
series_id string No Only this series (e.g., spx_xyz789)
tag string No Only questions with this tag (case-insensitive)
limit integer No Questions per page, ordered by question text (default 100, max 200). Each question returns one row per series
offset integer No Questions to skip (default 0) 
https://knowatoa.com/api/v2/sites/question_performance?site_id=tpc_abc123&api_key=YOUR_API_KEY&start_date=2026-09-01&end_date=2026-09-30&format=csv

Response

Nested JSON Format

{
  "site": { "id": "tpc_abc123", "name": "Example Site", "external_id": "example.com" },
  "period": { "start": "2026-09-01", "end": "2026-09-30", "refresh_count": 4 },
  "compare_to": { "start": "2026-08-02", "end": "2026-08-31", "refresh_count": 4 },
  "total_questions": 140,
  "limit": 100,
  "offset": 0,
  "questions": [
    {
      "question_id": "qst_abc123",
      "question": "Best apartments near UT Dallas",
      "tags": ["location", "non-branded"],
      "series": [
        {
          "series": { "id": "spx_xyz789", "name": "ChatGPT" },
          "mentioned": true,
          "sentiment_label": "Positive",
          "metrics": {
            "mention_rate": { "current": 75.0, "previous": 50.0, "change_points": 25.0, "change_percent": 50.0 },
            "mentions": { "current": 3, "previous": 2, "change_points": 1, "change_percent": 50.0 },
            "samples": { "current": 4, "previous": 4, "change_points": 0, "change_percent": 0.0 },
            "average_position": { "current": 1.7, "previous": 2.5, "change_points": -0.8, "change_percent": -32.0 },
            "sentiment_score": { "current": 0.32, "previous": 0.2, "change_points": 0.12, "change_percent": 60.0 },
            "positive_count": { "current": 2, "previous": 1, "change_points": 1, "change_percent": 100.0 },
            "neutral_count": { "current": 1, "previous": 1, "change_points": 0, "change_percent": 0.0 },
            "negative_count": { "current": 0, "previous": 0, "change_points": 0, "change_percent": null },
            "citation_count": { "current": 18, "previous": 15, "change_points": 3, "change_percent": 20.0 }
          },
          "competitors_mentioned": [
            { "site_id": "tpc_def456", "name": "Rival Apartments", "mentions": 2, "mention_rate": 50.0 }
          ],
          "top_domains": [
            { "domain": "apartments.com", "citation_count": 4 },
            { "domain": "zillow.com", "citation_count": 3 }
          ]
        }
      ]
    }
  ]
}

Flat JSON and CSV

One row per question and series, with no rollup row. Each row has site_id, site_name, external_id, period_start, period_end, compare_start, compare_end, question_id, question, tags (separated by ; ), series_id, series, mentioned, sentiment_label, then <metric>_current, <metric>_previous, <metric>_change_points, and <metric>_change_percent for each metric, then competitors_mentioned (e.g. Rival Apartments (50.0%); Other (25.0%)) and top_domains (e.g. apartments.com (4); zillow.com (3)).

Response Fields

Field Type Description
mentioned boolean The site was mentioned at least once in the period. null when no AI responses completed
mention_rate float Mentions ÷ completed AI responses (samples), as a percentage
samples integer Completed AI responses for the question on that series in the period
average_position float Average order of first appearance among tracked brands (site plus competitors)
sentiment_score float Average sentiment from -1 to 1
sentiment_label string Very Negative, Negative, Neutral, Positive, or Very Positive, from the current sentiment_score
positive_count, neutral_count, negative_count integer Mentions by sentiment: negative ≤ -0.1, neutral ≤ 0.1, positive above 0.1
citation_count integer Citations to any domain in those AI responses
competitors_mentioned array Competitors mentioned in the current period, most mentions first, with their mention rate
top_domains array Up to 5 most-cited domains in the current period

Paging

Results are paged by question. Every format returns an X-Total-Questions header, and nested JSON also returns total_questions, limit, and offset. To fetch every question, increase offset by limit until it reaches total_questions.

Notes

  • null means no completed AI responses in that window, not zero. See Period Comparison.
  • Mention rate is sample-based: with weekly refreshes a 30-day period has about four samples per question and series.
  • competitors_mentioned and top_domains cover the current period only.
  • Only tracked questions and the series on your plan are included.