Browse all documentation

Brand report

Compare visibility, share of voice, average position and tone for your brand and tracked competitors.

GET/api/v1/brands/{brandId}/reports/brandsread

Call the corresponding get_brand_report MCP tool with JSON arguments. Supply brandId and other path values as named arguments when the endpoint has them.

Request details

Required scope: A valid read or write token. Increase offset by limit for each page while paging.hasMore is true.

Request example
curl --request GET \
  --url "https://searchseal.com/api/v1/brands/b7e4c2a0-5d1f-4c8e-9a3b-2f6d8e1c4a70/reports/brands?dimensions=engine&engines=google_aio" \
  --header "Authorization: Bearer $SEARCHSEAL_TOKEN"

Reports include non-preview answers marked complete under the current collection version. A daily run need not be fully finished.

visibility uses all qualifying answers as its denominator. shareOfVoice uses summed brand-answer counts across tracked brands. averagePosition uses recorded positions 1–10.

Request parameters

NameLocationRequiredTypeDescription
brandIdpathYesuuidAn active brand ID returned by the brand list.
startDatequeryNoYYYY-MM-DDInclusive starting date. Defaults to 27 days before endDate; the window allows 90 days. Search dates follow the source calendar.
endDatequeryNoYYYY-MM-DDInclusive ending date, defaulting to today in the account time zone. A future date returns 400 invalid_request with field code future_date.
enginesqueryNostringEngines to select. Repeat this parameter or comma-separate values: google_aio, chatgpt, gemini, perplexity, grok, claude, deepseek, copilot, google_ai_mode, claude_lite, grok_lite, sakana. Defaults to all engines on your plan.
countryqueryNostringFilter by a supported two-letter country code, such as us, or by global for questions without a country.
questionIdqueryNouuidReturn data for this question only.
dimensionsqueryNostringComma-separated values from engine, country, question, date, week, month. Choose at most one time dimension. Each row represents one entity and dimension combination; question produces a questionId key. Omit for one row per entity.
limitqueryNointegerPage size from 1 to 100; defaults to 50.
offsetqueryNointegerNumber of preceding items to skip; defaults to 0.

Response fields

Response body example
{
  "items": [
    {
      "brand": "Rival Resort",
      "isYou": false,
      "engine": "google_aio",
      "visibility": 0.5809,
      "shareOfVoice": 0.5809,
      "averagePosition": 1.8,
      "mentions": 79,
      "answers": 136,
      "tone": 75
    },
    {
      "brand": "Example Villas",
      "isYou": true,
      "engine": "google_aio",
      "visibility": 0.4191,
      "shareOfVoice": 0.4191,
      "averagePosition": 2.4,
      "mentions": 57,
      "answers": 136,
      "tone": 71
    }
  ],
  "paging": {
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "meta": {
    "generatedAt": "2026-09-26T08:15:02.114Z",
    "timeZone": "Asia/Jakarta",
    "dataThrough": {
      "answers": "2026-09-26",
      "google": "2026-09-23",
      "bing": "2026-09-24"
    }
  }
}
FieldTypeDescription
brandstringSaved name of the brand.
isYoubooleanIdentifies the account’s brand rather than a tracked competitor.
engine, country, …string | nullDimension values for this row’s combination.
visibilitynumberFraction of the group’s answers with a recorded mention of this brand, from 0 to 1.
shareOfVoicenumberBrand-answer count divided by the sum of counts for your brand and tracked rivals, from 0 to 1.
averagePositionnumber | nullMean recorded mention position, restricted to positions 1–10.
mentionsintegerDistinct answers with a recorded mention of this brand.
answersintegerTotal qualifying answers in this dimension group.
toneinteger | nullTone index from 0 to 100; null with fewer than 20 scored mentions.

Successful REST responses from this endpoint include the shown meta fields. Read about data-through dates.

Possible errors

  • 400 invalid_request — An input failed validation. Field details may appear in errors.
  • 400 engine_not_in_plan — A requested engine is unavailable to the account. Remove it from engines.
  • 401 unauthorized — Authentication failed because the token is absent, unrecognized or revoked.
  • 403 forbidden — Account access or token permissions do not allow this request. Check the message for the cause.
  • 404 not_found — The resource is missing or unavailable to this account, including inactive brands.
  • 429 rate_limited — A quota was reached or could not be checked. Wait the Retry-After delay before retrying.
  • 500 server_error — The server failed to complete the operation.

For the shared error format, see status codes, quotas and retries. Next endpoint: Domain report.