---
title: "Look up a brand in an industry by name"
method: GET
path: "/org/industries/{id}/brands/{brand}"
tags: ["Industries"]
---

# Look up a brand in an industry by name

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

## Request

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

Everything about one brand in the industry over the window, found by fuzzy name match and merged across spelling variants: mention rate, share of voice, average position, rank, sentiment, the most-cited domain, and a per-model breakdown. A brand the answers never named returns `200` with `mentioned` false and null `metrics`, not a `404`. A name never seen before is registered, so the response always carries a stable `brand_id`; use `GET /org/industries/{id}/brands-by-id/{brand_id}` for repeat calls. Reads are limited to the public catalogue and your organization's own industry. Requires the GEO product.

## Path parameters

- `id` string, uuid, required
- `brand` string, required

## Query parameters

- `from` string, date
- `to` string, date
- `models` string
- `location` string

## Response `200`

The brand's standing in the industry over the window.

- IndustryBrandDetailResponse: Everything about one brand in an industry over the window.
  - `resolved` IndustryBrandResolved, required: The brand the query was matched to.
    - `brand_id` string, uuid, nullable, required: The brand's stable, global identifier — the value to store. Null only when the brand could not be resolved or registered.
    - `brand_key` string, required: A display and merge key that curation may change. Do not store it as an identifier.
    - `brand_name` string, required
    - `entity_type` string, required: What kind of entity the brand is, e.g. `brand` or `regulator`.
    - `matched_on` string, required: How the query was matched to the brand — `contains`, `exact`, `none`, `variation`. `exact` when addressed by id.
    - `match_confidence` number, required: Confidence in the match, 0–1.
    - `surface_forms` string[], nullable, required: The spelling variants merged into this brand.
  - `window` IndustryAnalyticsWindow, 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`.
    - `days` integer, required: Length of the window in days.
    - `effective_weeks` string[]: The weeks of data the window actually covered, when known.
    - `collection_runs` integer: Prompt runs collected in the window, when known.
  - `mentioned` boolean, required: Whether any answer in the window named the brand.
  - `metrics` IndustryBrandDetailMetrics, nullable, required: The brand's metrics over the window. Null when the brand was never mentioned.
    - `mention_rate` IndustryRate, required: A rate with a ready-to-display rendering.
      - `value` number, required: The rate as a number.
      - `display` string, required: The rate formatted for display.
    - `share_of_voice` IndustryRate, required: A rate with a ready-to-display rendering.
      - `value` number, required: The rate as a number.
      - `display` string, required: The rate formatted for display.
    - `avg_position` number, required: Average position of the brand within the answers that named it; lower is earlier.
    - `rank_in_industry` integer, required: The brand's position on the industry leaderboard.
    - `brands_ranked` integer, required: How many brands the leaderboard ranked.
    - `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.
    - `owned_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").
  - `by_model` IndustryBrandModelRate[], required: The brand's mention rate per AI model. Empty when the brand was never mentioned.
    - `model` string, required
    - `mention_rate` IndustryRate, required: A rate with a ready-to-display rendering.
      - `value` number, required: The rate as a number.
      - `display` string, required: The rate formatted for display.
  - `by_stage` IndustryBrandStageRate[], nullable, required: The brand's mention rate per funnel stage of the prompts. Null when no stage data exists for the window.
    - `funnel_stage` string, required: The prompts' funnel stage, e.g. `awareness` or `consideration`.
    - `mention_rate` IndustryRate, required: A rate with a ready-to-display rendering.
      - `value` number, required: The rate as a number.
      - `display` string, required: The rate formatted for display.
    - `answered_count` integer, required: Answers to prompts in this stage over the window.
  - `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: Caveats about this result. Empty when there are none.
  - `definitions` object, required: A plain-language definition of each metric, keyed by field 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.
- `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)