GET /sites/series_performance

Compares each AI service (series) for a site over a period against a previous period, for example month over month: mention rate, mentions, average position, sentiment, citation count, and prompt coverage.

Request

Endpoint

https://knowatoa.com/api/v2/sites/series_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
start_date	string	Yes	Period start (YYYY-MM-DD)
end_date	string	Yes	Period end (YYYY-MM-DD), inclusive. At most 366 days after 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
flat	string	No	Set to "true" for flat JSON format (one row per series)
format	string	No	Set to "csv" for CSV export (one row per series)

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

Response

Nested JSON Format

Truncated to two metrics; every response includes all the metrics listed under Metrics.

{
  "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 },
  "metrics": {
    "mention_rate": { "current": 42.5, "previous": 35.0, "change_points": 7.5, "change_percent": 21.4 },
    "prompt_coverage": { "current": 60.0, "previous": 50.0, "change_points": 10.0, "change_percent": 20.0 }
  },
  "series": [
    {
      "series": { "id": "spx_xyz789", "name": "ChatGPT" },
      "metrics": {
        "mention_rate": { "current": 50.0, "previous": 40.0, "change_points": 10.0, "change_percent": 25.0 },
        "prompt_coverage": { "current": 70.0, "previous": 55.0, "change_points": 15.0, "change_percent": 27.3 }
      }
    }
  ]
}

metrics covers the site across all series; each series entry has the same metrics for one series. Every metric has current, previous, change_points, and change_percent (see Period Comparison).

Metrics

Metric	Description
mention_rate	Mentions ÷ samples, as a percentage
mentions	Completed AI responses that mention the site
samples	Completed AI responses
average_position	Average order of first appearance among tracked brands
sentiment_score	Average sentiment of scored mentions (-1 to 1)
sentiment_evaluated	Mentions with a sentiment score
positive_count, neutral_count, negative_count	Mentions by sentiment bucket
citation_count	Citations in the site’s AI responses
prompt_coverage	Percentage of sampled questions (`questions_sampled`) mentioned at least once in the period
questions_mentioned	Sampled questions mentioned at least once
questions_sampled	Questions with at least one completed AI response

Flat JSON and CSV

One row per series, with no all-series rollup row. Only count columns (mentions, samples, sentiment_evaluated, the sentiment bucket counts, and citation_count) can be summed across rows. Rates, averages, and coverage (mention_rate, average_position, sentiment_score, prompt_coverage) cannot, and neither can questions_mentioned or questions_sampled, because the same question is counted once in every series it ran in. Use the nested metrics block for all-series values. Columns: site_id, site_name, external_id, period_start, period_end, compare_start, compare_end, series_id, series, then <metric>_current, <metric>_previous, <metric>_change_points, and <metric>_change_percent for each metric.

Notes

null means no completed AI responses in that period, not zero. average_position is also null with no mentions, and sentiment_score with no scored mentions.
Prompt coverage counts each question once, so the all-series value is not the sum or average of the per-series values.
History is grouped by AI service, so it carries across model upgrades.
Only target sites are supported; competitor sites return an error.