Get entity stats for a single query

curl --request POST \
  --url https://api.mentionlab.io/api/analytics/queries/{queryId}/entities \
  --header 'Content-Type: application/json' \
  --header 'x-project-id: <x-project-id>' \
  --data '
{
  "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,
  "entityTypes": [
    "owned",
    "primary",
    "competitor"
  ],
  "entityIds": [
    "3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d"
  ]
}
'

import requests

url = "https://api.mentionlab.io/api/analytics/queries/{queryId}/entities"

payload = {
    "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,
    "entityTypes": ["owned", "primary", "competitor"],
    "entityIds": ["3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d"]
}
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-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,
    entityTypes: ['owned', 'primary', 'competitor'],
    entityIds: ['3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d']
  })
};

fetch('https://api.mentionlab.io/api/analytics/queries/{queryId}/entities', 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/queries/{queryId}/entities",
  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-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,
    'entityTypes' => [
        'owned',
        'primary',
        'competitor'
    ],
    'entityIds' => [
        '3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d'
    ]
  ]),
  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/queries/{queryId}/entities"

	payload := strings.NewReader("{\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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d\"\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/queries/{queryId}/entities")
  .header("x-project-id", "<x-project-id>")
  .header("Content-Type", "application/json")
  .body("{\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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mentionlab.io/api/analytics/queries/{queryId}/entities")

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-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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d\"\n  ]\n}"

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

{
  "totalResponses": 42,
  "entities": [
    {
      "displayKey": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Acme Corp",
      "isOwned": true,
      "isPrimary": true,
      "isCompetitor": false,
      "mentionCount": 56,
      "visibility": 67,
      "shareOfVoice": 32.1,
      "avgRanking": 2.5,
      "sentimentScore": 72.3,
      "sentiment": {
        "positive": 35,
        "neutral": 15,
        "negative": 6
      }
    }
  ]
}

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

queries

{queryId}

entities

Get entity stats for a single query

curl --request POST \
  --url https://api.mentionlab.io/api/analytics/queries/{queryId}/entities \
  --header 'Content-Type: application/json' \
  --header 'x-project-id: <x-project-id>' \
  --data '
{
  "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,
  "entityTypes": [
    "owned",
    "primary",
    "competitor"
  ],
  "entityIds": [
    "3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d"
  ]
}
'

import requests

url = "https://api.mentionlab.io/api/analytics/queries/{queryId}/entities"

payload = {
    "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,
    "entityTypes": ["owned", "primary", "competitor"],
    "entityIds": ["3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d"]
}
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-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,
    entityTypes: ['owned', 'primary', 'competitor'],
    entityIds: ['3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d']
  })
};

fetch('https://api.mentionlab.io/api/analytics/queries/{queryId}/entities', 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/queries/{queryId}/entities",
  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-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,
    'entityTypes' => [
        'owned',
        'primary',
        'competitor'
    ],
    'entityIds' => [
        '3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d'
    ]
  ]),
  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/queries/{queryId}/entities"

	payload := strings.NewReader("{\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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d\"\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/queries/{queryId}/entities")
  .header("x-project-id", "<x-project-id>")
  .header("Content-Type", "application/json")
  .body("{\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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mentionlab.io/api/analytics/queries/{queryId}/entities")

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-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  \"entityTypes\": [\n    \"owned\",\n    \"primary\",\n    \"competitor\"\n  ],\n  \"entityIds\": [\n    \"3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d\"\n  ]\n}"

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

{
  "totalResponses": 42,
  "entities": [
    {
      "displayKey": "550e8400-e29b-41d4-a716-446655440000",
      "displayName": "Acme Corp",
      "isOwned": true,
      "isPrimary": true,
      "isCompetitor": false,
      "mentionCount": 56,
      "visibility": 67,
      "shareOfVoice": 32.1,
      "avgRanking": 2.5,
      "sentimentScore": 72.3,
      "sentiment": {
        "positive": 35,
        "neutral": 15,
        "negative": 6
      }
    }
  ]
}

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

Path Parameters

queryId

string

required

UUID of the query to retrieve detected entity stats for.

Example:

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

Body

application/json

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

entityTypes

enum<string>[]

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

entityIds

string[]

Entity IDs for brand-scoped metrics. Defaults to project brand.

Example:

["3f8a1c2d-5b6e-4a7f-9c0d-1e2f3a4b5c6d"]

Response

totalResponses

number

required

Total number of AI responses for this query in the filtered scope (denominator for visibility).

Example:

42

entities

object[]

required

All detected entities for this query, ordered by presence (how often they appear in AI responses) descending.

Show child attributes

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 entity stats for a single query

Headers

Path Parameters

Body

Response