Brand report
Compare visibility, share of voice, average position and tone for your brand and tracked competitors.
/api/v1/brands/{brandId}/reports/brandsreadCall 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.
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
| Name | Location | Required | Type | Description |
|---|---|---|---|---|
brandId | path | Yes | uuid | An active brand ID returned by the brand list. |
startDate | query | No | YYYY-MM-DD | Inclusive starting date. Defaults to 27 days before endDate; the window allows 90 days. Search dates follow the source calendar. |
endDate | query | No | YYYY-MM-DD | Inclusive ending date, defaulting to today in the account time zone. A future date returns 400 invalid_request with field code future_date. |
engines | query | No | string | Engines 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. |
country | query | No | string | Filter by a supported two-letter country code, such as us, or by global for questions without a country. |
questionId | query | No | uuid | Return data for this question only. |
dimensions | query | No | string | Comma-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. |
limit | query | No | integer | Page size from 1 to 100; defaults to 50. |
offset | query | No | integer | Number of preceding items to skip; defaults to 0. |
Response fields
{
"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"
}
}
}| Field | Type | Description |
|---|---|---|
brand | string | Saved name of the brand. |
isYou | boolean | Identifies the account’s brand rather than a tracked competitor. |
engine, country, … | string | null | Dimension values for this row’s combination. |
visibility | number | Fraction of the group’s answers with a recorded mention of this brand, from 0 to 1. |
shareOfVoice | number | Brand-answer count divided by the sum of counts for your brand and tracked rivals, from 0 to 1. |
averagePosition | number | null | Mean recorded mention position, restricted to positions 1–10. |
mentions | integer | Distinct answers with a recorded mention of this brand. |
answers | integer | Total qualifying answers in this dimension group. |
tone | integer | null | Tone 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 inerrors.400 engine_not_in_plan— A requested engine is unavailable to the account. Remove it fromengines.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 theRetry-Afterdelay 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.