Get per-brand ad share
curl --request POST \
--url https://api.mentionlab.io/api/analytics/ads/brands \
--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,
"formats": [
"image_card_v2"
]
}
'import requests
url = "https://api.mentionlab.io/api/analytics/ads/brands"
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,
"formats": ["image_card_v2"]
}
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,
formats: ['image_card_v2']
})
};
fetch('https://api.mentionlab.io/api/analytics/ads/brands', 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/ads/brands",
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,
'formats' => [
'image_card_v2'
]
]),
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/ads/brands"
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 \"formats\": [\n \"image_card_v2\"\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/ads/brands")
.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 \"formats\": [\n \"image_card_v2\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mentionlab.io/api/analytics/ads/brands")
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 \"formats\": [\n \"image_card_v2\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"adRate": 12.34,
"totalResponses": 1500,
"totalAdResponses": 185,
"totalAds": 320,
"totalUnits": 95,
"brands": [
{
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"entityName": "Garmin",
"adCount": 12,
"share": 40,
"responseCount": 9,
"adRate": 4.5,
"avgPosition": 1.4
}
]
}{
"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 - Ads
Get per-brand ad share
Returns each advertised brand’s share of sponsored ad placements (its ad cards over all ad cards in scope), with the ad rate and response totals for the filtered scope; honors the active filters.
POST
/
api
/
analytics
/
ads
/
brands
Get per-brand ad share
curl --request POST \
--url https://api.mentionlab.io/api/analytics/ads/brands \
--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,
"formats": [
"image_card_v2"
]
}
'import requests
url = "https://api.mentionlab.io/api/analytics/ads/brands"
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,
"formats": ["image_card_v2"]
}
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,
formats: ['image_card_v2']
})
};
fetch('https://api.mentionlab.io/api/analytics/ads/brands', 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/ads/brands",
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,
'formats' => [
'image_card_v2'
]
]),
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/ads/brands"
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 \"formats\": [\n \"image_card_v2\"\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/ads/brands")
.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 \"formats\": [\n \"image_card_v2\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mentionlab.io/api/analytics/ads/brands")
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 \"formats\": [\n \"image_card_v2\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"adRate": 12.34,
"totalResponses": 1500,
"totalAdResponses": 185,
"totalAds": 320,
"totalUnits": 95,
"brands": [
{
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"entityName": "Garmin",
"adCount": 12,
"share": 40,
"responseCount": 9,
"adRate": 4.5,
"avgPosition": 1.4
}
]
}{
"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: "and" matches ALL tags (default, the dashboard's), "or" matches ANY tag.
Available options:
and, or Execution tag matching mode: "and" matches ALL tags (default, the dashboard's), "or" matches ANY tag.
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 ad placements by card format (provider-defined open set, e.g. 'product_card_v2', 'image_card_v2'). Scopes totalAds and the brand rows only; adRate and the response totals remain format-agnostic.
Example:
["image_card_v2"]
Response
Percentage of AI responses that rendered at least one sponsored ad card, out of total responses in the filtered scope. Formula: (totalAdResponses / totalResponses) × 100. 0 when there are no responses. Identical definition to the overview adsRate.
Example:
12.34
Total number of AI responses in the filtered scope.
Example:
1500
AI responses in the filtered scope that rendered at least one ad card.
Example:
185
Total ad cards (placements) in the filtered scope — a 5-card carousel weighs 5.
Example:
320
Total ad units summed over ALL groups including the unattributed one — the denominator for each brand share. A unit carrying more than one brand counts once per brand.
Example:
95
Per-brand ad share, one row per canonical entity, sorted by share descending.
Show child attributes
Show child attributes