Brand stats

For a single brand's headline numbers + a daily history series, hit /api/v1/brands/{id}/stats. This is what answers questions like "how did our visibility improve last week?" or "how many times were we mentioned?".

Request

curl -H "Authorization: Bearer $KEY" \
  "https://api.42a.ai/api/v1/brands/brn_xxx/stats?from=2026-05-08&to=2026-05-14"

const stats = await fetch(
  `https://api.42a.ai/api/v1/brands/${brandId}/stats?from=2026-05-08&to=2026-05-14`,
  { headers: { Authorization: `Bearer ${KEY}` } },
).then((r) => r.json());

console.log(stats.data.visibility_score);             // 0.42
console.log(stats.data.trend.score_change);           // 0.05 = +5pp vs prior week
console.log(stats.data.history[0]);                   // { date, visibility_score, mention_count }

import requests

stats = requests.get(
    f"https://api.42a.ai/api/v1/brands/{brand_id}/stats",
    params={"from": "2026-05-08", "to": "2026-05-14"},
    headers={"Authorization": f"Bearer {KEY}"},
).json()

print(stats["data"]["visibility_score"])
print(stats["data"]["trend"]["score_change"])
print(stats["data"]["history"][0])

The window is set with from / to (ISO 8601 date or datetime, inclusive). Both default to today (00:00 UTC → now). Maximum range: 30 days.

Response

{
  "data": {
    "brand_id": "brn_xxx",
    "brand_name": "Acme",
    "from": "2026-05-08T00:00:00.000Z",
    "to": "2026-05-14T23:59:59.999Z",
    "visibility_score": 0.42,
    "mention_count": 184,
    "mention_coverage": 0.4031,
    "avg_position": 3.7,
    "sentiment_score": 0.21,
    "trend": {
      "score_change": 0.05,
      "mention_change": 28,
      "position_change": -0.4
    },
    "history": [
      { "date": "2026-05-08", "visibility_score": 0.39, "mention_count": 22 },
      { "date": "2026-05-09", "visibility_score": 0.40, "mention_count": 26 }
    ]
  }
}

The history array is one row per UTC day in the window - feed it straight into a chart library.

Common questions this answers

• "How did our visibility improve in the last week?" → set from to 7 days ago, look at trend.score_change. Positive = up.
• "How many times were we mentioned?" → mention_count for the window.
• "Were we in a worse position recently?" → trend.position_change. Higher is worse for position (bigger number = further down the list).
• "Did sentiment shift?" → compare sentiment_score between two windows.

See also

• Org-wide vitals - the same shape but aggregated across every brand in your org.
• Reference: /api/v1/brands/{id}/stats

Last updated May 14, 2026