Get per-tag stats with project brand metrics

curl --request POST \
  --url https://api.mentionlab.io/api/analytics/tags/stats \
  --header 'Content-Type: application/json' \
  --header 'x-project-id: <x-project-id>' \
  --data '
{
  "tagType": "query",
  "startDate": "2025-01-01",
  "endDate": "2025-02-01",
  "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": [],
  "queryTagMode": "or",
  "execTagMode": "or",
  "timezone": "Europe/Brussels",
  "groupByEntityGroup": false,
  "showAllEntities": false,
  "entityIds": [
    "3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90"
  ],
  "tagIds": [
    "tag_123",
    "tag_456"
  ],
  "groupIds": [
    "018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"
  ],
  "limit": 5,
  "sort": [
    {
      "field": "mentionCount",
      "direction": "DESC"
    }
  ]
}
'

import requests

url = "https://api.mentionlab.io/api/analytics/tags/stats"

payload = {
    "tagType": "query",
    "startDate": "2025-01-01",
    "endDate": "2025-02-01",
    "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": [],
    "queryTagMode": "or",
    "execTagMode": "or",
    "timezone": "Europe/Brussels",
    "groupByEntityGroup": False,
    "showAllEntities": False,
    "entityIds": ["3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90"],
    "tagIds": ["tag_123", "tag_456"],
    "groupIds": ["018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"],
    "limit": 5,
    "sort": [
        {
            "field": "mentionCount",
            "direction": "DESC"
        }
    ]
}
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({
    tagType: 'query',
    startDate: '2025-01-01',
    endDate: '2025-02-01',
    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: [],
    queryTagMode: 'or',
    execTagMode: 'or',
    timezone: 'Europe/Brussels',
    groupByEntityGroup: false,
    showAllEntities: false,
    entityIds: ['3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90'],
    tagIds: ['tag_123', 'tag_456'],
    groupIds: ['018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42'],
    limit: 5,
    sort: [{field: 'mentionCount', direction: 'DESC'}]
  })
};

fetch('https://api.mentionlab.io/api/analytics/tags/stats', 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/tags/stats",
  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([
    'tagType' => 'query',
    'startDate' => '2025-01-01',
    'endDate' => '2025-02-01',
    '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' => [
        
    ],
    'queryTagMode' => 'or',
    'execTagMode' => 'or',
    'timezone' => 'Europe/Brussels',
    'groupByEntityGroup' => false,
    'showAllEntities' => false,
    'entityIds' => [
        '3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90'
    ],
    'tagIds' => [
        'tag_123',
        'tag_456'
    ],
    'groupIds' => [
        '018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42'
    ],
    'limit' => 5,
    'sort' => [
        [
                'field' => 'mentionCount',
                'direction' => 'DESC'
        ]
    ]
  ]),
  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/tags/stats"

	payload := strings.NewReader("{\n  \"tagType\": \"query\",\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\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  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"entityIds\": [\n    \"3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90\"\n  ],\n  \"tagIds\": [\n    \"tag_123\",\n    \"tag_456\"\n  ],\n  \"groupIds\": [\n    \"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42\"\n  ],\n  \"limit\": 5,\n  \"sort\": [\n    {\n      \"field\": \"mentionCount\",\n      \"direction\": \"DESC\"\n    }\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/tags/stats")
  .header("x-project-id", "<x-project-id>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tagType\": \"query\",\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\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  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"entityIds\": [\n    \"3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90\"\n  ],\n  \"tagIds\": [\n    \"tag_123\",\n    \"tag_456\"\n  ],\n  \"groupIds\": [\n    \"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42\"\n  ],\n  \"limit\": 5,\n  \"sort\": [\n    {\n      \"field\": \"mentionCount\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mentionlab.io/api/analytics/tags/stats")

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  \"tagType\": \"query\",\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\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  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"entityIds\": [\n    \"3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90\"\n  ],\n  \"tagIds\": [\n    \"tag_123\",\n    \"tag_456\"\n  ],\n  \"groupIds\": [\n    \"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42\"\n  ],\n  \"limit\": 5,\n  \"sort\": [\n    {\n      \"field\": \"mentionCount\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "tags": [
    {
      "tagId": "550e8400-e29b-41d4-a716-446655440000",
      "tagName": "Pricing",
      "tagColor": "#4f46e5",
      "resultCount": 340,
      "projectBrand": {
        "mentionCount": 80,
        "visibility": 40,
        "avgRanking": 2.5,
        "sentimentScore": 72.3,
        "shareOfVoice": 32.1,
        "sentimentPositive": 52,
        "sentimentNeutral": 18,
        "sentimentNegative": 10
      }
    }
  ]
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

POST

api

analytics

tags

stats

Get per-tag stats with project brand metrics

curl --request POST \
  --url https://api.mentionlab.io/api/analytics/tags/stats \
  --header 'Content-Type: application/json' \
  --header 'x-project-id: <x-project-id>' \
  --data '
{
  "tagType": "query",
  "startDate": "2025-01-01",
  "endDate": "2025-02-01",
  "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": [],
  "queryTagMode": "or",
  "execTagMode": "or",
  "timezone": "Europe/Brussels",
  "groupByEntityGroup": false,
  "showAllEntities": false,
  "entityIds": [
    "3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90"
  ],
  "tagIds": [
    "tag_123",
    "tag_456"
  ],
  "groupIds": [
    "018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"
  ],
  "limit": 5,
  "sort": [
    {
      "field": "mentionCount",
      "direction": "DESC"
    }
  ]
}
'

import requests

url = "https://api.mentionlab.io/api/analytics/tags/stats"

payload = {
    "tagType": "query",
    "startDate": "2025-01-01",
    "endDate": "2025-02-01",
    "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": [],
    "queryTagMode": "or",
    "execTagMode": "or",
    "timezone": "Europe/Brussels",
    "groupByEntityGroup": False,
    "showAllEntities": False,
    "entityIds": ["3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90"],
    "tagIds": ["tag_123", "tag_456"],
    "groupIds": ["018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"],
    "limit": 5,
    "sort": [
        {
            "field": "mentionCount",
            "direction": "DESC"
        }
    ]
}
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({
    tagType: 'query',
    startDate: '2025-01-01',
    endDate: '2025-02-01',
    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: [],
    queryTagMode: 'or',
    execTagMode: 'or',
    timezone: 'Europe/Brussels',
    groupByEntityGroup: false,
    showAllEntities: false,
    entityIds: ['3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90'],
    tagIds: ['tag_123', 'tag_456'],
    groupIds: ['018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42'],
    limit: 5,
    sort: [{field: 'mentionCount', direction: 'DESC'}]
  })
};

fetch('https://api.mentionlab.io/api/analytics/tags/stats', 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/tags/stats",
  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([
    'tagType' => 'query',
    'startDate' => '2025-01-01',
    'endDate' => '2025-02-01',
    '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' => [
        
    ],
    'queryTagMode' => 'or',
    'execTagMode' => 'or',
    'timezone' => 'Europe/Brussels',
    'groupByEntityGroup' => false,
    'showAllEntities' => false,
    'entityIds' => [
        '3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90'
    ],
    'tagIds' => [
        'tag_123',
        'tag_456'
    ],
    'groupIds' => [
        '018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42'
    ],
    'limit' => 5,
    'sort' => [
        [
                'field' => 'mentionCount',
                'direction' => 'DESC'
        ]
    ]
  ]),
  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/tags/stats"

	payload := strings.NewReader("{\n  \"tagType\": \"query\",\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\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  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"entityIds\": [\n    \"3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90\"\n  ],\n  \"tagIds\": [\n    \"tag_123\",\n    \"tag_456\"\n  ],\n  \"groupIds\": [\n    \"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42\"\n  ],\n  \"limit\": 5,\n  \"sort\": [\n    {\n      \"field\": \"mentionCount\",\n      \"direction\": \"DESC\"\n    }\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/tags/stats")
  .header("x-project-id", "<x-project-id>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tagType\": \"query\",\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\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  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"entityIds\": [\n    \"3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90\"\n  ],\n  \"tagIds\": [\n    \"tag_123\",\n    \"tag_456\"\n  ],\n  \"groupIds\": [\n    \"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42\"\n  ],\n  \"limit\": 5,\n  \"sort\": [\n    {\n      \"field\": \"mentionCount\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mentionlab.io/api/analytics/tags/stats")

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  \"tagType\": \"query\",\n  \"startDate\": \"2025-01-01\",\n  \"endDate\": \"2025-02-01\",\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  \"queryTagMode\": \"or\",\n  \"execTagMode\": \"or\",\n  \"timezone\": \"Europe/Brussels\",\n  \"groupByEntityGroup\": false,\n  \"showAllEntities\": false,\n  \"entityIds\": [\n    \"3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90\"\n  ],\n  \"tagIds\": [\n    \"tag_123\",\n    \"tag_456\"\n  ],\n  \"groupIds\": [\n    \"018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42\"\n  ],\n  \"limit\": 5,\n  \"sort\": [\n    {\n      \"field\": \"mentionCount\",\n      \"direction\": \"DESC\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "tags": [
    {
      "tagId": "550e8400-e29b-41d4-a716-446655440000",
      "tagName": "Pricing",
      "tagColor": "#4f46e5",
      "resultCount": 340,
      "projectBrand": {
        "mentionCount": 80,
        "visibility": 40,
        "avgRanking": 2.5,
        "sentimentScore": 72.3,
        "shareOfVoice": 32.1,
        "sentimentPositive": 52,
        "sentimentNeutral": 18,
        "sentimentNegative": 10
      }
    }
  ]
}

{
  "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

x-project-id

string

required

Project ID to specify the project context

Body

application/json

tagType

enum<string>

required

Which tag system to group by

Available options:

query,

execution

Example:

"query"

startDate

string

Start date (inclusive)

Example:

"2025-01-01"

endDate

string

End date (exclusive)

Example:

"2025-02-01"

countries

string[]

Filter by country codes

Example:

["BE", "FR"]

languages

string[]

Filter by language codes

Example:

["en", "fr"]

models

string[]

Filter by AI models

Example:

["gpt-4o", "claude-3-5-sonnet"]

queryIds

string[]

Filter by query IDs

Example:

["3fa85f64-5717-4562-b3fc-2c963f66afa6"]

hasSources

enum<string>

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

hasShopping

enum<string>

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

queryTagIds

string[]

Filter by query tag IDs (numeric — bigint column)

Example:

["42"]

execTagIds

string[]

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"]

queryTypes

enum<string>[]

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

queryTagMode

enum<string>

default:or

Query tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags.

Available options:

and,

or

execTagMode

enum<string>

default:or

Execution tag matching mode: "or" matches ANY tag (default), "and" matches ALL tags.

Available options:

and,

or

timezone

string

default:UTC

IANA timezone for date bucketing and filtering (e.g. "Europe/Brussels"). Defaults to UTC.

Example:

"Europe/Brussels"

groupBy

enum<string>

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

groupByEntityGroup

boolean

deprecated

Deprecated — use groupBy instead. true is equivalent to groupBy="group".

Example:

false

showAllEntities

boolean

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

entityIds

string[]

Entity IDs for the project brand (defaults to primary non-blacklisted)

Example:

["3f1a9c2e-7b4d-4e6a-9c1f-2d8e5a6b7c90"]

tagIds

string[]

Restrict to specific tag IDs (omit for all tags)

Example:

["tag_123", "tag_456"]

groupIds

string[]

Tag group IDs to roll up — each selected group returns one aggregated row (deduplicated per response), as a peer of any tagIds rows.

Example:

["018f3a2b-7c4d-7e91-b3f5-2a6c8d0e1f42"]

limit

number

Max number of tags to return (top N by the active sort). Omit for all tags.

Example:

5

sort

object[]

Server-side sort. Allowed fields: tagName, resultCount, mentionCount, visibility, shareOfVoice, avgRanking, sentimentScore. Default: mentionCount descending.

Show child attributes

Example:

[
  {
    "field": "mentionCount",
    "direction": "DESC"
  }
]

Overview

Projects

Queries

Entities

Organisations

Jobs

Tags

Tag Groups

Execution Tags

Theme Analysis

Entity Groups

Source Categories

Job Executions

Analytics - Visibility

Analytics - Tags

Analytics - Sources

Analytics - Shopping

Analytics - Sentiment

Analytics - Queries

Analytics - Models

Analytics - Themes

Analytics - Fan Outs

Analytics - Social

Source Topics

Reference

Shopping Products

Get per-tag stats with project brand metrics

Headers

Body

Response