AI Sentiment API endpoint

POST /v1/sentimentAbout AI Sentiment

Score how each AI model talks about a brand as positive, neutral or negative, with the verbatim phrases driving the tone and an aggregate across models.

Overview

Not just whether a model mentions a brand, but how it talks about it. Per model you get a positive/neutral/negative split (summing to ~1) and the verbatim phrases driving it, plus an aggregate across all models queried.

Need a weekly or monthly sentiment history? Save this input with the Tracker API.

Reading the metrics
Sentiment percentages are AI-estimated tone weights, not the share of positive answers. Failed classifications are excluded; no usable answers means unavailable, not 0%.

Reference

POST/v1/sentiment

$0.03 to $0.08 / model · billed per model queried, so all 5 models = $0.30. Pass models to query fewer.

Parameters

querystringrequired
The query whose answers are scored for brand sentiment.
brandstringrequired
The brand to score sentiment for in each model answer.
modelsenum[]optional
AI surfaces to query, each billed separately; pass a subset when the user names surfaces or wants a lower cost. Omit for the defaults (chatgpt, perplexity, gemini); fullSweep queries all five. google_ai_overview accepts queries up to 700 characters, the others 2000.
Values:chatgptclaudeperplexitygeminigoogle_ai_overview
fullSweepbooleanoptional
Query all five AI surfaces (adds claude and google_ai_overview) for full cross-surface coverage, at a higher cost. Ignored when models is given.

Request

curl https://www.cite42.dev/api/v1/sentiment \
  -X POST \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"models":["chatgpt"],"query":"Is Acme CRM a good CRM for startup teams?","brand":"Acme CRM"}'

Response

{
  "query": "Is Acme CRM a good CRM for startup teams?",
  "brand": "Acme CRM",
  "perModel": [
    {
      "model": "chatgpt",
      "classificationStatus": "complete",
      "positive": 0.55,
      "neutral": 0.35,
      "negative": 0.1,
      "phrases": [
        "modern, AI-native CRM",
        "polished UI"
      ]
    }
  ],
  "aggregate": {
    "positive": 0.55,
    "neutral": 0.35,
    "negative": 0.1,
    "phrases": [
      "modern, AI-native CRM",
      "polished UI"
    ]
  },
  "measurement": {
    "methodologyVersion": "2026-09-28-v1",
    "surfaces": [
      {
        "model": "chatgpt",
        "provider": "OpenAI",
        "access": "official-api",
        "webSearch": "auto",
        "status": "complete"
      }
    ]
  },
  "metrics": {
    "definitionVersion": "2026-09-23-v1",
    "checkedAnswers": 1,
    "requestedAnswers": 1,
    "excludedAnswers": 0,
    "note": "A descriptive sample, not a market-wide score. Small samples can swing sharply. Failed, empty and incomplete answers are excluded. Cached observations may be reused. A mention is not an endorsement; position is first-mention order, not a Google ranking. Sentiment percentages are estimated tone weights, not the share of positive answers or customer opinions.",
    "sentiment": {
      "positivePercentage": 55,
      "neutralPercentage": 35,
      "negativePercentage": 10,
      "scoredAnswers": 1,
      "label": "AI-estimated tone across 1 of 1 requested answers"
    }
  },
  "requestId": "…",
  "billing": {
    "cost": {
      "microCredits": 30000,
      "usd": "0.30"
    },
    "balance": {
      "microCredits": 1336000,
      "usd": "13.36"
    }
  }
}