---
title: "Brand leaderboard for an industry"
method: GET
path: "/org/industries/{id}/brands"
tags: ["Industries"]
---

# Brand leaderboard for an industry

`GET /org/industries/{id}/brands`

## Request

- Base URL: `https://apiv2.senso.ai/api/v1`
- URL: `https://apiv2.senso.ai/api/v1/org/industries/{id}/brands`
- Auth: API key in header `X-API-Key`

Returns the brands the AI answers named in this industry over a date window, ranked by how many answers mentioned each one, with mention totals, average position, sentiment counts, the most-cited domain, and trends against the previous window of the same length. Figures are counts rather than rates so you can compute shares against `totals` yourself. Ranks and trends are computed over the whole leaderboard before paging, so a later page still shows global ranks. You can read any industry in the public catalogue (`GET /org/industries`) and your organization's own industry; any other id is a `404`. Requires the GEO product.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `from` string, date
- `to` string, date
- `models` string
- `location` string
- `limit` integer
- `offset` integer
- `canonicalize` boolean
- `rollup` string
- `entity_type` string

## Response `200`

One page of the industry's brand leaderboard.

- IndustryBrandLeaderboardResponse: One page of an industry's brand leaderboard.
  - `window` IndustryWindow, required: The date window that was applied.
    - `from` string, required: Start of the window, `YYYY-MM-DD`.
    - `to` string, required: End of the window, `YYYY-MM-DD`.
  - `totals` IndustryTotals, required: Industry-wide denominators for the window, so shares can be computed.
    - `run_count` integer, required: Prompt runs collected in the window.
    - `answered_count` integer, required: Runs that produced an answer.
    - `brand_mention_total` integer, required: Mention instances across every brand — the share-of-voice denominator.
  - `total` integer, required: Brands in the window after any `entity_type` filter, before paging. Ranks and trends are computed over the full landscape.
  - `limit` integer, required: The page size that was applied.
  - `offset` integer, required: The offset that was applied.
  - `brands` IndustryBrandLeaderboardRow[], required: The brands on this page, in rank order.
    - `brand_id` string, uuid, nullable, required: The brand's stable, global identifier — the same for this brand in every industry and endpoint, and the value to store. Null when the brand has not been registered yet.
    - `parent_brand_id` string, uuid: Present when the brand is a sub-brand of a company; the row still reports the sub-brand's own numbers (pass `rollup=parent` to fold them). Absent for brands that own themselves and from rolled-up responses.
    - `brand_key` string, required: A display and merge key that curation may change. Do not store it as an identifier.
    - `brand_name` string, required
    - `mentions_count` integer, required: Answers that named the brand at least once.
    - `mention_total` integer, required: Mention instances — an answer naming the brand three times counts three.
    - `answered_count` integer, required: Answers in the window the brand could have appeared in.
    - `mentions_rank` integer, required: Position in the full landscape by `mentions_count`; 1 is the most mentioned. Not renumbered by an `entity_type` filter.
    - `average_position` number, required: Average position of the brand within the answers that named it; lower is earlier.
    - `sentiment` BrandSentimentCounts, required: How the answers that named the brand spoke of it.
      - `positive` integer, required
      - `neutral` integer, required
      - `negative` integer, required
    - `top_cited_domain` string, required: The domain cited most often in answers that named the brand. Empty when none.
    - `entity_type` string: What kind of entity the row is — `brand`, `regulator`, `publisher`, `government`, `generic_term`, `product_model`, or `forum_social`. Omitted when unclassified, which counts as `brand`.
    - `surface_forms` string[]: The spelling variants merged into this row. Present only in canonicalized responses.
    - `model_data` IndustryBrandModelMentions[], nullable, required: The brand's mentions broken down by AI model.
      - `model` string, required
      - `mentions_count` integer, required: Answers from this model that named the brand.
      - `answered_count` integer, required: Answers from this model in the window.
    - `mentions_rank_trend` integer, nullable, required: Previous rank minus current rank against the preceding window of the same length; positive means the brand climbed. Null when the brand had no rows in the previous window.
    - `mentions_count_trend` integer, nullable, required: Current `mentions_count` minus the previous window's. Null when there is nothing to compare against.
    - `mentions_percent_trend` number, nullable, required: Change in mention rate (mentions over answered) in percentage points. Null when there is nothing to compare against.

## 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.
- `404`: The requested resource does not exist or is not visible to this key.

---

[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)