GET /sites/sentiment

Returns sentiment analysis for each question across all series.

Request

Endpoint

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

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). With end_date, returns period metrics instead of the latest refresh. See Period Comparison
end_date	string	No	Period end (YYYY-MM-DD), inclusive
compare_start	string	No	Comparison period start. Defaults to the equal-length period before start_date
compare_end	string	No	Comparison period end, inclusive

Response

Nested JSON Format

{
  "site": {
    "id": "tpc_abc123",
    "name": "Example Site",
    "external_id": "example.com"
  },
  "refresh_date": "2025-01-15",
  "series": [
    {
      "id": "spx_xyz789",
      "name": "ChatGPT"
    }
  ],
  "summary": {
    "period": { "start": "2025-01-15", "end": "2025-01-15", "refresh_count": 1 },
    "compare_to": { "start": "2025-01-08", "end": "2025-01-08", "refresh_count": 1 },
    "metrics": {
      "mentions": { "current": 53, "previous": 48, "change_points": 5, "change_percent": 10.4 },
      "positive_count": { "current": 36, "previous": 30, "change_points": 6, "change_percent": 20.0 },
      "...": "..."
    },
    "series": [
      {
        "series": { "id": "spx_xyz789", "name": "ChatGPT" },
        "metrics": { "...": "..." }
      }
    ]
  },
  "sentiment": [
    {
      "question": "What is example?",
      "series_tracked": 5,
      "mentions": 3,
      "percent_mentioned": 60.0,
      "chat_gpt_sentiment": "Positive",
      "perplexity_sentiment": null,
      "positive_count": 2,
      "neutral_count": 1,
      "negative_count": 0,
      "sentiment_evaluated": 3,
      "positive_percent": 66.7,
      "neutral_percent": 33.3,
      "negative_percent": 0.0
    }
  ]
}

Response Fields

Field	Type	Description
series_tracked	integer	Total number of series tracked
mentions	integer	Number of series mentioning the site
percent_mentioned	float	Percentage of series with mentions
[series]_sentiment	string	Sentiment label or null if not mentioned
positive_count, neutral_count, negative_count	integer	Series whose mention of the site falls in each sentiment bucket for this question
sentiment_evaluated	integer	Mentions with a sentiment score (the denominator for the percentages)
positive_percent, neutral_percent, negative_percent	float	Share of evaluated mentions in each bucket, or null when nothing was evaluated
summary	object	Nested JSON only. The latest refresh compared to the refresh before it, in the same shape as the period response below

Period Comparison

Returns period, compare_to, metrics for the site across all series, and series with the same metrics per series. Each metric is {current, previous, change_points, change_percent}. Metrics: mentions, sentiment_evaluated, sentiment_score (average, -1 to 1), positive_count, neutral_count, negative_count, positive_percent, neutral_percent, negative_percent.

Notes

Sentiment buckets: score ≤ -0.1 is negative, ≤ 0.1 is neutral, above 0.1 is positive. These are the same thresholds used for the stored sentiment label
Mentions that have not been scored yet count toward mentions but not sentiment_evaluated
Per-question rows read each series’ current AI model; the summary also counts history recorded under a model the series has since replaced, so the two can differ right after a model change
Count fields are in JSON responses (nested and flat). The CSV layout is unchanged; use GET /sites/competitor_sentiment for counts in CSV (the row with is_target: true is your site)
Sentiment values: “Positive”, “Negative”, “Neutral”, “Mixed”, or null
Percent calculations rounded to 1 decimal place