--- title: "Visibility time series" method: GET path: "/org/analytics/mentions" tags: ["Analytics"] --- # Visibility time series `GET /org/analytics/mentions` ## Request - Base URL: `https://apiv2.senso.ai/api/v1` - URL: `https://apiv2.senso.ai/api/v1/org/analytics/mentions` - Auth: API key in header `X-API-Key` Mention volume, Share of Voice, average rank, and sentiment over the window, bucketed by day or week, with the window totals alongside. Requires the GEO product. ## Query parameters - `from` string, date - `to` string, date - `models` string - `location` string - `prompt_type` 'awareness' | 'consideration' | 'evaluation' | 'decision' - `tag` string - `group_by` 'day' | 'week' ## Response `200` The visibility series with window totals. - OrgMentionsResponse: The visibility time series with window totals. - `window` AnalyticsWindow, required: The effective window every number in the payload was computed over. - `from` string, date, required: First day in the window (inclusive). - `to` string, date, required: Last day in the window (inclusive). - `days` integer, required: Number of days spanned, inclusive. - `latest_data_day` string, date, nullable, required: Most recent day with data for the active model/location filter, or null if none. - `group_by` string, required: The bucket the series is grouped by — `day` or `week`, echoing the request. - `totals` AnalyticsTotals, required: The additive count block — every numerator and denominator behind the metrics, summed over the window and filter. All are additive, so they can be recombined across windows; ratios cannot. - `run_count` integer, required: Prompt-run answers attempted. - `answered_count` integer, required: Non-empty answers — the mention-rate denominator. - `mentioned_count` integer, required: Answers naming the org (mention-rate numerator). - `mention_total` integer, required: Mention instances for the org (Share of Voice numerator). - `tracked_mention_total` integer, required: Mention instances over {org + tracked competitors}. NOT the Share of Voice denominator. - `brand_mention_total` integer, required: Mention instances over ALL brands — the Share of Voice denominator. - `rank_sum` integer, required: Σ ordinal position over mentioned answers (avg-rank numerator). - `sentiment` SentimentCounts, required: The mention-sentiment split. positive + neutral + negative = mentioned_count. - `positive` integer, required - `neutral` integer, required - `negative` integer, required - `cited_run_count` integer, required: Answers with ≥1 citation of any tier — this is D, the Citation Rate and Coverage denominator. - `primary_cited_run_count` integer, required: Answers citing an owned domain. - `tracked_cited_run_count` integer, required: Answers citing a tracked source. - `external_cited_run_count` integer, required: Answers citing a third-party domain. - `cited_total` integer, required: Total citation instances, all tiers — this is S, the Citation Share denominator. - `primary_cited_total` integer, required: Citation instances pointing at an owned domain. - `tracked_cited_total` integer, required: Citation instances pointing at a tracked source. - `external_cited_total` integer, required: Citation instances pointing at a third-party domain. - `prompt_count` integer, required: Distinct prompts contributing to the window. - `model_count` integer, required: Distinct models contributing to the window. - `location_count` integer, required: Distinct locations contributing to the window. - `metrics` AnalyticsMetrics, required: Every ratio derivable from the totals. Each is null when its denominator is zero. Tier RATES divide by D and are independent (can sum past 100%); tier SHARES divide by S and partition (sum to exactly 100%). - `mention_rate` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `share_of_voice` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `avg_rank` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `primary_citation_rate` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `tracked_citation_rate` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `external_citation_rate` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `primary_citation_share` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `tracked_citation_share` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `external_citation_share` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `citations_per_answer` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `series` MentionSeriesPoint[], required: One entry per bucket, oldest first. Buckets are grouped from the days that have stored data, so a day (or week) with no data is **absent** from the series rather than present with zeros — never read a gap as a zero. The window `totals` are computed independently of the series, so they still cover the whole window. - `period_start` string, date, required: First day of the bucket (day or ISO week). - `run_count` integer, required: Prompt-run answers attempted in this bucket. - `answered_count` integer, required: Non-empty answers in this bucket — the `mention_rate` denominator for this bucket. - `mentioned_count` integer, required: Answers in this bucket that named your brand. - `mention_total` integer, required: Mention instances for your brand in this bucket. - `tracked_mention_total` integer, required: Mention instances across you plus tracked competitors in this bucket. A raw count for your own math — not this bucket's `share_of_voice` denominator. - `brand_mention_total` integer, required: Mention instances across all brands — this bucket's `share_of_voice` denominator. - `rank_sum` integer, required: Sum of your ordinal positions over the answers in this bucket that mentioned you. - `sentiment` SentimentCounts, required: The mention-sentiment split. positive + neutral + negative = mentioned_count. - `positive` integer, required - `neutral` integer, required - `negative` integer, required - `mention_rate` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `share_of_voice` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `avg_rank` MetricValue, nullable, required: A ratio, shipped as an unrounded fraction plus a ready-to-quote string. Use `value` for math and `display` verbatim for anything a human reads — it is why `0.012` never reaches a slide as "0.012%". `value` is a 0–1 fraction for rates and shares, an average position for ranks, and an intensity for frequencies. Wherever a field of this shape is nullable, `null` means the metric's denominator was zero, so the metric was **not measured** in this window; it never means the metric was measured as zero. - `value` number, required: The raw number for math — a 0–1 fraction for rates/shares, an average position for ranks, an intensity for frequencies. - `display` string, required: The presentation string, safe to quote verbatim (e.g. "2.6%", "#1.4", "4.20 citations per cited answer"). - `data_quality` DataQuality, required: Deterministic sample-quality flag driven by the answered-run count. - `level` 'high' | 'medium' | 'low', required: low (<100 answered runs), medium (<400), high otherwise. - `answered_count` integer, required: The answered-run count the flag was derived from. - `reasons` string[], required: Human-readable caveats when confidence is below high; empty otherwise. - `notes` string[], required - `definitions` object, required: One-line definition of each metric in the payload, keyed by metric name. ## Other responses - `400`: The request was malformed — a bad path/query parameter or an invalid value. - `401`: Missing or invalid credentials — supply a valid org API key in the `X-API-Key` header. - `403`: The API key is authenticated but not permitted to access this resource. --- [API](https://skmtc.dev/senso/apis/senso-org-api.md) - [All operations](https://skmtc.dev/senso/apis/senso-org-api/llms.txt) - [OpenAPI document](https://skmtc.dev/senso/apis/senso-org-api/revisions/d789b4fcbe84?raw)