Get brand share of voice
curl --request POST \
--url https://api.mentionlab.io/api/analytics/visibility/share-of-voice \
--header 'Content-Type: application/json' \
--header 'x-project-id: <x-project-id>' \
--data '
{
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"countries": [
"BE",
"FR"
],
"languages": [
"en",
"fr"
],
"models": [
"gpt-4o",
"claude-3-5-sonnet"
],
"queryIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"queryTagIds": [
"42"
],
"execTagIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"queryTagGroupIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"execTagGroupIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"queryTypes": [],
"timezone": "UTC",
"groupByEntityGroup": false,
"showAllEntities": false,
"entityTypes": [
"owned",
"primary",
"competitor"
]
}
'import requests
url = "https://api.mentionlab.io/api/analytics/visibility/share-of-voice"
payload = {
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"countries": ["BE", "FR"],
"languages": ["en", "fr"],
"models": ["gpt-4o", "claude-3-5-sonnet"],
"queryIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"queryTagIds": ["42"],
"execTagIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"queryTagGroupIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"execTagGroupIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"queryTypes": [],
"timezone": "UTC",
"groupByEntityGroup": False,
"showAllEntities": False,
"entityTypes": ["owned", "primary", "competitor"]
}
headers = {
"x-project-id": "<x-project-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-project-id': '<x-project-id>', 'Content-Type': 'application/json'},
body: JSON.stringify({
startDate: '2025-01-01',
endDate: '2025-01-31',
countries: ['BE', 'FR'],
languages: ['en', 'fr'],
models: ['gpt-4o', 'claude-3-5-sonnet'],
queryIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
queryTagIds: ['42'],
execTagIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
queryTagGroupIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
execTagGroupIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
queryTypes: [],
timezone: 'UTC',
groupByEntityGroup: false,
showAllEntities: false,
entityTypes: ['owned', 'primary', 'competitor']
})
};
fetch('https://api.mentionlab.io/api/analytics/visibility/share-of-voice', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mentionlab.io/api/analytics/visibility/share-of-voice",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'startDate' => '2025-01-01',
'endDate' => '2025-01-31',
'countries' => [
'BE',
'FR'
],
'languages' => [
'en',
'fr'
],
'models' => [
'gpt-4o',
'claude-3-5-sonnet'
],
'queryIds' => [
'3fa85f64-5717-4562-b3fc-2c963f66afa6'
],
'queryTagIds' => [
'42'
],
'execTagIds' => [
'3fa85f64-5717-4562-b3fc-2c963f66afa6'
],
'queryTagGroupIds' => [
'3fa85f64-5717-4562-b3fc-2c963f66afa6'
],
'execTagGroupIds' => [
'3fa85f64-5717-4562-b3fc-2c963f66afa6'
],
'queryTypes' => [
],
'timezone' => 'UTC',
'groupByEntityGroup' => false,
'showAllEntities' => false,
'entityTypes' => [
'owned',
'primary',
'competitor'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-project-id: <x-project-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mentionlab.io/api/analytics/visibility/share-of-voice"
payload := strings.NewReader("{\n \"startDate\": \"2025-01-01\",\n \"endDate\": \"2025-01-31\",\n \"countries\": [\n \"BE\",\n \"FR\"\n ],\n \"languages\": [\n \"en\",\n \"fr\"\n ],\n \"models\": [\n \"gpt-4o\",\n \"claude-3-5-sonnet\"\n ],\n \"queryIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagIds\": [\n \"42\"\n ],\n \"execTagIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"execTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTypes\": [],\n \"timezone\": \"UTC\",\n \"groupByEntityGroup\": false,\n \"showAllEntities\": false,\n \"entityTypes\": [\n \"owned\",\n \"primary\",\n \"competitor\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-project-id", "<x-project-id>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mentionlab.io/api/analytics/visibility/share-of-voice")
.header("x-project-id", "<x-project-id>")
.header("Content-Type", "application/json")
.body("{\n \"startDate\": \"2025-01-01\",\n \"endDate\": \"2025-01-31\",\n \"countries\": [\n \"BE\",\n \"FR\"\n ],\n \"languages\": [\n \"en\",\n \"fr\"\n ],\n \"models\": [\n \"gpt-4o\",\n \"claude-3-5-sonnet\"\n ],\n \"queryIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagIds\": [\n \"42\"\n ],\n \"execTagIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"execTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTypes\": [],\n \"timezone\": \"UTC\",\n \"groupByEntityGroup\": false,\n \"showAllEntities\": false,\n \"entityTypes\": [\n \"owned\",\n \"primary\",\n \"competitor\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mentionlab.io/api/analytics/visibility/share-of-voice")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-project-id"] = '<x-project-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"startDate\": \"2025-01-01\",\n \"endDate\": \"2025-01-31\",\n \"countries\": [\n \"BE\",\n \"FR\"\n ],\n \"languages\": [\n \"en\",\n \"fr\"\n ],\n \"models\": [\n \"gpt-4o\",\n \"claude-3-5-sonnet\"\n ],\n \"queryIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagIds\": [\n \"42\"\n ],\n \"execTagIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"execTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTypes\": [],\n \"timezone\": \"UTC\",\n \"groupByEntityGroup\": false,\n \"showAllEntities\": false,\n \"entityTypes\": [\n \"owned\",\n \"primary\",\n \"competitor\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"totalMentions": 150,
"brands": [
{
"displayKey": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "Acme Corp",
"isOwned": true,
"isPrimary": true,
"mentionCount": 42,
"shareOfVoice": 28
}
]
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}Analytics - Visibility
Get brand share of voice
Returns each entity’s share of voice (its percentage of total brand mentions) over the selected date range, sorted by mention count descending, for comparing against competitors.
POST
/
api
/
analytics
/
visibility
/
share-of-voice
Get brand share of voice
curl --request POST \
--url https://api.mentionlab.io/api/analytics/visibility/share-of-voice \
--header 'Content-Type: application/json' \
--header 'x-project-id: <x-project-id>' \
--data '
{
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"countries": [
"BE",
"FR"
],
"languages": [
"en",
"fr"
],
"models": [
"gpt-4o",
"claude-3-5-sonnet"
],
"queryIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"queryTagIds": [
"42"
],
"execTagIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"queryTagGroupIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"execTagGroupIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6"
],
"queryTypes": [],
"timezone": "UTC",
"groupByEntityGroup": false,
"showAllEntities": false,
"entityTypes": [
"owned",
"primary",
"competitor"
]
}
'import requests
url = "https://api.mentionlab.io/api/analytics/visibility/share-of-voice"
payload = {
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"countries": ["BE", "FR"],
"languages": ["en", "fr"],
"models": ["gpt-4o", "claude-3-5-sonnet"],
"queryIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"queryTagIds": ["42"],
"execTagIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"queryTagGroupIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"execTagGroupIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"],
"queryTypes": [],
"timezone": "UTC",
"groupByEntityGroup": False,
"showAllEntities": False,
"entityTypes": ["owned", "primary", "competitor"]
}
headers = {
"x-project-id": "<x-project-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-project-id': '<x-project-id>', 'Content-Type': 'application/json'},
body: JSON.stringify({
startDate: '2025-01-01',
endDate: '2025-01-31',
countries: ['BE', 'FR'],
languages: ['en', 'fr'],
models: ['gpt-4o', 'claude-3-5-sonnet'],
queryIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
queryTagIds: ['42'],
execTagIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
queryTagGroupIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
execTagGroupIds: ['3fa85f64-5717-4562-b3fc-2c963f66afa6'],
queryTypes: [],
timezone: 'UTC',
groupByEntityGroup: false,
showAllEntities: false,
entityTypes: ['owned', 'primary', 'competitor']
})
};
fetch('https://api.mentionlab.io/api/analytics/visibility/share-of-voice', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mentionlab.io/api/analytics/visibility/share-of-voice",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'startDate' => '2025-01-01',
'endDate' => '2025-01-31',
'countries' => [
'BE',
'FR'
],
'languages' => [
'en',
'fr'
],
'models' => [
'gpt-4o',
'claude-3-5-sonnet'
],
'queryIds' => [
'3fa85f64-5717-4562-b3fc-2c963f66afa6'
],
'queryTagIds' => [
'42'
],
'execTagIds' => [
'3fa85f64-5717-4562-b3fc-2c963f66afa6'
],
'queryTagGroupIds' => [
'3fa85f64-5717-4562-b3fc-2c963f66afa6'
],
'execTagGroupIds' => [
'3fa85f64-5717-4562-b3fc-2c963f66afa6'
],
'queryTypes' => [
],
'timezone' => 'UTC',
'groupByEntityGroup' => false,
'showAllEntities' => false,
'entityTypes' => [
'owned',
'primary',
'competitor'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-project-id: <x-project-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mentionlab.io/api/analytics/visibility/share-of-voice"
payload := strings.NewReader("{\n \"startDate\": \"2025-01-01\",\n \"endDate\": \"2025-01-31\",\n \"countries\": [\n \"BE\",\n \"FR\"\n ],\n \"languages\": [\n \"en\",\n \"fr\"\n ],\n \"models\": [\n \"gpt-4o\",\n \"claude-3-5-sonnet\"\n ],\n \"queryIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagIds\": [\n \"42\"\n ],\n \"execTagIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"execTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTypes\": [],\n \"timezone\": \"UTC\",\n \"groupByEntityGroup\": false,\n \"showAllEntities\": false,\n \"entityTypes\": [\n \"owned\",\n \"primary\",\n \"competitor\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-project-id", "<x-project-id>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mentionlab.io/api/analytics/visibility/share-of-voice")
.header("x-project-id", "<x-project-id>")
.header("Content-Type", "application/json")
.body("{\n \"startDate\": \"2025-01-01\",\n \"endDate\": \"2025-01-31\",\n \"countries\": [\n \"BE\",\n \"FR\"\n ],\n \"languages\": [\n \"en\",\n \"fr\"\n ],\n \"models\": [\n \"gpt-4o\",\n \"claude-3-5-sonnet\"\n ],\n \"queryIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagIds\": [\n \"42\"\n ],\n \"execTagIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"execTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTypes\": [],\n \"timezone\": \"UTC\",\n \"groupByEntityGroup\": false,\n \"showAllEntities\": false,\n \"entityTypes\": [\n \"owned\",\n \"primary\",\n \"competitor\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mentionlab.io/api/analytics/visibility/share-of-voice")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-project-id"] = '<x-project-id>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"startDate\": \"2025-01-01\",\n \"endDate\": \"2025-01-31\",\n \"countries\": [\n \"BE\",\n \"FR\"\n ],\n \"languages\": [\n \"en\",\n \"fr\"\n ],\n \"models\": [\n \"gpt-4o\",\n \"claude-3-5-sonnet\"\n ],\n \"queryIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagIds\": [\n \"42\"\n ],\n \"execTagIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"execTagGroupIds\": [\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"\n ],\n \"queryTypes\": [],\n \"timezone\": \"UTC\",\n \"groupByEntityGroup\": false,\n \"showAllEntities\": false,\n \"entityTypes\": [\n \"owned\",\n \"primary\",\n \"competitor\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"totalMentions": 150,
"brands": [
{
"displayKey": "550e8400-e29b-41d4-a716-446655440000",
"displayName": "Acme Corp",
"isOwned": true,
"isPrimary": true,
"mentionCount": 42,
"shareOfVoice": 28
}
]
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}{
"statusCode": 400,
"message": "Validation failed",
"error": "Bad Request"
}Headers
Project ID to specify the project context
Body
application/json
Start date (inclusive)
Example:
"2025-01-01"
End date (inclusive)
Example:
"2025-01-31"
Filter by country codes
Example:
["BE", "FR"]
Filter by language codes
Example:
["en", "fr"]
Filter by AI models
Example:
["gpt-4o", "claude-3-5-sonnet"]
Filter by query IDs
Example:
["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
Filter by source presence: "sources" (only with sources), "no_sources" (only without), "all" (no filter). Legacy true/false values are still accepted.
Available options:
all, sources, no_sources Filter by shopping presence: "shopping" (only with shopping), "no_shopping" (only without), "all" (no filter). Legacy true/false values are still accepted.
Available options:
all, shopping, no_shopping Filter by sponsored-ad presence: "ads" (only with ads), "no_ads" (only without), "all" (no filter). Legacy true/false values are still accepted.
Available options:
all, ads, no_ads Filter by query tag IDs (numeric — bigint column)
Example:
["42"]
Filter by execution tag IDs
Example:
["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
Filter by query tag group IDs — matches rows carrying any tag filed under a selected group. Combines with queryTagIds per queryTagMode.
Example:
["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
Filter by execution tag group IDs — matches rows carrying any tag filed under a selected group. Combines with execTagIds per execTagMode.
Example:
["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
Filter by query type. Include "untyped" to also match queries without a type. Results from since-deleted queries are excluded when this filter is set.
Available options:
comparative, informative, perception, untyped Query tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags.
Available options:
and, or Execution tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags.
Available options:
and, or Deprecated and ignored. Date bounds and buckets are always UTC. Accepted for backward compatibility only.
Example:
"UTC"
Row grouping level for entity results. "none" = one row per entity, "division" = one row per division (entities not in a division get their own row), "group" = one row per top-level group (divisions roll up into their group). Defaults to "none".
Available options:
none, division, group Deprecated — use groupBy instead. true is equivalent to groupBy="group".
Example:
false
Include entities that have only ever been seen in a single AI response. These are mostly one-off extraction noise and are hidden by default.
Example:
false
Filter which entity types to include in results. Accepted values: "owned", "primary", "competitor". Defaults to all types when omitted.
Available options:
owned, primary, competitor Example:
["owned", "primary", "competitor"]
Response
Sum of mentionCount across all non-blacklisted canonical entities (denominator for shareOfVoice). Because one AI response can mention multiple entities, this may exceed the total number of AI responses.
Example:
150
Per-entity share of voice, sorted by mentionCount descending. Includes all non-blacklisted canonical entities for the project.
Show child attributes
Show child attributes