---
title: "Live LLM Mentions Cross Aggregated Metrics"
url: "https://docs.dataforseo.com/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live/"
date: "2026-06-06"
---
## Live LLM Mentions Cross Aggregated Metrics
Live LLM Mentions endpoint provides aggregated metrics grouped by custom keys for mentions of the keywords or domains specified in the `target` array of the request. Each item in the results array corresponds to the specified target. The results are specific to the selected platform (`google` for Google’s AI Overview or `chat_gpt` for ChatGPT), location and language parameters (see [the List of Locations & Languages](https://docs.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages.md)).
 POST https://api.dataforseo.com/v3/ai\_optimization/llm\_mentions/cross\_aggregated\_metrics/live
Pricing
The cost of the task can be calculated on the [Pricing page](https://dataforseo.com/pricing/ai-optimization/llm-mentions).
All POST data should be sent in the [JSON](https://en.wikipedia.org/wiki/JSON) format (UTF-8 encoding). The task setting is done using the POST method. When setting a task, you should send all task parameters in the task array of the generic POST array. You can send up to 2000 API calls per minute, each Live LLM Mentions API call can contain only one task.
**Execution time for tasks set with the Live LLM Mentions endpoint is currently up to 120 seconds.**
Below you will find a detailed description of the fields you can use for setting a task.
| Field name | Type | Description |
|---|---|---|
| **`targets`** | array | *array of objects containing target entities with aggregation keys* **required field** you can specify **up to 10, but not less than 2** `target` sets of parameters, each with its `aggregation_key`; example of a `targets` array with multiple entities: `[{"aggregation_key":"bmw","target":[{"domain":"en.wikipedia.org","search_filter":"exclude"},{"keyword":"m5","match_type":"partial_match","search_scope":["answer"]}]},{"aggregation_key":"mercedes","target":[{"domain":"www.mercedes-benz.com","search_filter":"exclude"},{"keyword":"GLC","match_type":"word_match"}]}]` |
| `aggregation_key` | string | *aggregation key for grouping the results* **required field** groups results for comparison and serves as a label for the group; you can specify **up to 250 characters** in the `aggregation_key` field |
| `target` | array | *array of objects containing target entities* **required field** a single `target` can contain up to 10 `domain` and/or `keyword` entities |
| **`domain_entity`** | object | *domain entity in the target array* example: `{"domain": "en.wikipedia.org", "search_filter": "exclude", "search_scope": ["sources"]}` |
| `domain` | string | *target domain* **required field if you don't specify a `keyword`** you can specify **up to 63 characters** in the `domain` field; a domain should be specified without `https://` and `www.` |
| `search_filter` | string | *target domain search filter* optional field possible values: `include`, `exclude` default value: `include` |
| `search_scope` | array | *target domain search scope* optional field possible values: `any`, `sources`, `search_results` default value: `any` |
| `include_subdomains` | boolean | *indicates if the subdomains of the target `domain` will be included in the search* optional field if set to `true`, the subdomains will be included in the search default value: `false` |
| **`keyword_entity`** | object | *keyword entity in the target array* example: `{"keyword": "bmw", "search_filter": "include", "search_scope": ["question"], "match_type ": "partial_match"}` |
| `keyword` | string | *target keyword* **required field if you don't specify a `domain`** you can specify **up to 250 characters** in the `keyword` field all %## will be decoded (plus character ‘+’ will be decoded to a space character) if you need to use the “%” character for your `keyword`, please specify it as “%25”; if you need to use the “+” character for your `keyword`, please specify it as “%2B” learn more about rules and limitations of `keyword` and `keywords` fields in DataForSEO APIs in this [Help Center article](https://dataforseo.com/help-center/rules-and-limitations-of-keyword-and-keywords-fields-in-dataforseo-apis) |
| `search_filter` | string | *target keyword search filter* optional field possible values: `include`, `exclude` default value: `include` |
| `search_scope` | array | *target keyword search scope* optional field possible values: `any`, `question`, `answer`, `brand_entities`, `fan_out_queries` default value: `any` |
| `match_type` | string | *target keyword match type* defines how the specified keyword is matched optional field possible values: `word_match` - full-text search for terms that match the specified seed keyword with additional words included before, after, or within the key phrase (e.g., search for "light" will return results with "light bulb", "light switch"); `partial_match` - substring search that finds all instances containing the specified sequence of characters, even if it appears inside a longer word (e.g., search for "light" will return results with "lighting", "highlight"); default value: `word_match` |
| `location_name` | string | *full name of search location* optional field if you use this field, you don't need to specify `location_code` if you don't specify this field, the `location_code` with `2840` value will be used by default; you can receive the list of available locations of the search engine with their `location_name` by making a separate request to the `https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages` **Note: `chat_gpt` data is available for `United States` only** |
| `location_code` | integer | *search location code* optional field if you use this field, you don't need to specify `location_name` you can receive the list of available locations of the search engine with their `location_code` by making a separate request to the `https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages` default value: `2840` **Note: `chat_gpt` data is available for `2840` only** |
| `language_name` | string | *full name of search language* optional field if you use this field, you don't need to specify `language_code`; if you don't specify this field, the `language_code` with `en` value will be used by default; you can receive the list of available languages of the search engine with their `language_name` by making a separate request to the `https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages` **Note: `chat_gpt` data is available for `English` only** |
| `language_code` | string | *search language code* optional field if you use this field, you don't need to specify `language_name`; you can receive the list of available languages of the search engine with their `language_code`\_by making a separate request to the `https://api.dataforseo.com/v3/ai_optimization/llm_mentions/locations_and_languages` default value: `en` **Note: `chat_gpt` data is available for `en` onlyn** |
| `platform` | string | *target platform* optional field possible values: `chat_gpt`, `google` default value: `google` **Note:** the data returned depends on the selected platform **Note #2:**`chat_gpt` data is available for the `United States` and `English` only |
| `initial_dataset_filters` | array | *array of filter expressions applied before aggregation* optional field you can use this array to filter expressions applied to the raw mentions database before aggregation to limit the rows contributing to the result; **you can add several filters at once (8 filters maximum)** you should set a logical operator `and`, `or` between the conditions the following operators are supported: `=`, `<>`, `in`, `not_in`, `like`, `not_like`, `ilike`, `not_ilike`, `match`, `not_match` you can use the `%` operator with `like` and `not_like` to match any string of zero or more characters example: `["ai_search_volume",">","1000"]` the full list of possible filters is available [here.](https://docs.dataforseo.com/v3/ai_optimization/llm_mentions/filters.md) learn more about the initial dataset filters in [this help center article.](https://dataforseo.com/help-center/what-are-the-initial-dataset-filters-and-how-do-they-work) |
| `internal_list_limit` | integer | *maximum number of elements within internal arrays* optional field you can use this field to limit the number of elements within the following arrays: `sources_domain` `search_results_domain` minimum value: `1` maximum value: `10` default value: `5` |
| `tag` | string | *user-defined task identifier* optional field *the character limit is 255* you can use this parameter to identify the task and match it with the result you will find the specified `tag` value in the `data` object of the response |
As a response of the API server, you will receive [JSON](https://en.wikipedia.org/wiki/JSON)-encoded data containing a `tasks` array with the information specific to the set tasks.
**Description of the fields in the results array:**
| Field name | Type | Description |
|---|---|---|
| `version` | string | *the current version of the API* |
| `status_code` | integer | *general status code* you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) **Note:** we strongly recommend designing a necessary system for handling related exceptional or error conditions |
| `status_message` | string | *general informational message* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md) |
| `time` | string | *execution time, seconds* |
| `cost` | float | *total tasks cost, USD* |
| `tasks_count` | integer | *the number of tasks in the **`tasks`** array* |
| `tasks_error` | integer | *the number of tasks in the **`tasks`** array returned with an error* |
| **`tasks`** | array | *array of tasks* |
| `id` | string | *task identifier* **unique task identifier in our system in the [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) format** |
| `status_code` | integer | *status code of the task* generated by DataForSEO; can be within the following range: 10000-60000 you can find the full list of the response codes [here](https://docs.dataforseo.com/v3/appendix/errors.md) |
| `status_message` | string | *informational message of the task* you can find the full list of general informational messages [here](https://docs.dataforseo.com/v3/appendix/errors.md) |
| `time` | string | *execution time, seconds* |
| `cost` | float | *cost of the task, USD* |
| `result_count` | integer | *number of elements in the `result` array* |
| `path` | array | *URL path* |
| `data` | object | *contains the same parameters that you specified in the POST request* |
| **`result`** | array | *array of results* |
| **`total`** | object | *aggregated mentions metrics summary* contains overall aggregated LLM mention metrics across all found domains, grouped by various dimensions |
| **`location`** | array | *location-based grouping* array of objects containing mention metrics segmented by geographical location |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to this specific grouping key |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`language`** | array | *language-based grouping* array of objects containing mention metrics segmented by content language |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to this specific grouping key |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`platform`** | array | *platform-based grouping* array of group elements containing mention metrics segmented by AI platform |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to this specific grouping key |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`sources_domain`** | array | *found top source domains relevant to the target* array of objects containing data on top domains that are cited as sources in LLM responses learn more about the sources and how to retrieve LLM citation data at our [Help Center](https://dataforseo.com/help-center/how-to-get-llm-citation-data-with-llm-mentions-api) |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension in this case the field displays a found domain name |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to the specific domain |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`search_results_domain`** | array | *found top search results domains relevant to the target* array of objects containing data on top domains that appear in search results related to LLM queries |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension in this case the field displays a found domain name |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to the specific domain |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`brand_entities_title`** | array | *data on brand entities relevant to the target* array of objects containing data on brand entity titles that appear in search results related to LLM queries |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension in this case the field displays a found brand entity title |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to the specific domain |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`brand_entities_category`** | array | *data on brand entities relevant to the target* array of objects containing data on brand entity categories that appear in search results related to LLM queries |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension in this case the field displays a found brand entity category |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to the specific domain |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`items`** | array | *contains relevant mentions data* |
| `key` | string | *aggregation key received in a POST array* |
| **`location`** | array | *location-based grouping* array of objects containing mention metrics segmented by geographical location |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to this specific grouping key |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`language`** | array | *language-based grouping* array of objects containing mention metrics segmented by content language |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to this specific grouping key |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`platform`** | array | *platform-based grouping* array of group elements containing mention metrics segmented by AI platform |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to this specific grouping key |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`sources_domain`** | array | *found top source domains relevant to the target* array of objects containing data on top domains that are cited as sources in LLM responses learn more about the sources and how to retrieve LLM citation data at our [Help Center](https://dataforseo.com/help-center/how-to-get-llm-citation-data-with-llm-mentions-api) |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension in this case the field displays a found domain name |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to the specific domain |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`search_results_domain`** | array | *found top search results domains relevant to the target* array of objects containing data on top domains that appear in search results related to LLM queries |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension in this case the field displays a found domain name |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to the specific domain |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`brand_entities_title`** | array | *data on brand entities relevant to the target* array of objects containing data on brand entity titles that appear in search results related to LLM queries |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension in this case the field displays a found brand entity title |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to the specific domain |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
| **`brand_entities_category`** | array | *data on brand entities relevant to the target* array of objects containing data on brand entity categories that appear in search results related to LLM queries |
| `type` | string | *type of the element = '**group\_element**'* |
| `key` | string | *grouping identifier* the specific identifier for the grouping dimension in this case the field displays a found brand entity category |
| `mentions` | integer | *total LLM mentions count* the number of times the target keyword or domain were mentioned in relation to the specific domain |
| `ai_search_volume` | integer | *current AI search volume rate of a keyword* learn more about this metric [here](https://dataforseo.com/help-center/how-the-ai-search-volume-metric-works-in-llm-mentions) |
| `impressions` | integer | *current AI impressions rate of a keyword* deprecated field, the value will be `null` |
> Instead of ‘login’ and ‘password’ use your credentials from https://app.dataforseo.com/api-access
```
# Instead of 'login' and 'password' use your credentials from https://app.dataforseo.com/api-access
login="login"
password="password"
cred="$(printf ${login}:${password} | base64)"
curl --location --request POST "https://api.dataforseo.com/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live"
--header "Authorization: Basic ${cred}"
--header "Content-Type: application/json"
--data-raw '[
{
"language_code": "en",
"location_code": 2840,
"platform": "google",
"targets": [
{
"aggregation_key": "chat_gpt",
"target": [
{
"keyword": "chat gpt"
}
]
},
{
"aggregation_key": "claude",
"target": [
{
"keyword": "claude"
}
]
},
{
"aggregation_key": "gemini",
"target": [
{
"keyword": "gemini"
}
]
},
{
"aggregation_key": "perplexity",
"target": [
{
"keyword": "perplexity",
"search_filter": "include"
}
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"internal_list_limit": 5
}
]'
```
```php
'en',
'location_code' => 2840,
'platform' => 'google',
'targets' => [
[
'aggregation_key' => 'chat_gpt',
'target' => [
[
'keyword' => 'chat gpt',
],
],
],
[
'aggregation_key' => 'claude',
'target' => [
[
'keyword' => 'claude',
],
],
],
[
'aggregation_key' => 'gemini',
'target' => [
[
'keyword' => 'gemini',
],
],
],
[
'aggregation_key' => 'perplexity',
'target' => [
[
'keyword' => 'perplexity',
'search_filter' => 'include',
],
],
],
],
'initial_dataset_filters' => [
[
'ai_search_volume',
'>',
10,
],
],
'internal_list_limit' => 5,
],
];
try {
$result = $client->post('/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live', $data);
print_r($result);
// do something with post result
} catch (RestClientException $e) {
printf(
"HTTP code: %dnError code: %dnMessage: %snTrace: %sn",
$e->getHttpCode(),
$e->getCode(),
$e->getMessage(),
$e->getTraceAsString()
);
}
?>
```
```js
const axios = require('axios');
axios({
method: 'post',
url: 'https://api.dataforseo.com/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live',
auth: {
username: 'login',
password: 'password'
},
data: [ {
"language_code": "en",
"location_code": 2840,
"platform": "google",
"targets": [
{
"aggregation_key": "chat_gpt",
"target": [
{
"keyword": "chat gpt"
}
]
},
{
"aggregation_key": "claude",
"target": [
{
"keyword": "claude"
}
]
},
{
"aggregation_key": "gemini",
"target": [
{
"keyword": "gemini"
}
]
},
{
"aggregation_key": "perplexity",
"target": [
{
"keyword": "perplexity",
"search_filter": "include"
}
]
}
],
"initial_dataset_filters": [
[
"ai_search_volume",
">",
10
]
],
"internal_list_limit": 5
}],
headers: {
'content-type': 'application/json'
}
}).then(function (response) {
var result = response['data']['tasks'];
// Result data
console.log(result);
}).catch(function (error) {
console.log(error);
});
```
```
"""
Method: POST
Endpoint: https://api.dataforseo.com/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live
@see https://docs.dataforseo.com/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live
"""
import sys
import os
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '../../../../../')))
from lib.client import RestClient
from lib.config import username, password
client = RestClient(username, password)
post_data = []
post_data.append({
'language_code': 'en',
'location_code': 2840,
'platform': 'google',
'targets': [
{
'aggregation_key': 'chat_gpt',
'target': [
{
'keyword': 'chat gpt'
}
]
},
{
'aggregation_key': 'claude',
'target': [
{
'keyword': 'claude'
}
]
},
{
'aggregation_key': 'gemini',
'target': [
{
'keyword': 'gemini'
}
]
},
{
'aggregation_key': 'perplexity',
'target': [
{
'keyword': 'perplexity',
'search_filter': 'include'
}
]
}
],
'initial_dataset_filters': [
[
'ai_search_volume',
'>',
10
]
],
'internal_list_limit': 5
})
try:
response = client.post('/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live', post_data)
print(response)
# do something with post result
except Exception as e:
print(f'An error occurred: {e}')
```
```csharp
///
/// Method: POST
/// Endpoint: https://api.dataforseo.com/v3/ai_optimization/llm_mentions/cross_aggregated_metrics/live
///
///
public static async Task LlmMentionsCrossAggregatedMetricsLive()
{
var postData = new List