What are the initial dataset filters, and how do they work?
Among the request parameters of specific endpoints of the LLM Mentions API, Business Data API, and Content Analysis API, you might have encountered the initial_dataset_filters array. Although you can pass similar filter fields and operators in initial_dataset_filters as in the default filters array, the underlying algorithm behind the initial dataset filters is different. In this guide, we’ll explain what initial dataset filters are and how they work.
Explaining the initial dataset filters and their difference from the default filters
To understand what the initial dataset filters are, let’s first go through how the default filters work. In most DataForSEO API endpoints, filters are applied to a pre-existing dataset or data fetched directly from the source. When you send an API request with a filters array specified, the API searches through the data, selects the results that match your conditions, and returns them in the response.
For example, if you specify “filters”: [“ai_search_volume”, “>”, 1000] in the request of the LLM Mentions Search endpoint, it will fetch all relevant individual mentions from the main dataset with the AI search volume above 1000.
The initial_dataset_filters are available in the other endpoint type of the DataForSEO API – the aggregation endpoints. These endpoints return aggregated metrics calculated as the sum of individual values derived from the underlying source data. For example, metrics such as mentions, and ai_search_volume in the LLM Mentions Aggregated Metrics endpoint represent the total number of relevant mentions and the sum of their AI search volume values, respectively. Basically, the response of an aggregation endpoint is built from the results of a related source endpoint.
For instance, the mentioned Aggregated Metrics endpoint builds its metrics from the raw data returned by the related Mentions Search endpoint. In this case, the initial_dataset_filters array lets you filter the source dataset from the Mentions Search endpoint before the aggregation is performed. In other words, you use initial_dataset_filters to define which source records should be included in the metric calculation. The filter fields available in initial_dataset_filters correspond to the fields of the source endpoint, not the aggregation endpoint itself.
Using the initial dataset filters in aggregation endpoints
Here’s a practical example. Suppose you are using the LLM Mentions Aggregated Metrics endpoint to find how many mentions are for the keyword “iphone” in ChatGPT answers with AI search volume above 1000. To filter out mentions that have less AI search volume, you should include the "initial_dataset_filters": ["ai_search_volume", ">", 1000] in the request.
POST: https://api.dataforseo.com/v3/ai_optimization/llm_mentions/aggregated_metrics/live
Request example:
[
{
"platform": "chat_gpt",
"target": [
{
"keyword": "iphone",
"search_scope": [
"answer"
]
}
],
"location_name": "United States",
"initial_dataset_filters": [
"ai_search_volume",
">",
1000
]
}
]
Response example:
{
"version": "0.1.20260420",
"status_code": 20000,
"status_message": "Ok.",
"time": "5.4503 sec.",
"cost": 0.101,
"tasks_count": 1,
"tasks_error": 0,
"tasks": [
{
"id": "04231852-1535-0635-0000-7cb0ae1bb3b4",
"status_code": 20000,
"status_message": "Ok.",
"time": "5.3841 sec.",
"cost": 0.101,
"result_count": 1,
"path": [
"v3",
"ai_optimization",
"llm_mentions",
"aggregated_metrics",
"live"
],
"data": {
"api": "ai_optimization",
"function": "aggregated_metrics",
"platform": "chat_gpt",
"target": [
{
"keyword": "iphone",
"search_scope": [
"answer"
]
}
],
"location_name": "United States",
"initial_dataset_filters": [
"ai_search_volume",
">",
1000
]
},
"result": [
{
"total": {
"location": [
{
"type": "group_element",
"key": "2840",
"mentions": 96,
"ai_search_volume": 202189,
"impressions": 19410144
}
],
"language": [
{
"type": "group_element",
"key": "en",
"mentions": 96,
"ai_search_volume": 202189,
"impressions": 19410144
}
],
"platform": [
{
"type": "group_element",
"key": "chat_gpt",
"mentions": 96,
"ai_search_volume": 202189,
"impressions": 19410144
}
],
"sources_domain": [
{
"type": "group_element",
"key": "apps.apple.com",
"mentions": 8,
"ai_search_volume": 24205,
"impressions": 193640
},
{
"type": "group_element",
"key": "en.wikipedia.org",
"mentions": 6,
"ai_search_volume": 23524,
"impressions": 141144
},
{
"type": "group_element",
"key": "support.apple.com",
"mentions": 8,
"ai_search_volume": 17933,
"impressions": 143464
},
{
"type": "group_element",
"key": "www.reddit.com",
"mentions": 6,
"ai_search_volume": 9917,
"impressions": 59502
},
{
"type": "group_element",
"key": "www.alibaba.com",
"mentions": 4,
"ai_search_volume": 5095,
"impressions": 20380
},
{
"type": "group_element",
"key": "www.apple.com",
"mentions": 2,
"ai_search_volume": 3103,
"impressions": 6206
},
{
"type": "group_element",
"key": "www.mcafee.com",
"mentions": 4,
"ai_search_volume": 5416,
"impressions": 21664
},
{
"type": "group_element",
"key": "www.phonearena.com",
"mentions": 4,
"ai_search_volume": 7757,
"impressions": 31028
},
{
"type": "group_element",
"key": "www.tomsguide.com",
"mentions": 4,
"ai_search_volume": 5828,
"impressions": 23312
},
{
"type": "group_element",
"key": "www.lifewire.com",
"mentions": 2,
"ai_search_volume": 2504,
"impressions": 5008
}
],
"search_results_domain": [
{
"type": "group_element",
"key": "apps.apple.com",
"mentions": 12,
"ai_search_volume": 29564,
"impressions": 354768
},
{
"type": "group_element",
"key": "support.apple.com",
"mentions": 9,
"ai_search_volume": 19002,
"impressions": 171018
},
{
"type": "group_element",
"key": "www.alibaba.com",
"mentions": 7,
"ai_search_volume": 11619,
"impressions": 81333
},
{
"type": "group_element",
"key": "www.apple.com",
"mentions": 4,
"ai_search_volume": 6622,
"impressions": 26488
},
{
"type": "group_element",
"key": "www.tomsguide.com",
"mentions": 7,
"ai_search_volume": 14594,
"impressions": 102158
},
{
"type": "group_element",
"key": "discussions.apple.com",
"mentions": 8,
"ai_search_volume": 12465,
"impressions": 99720
},
{
"type": "group_element",
"key": "www.youtube.com",
"mentions": 5,
"ai_search_volume": 7605,
"impressions": 38025
},
{
"type": "group_element",
"key": "www.reddit.com",
"mentions": 7,
"ai_search_volume": 20160,
"impressions": 141120
},
{
"type": "group_element",
"key": "9to5mac.com",
"mentions": 5,
"ai_search_volume": 9204,
"impressions": 46020
},
{
"type": "group_element",
"key": "play.google.com",
"mentions": 4,
"ai_search_volume": 15401,
"impressions": 61604
}
],
"brand_entities_title": [
{
"type": "group_element",
"key": "FlightAware",
"mentions": 3,
"ai_search_volume": 19510,
"impressions": 58530
},
{
"type": "group_element",
"key": "Flightradar24",
"mentions": 3,
"ai_search_volume": 19510,
"impressions": 58530
},
{
"type": "group_element",
"key": "Apple",
"mentions": 2,
"ai_search_volume": 4704,
"impressions": 9408
},
{
"type": "group_element",
"key": "Apple AirPods Max",
"mentions": 2,
"ai_search_volume": 2181,
"impressions": 4362
},
{
"type": "group_element",
"key": "Apple AirPods Pro 3",
"mentions": 2,
"ai_search_volume": 4242,
"impressions": 8484
},
{
"type": "group_element",
"key": "Bose QuietComfort Ultra",
"mentions": 2,
"ai_search_volume": 2421,
"impressions": 4842
},
{
"type": "group_element",
"key": "Flighty",
"mentions": 2,
"ai_search_volume": 18174,
"impressions": 36348
},
{
"type": "group_element",
"key": "Microsoft",
"mentions": 2,
"ai_search_volume": 4704,
"impressions": 9408
},
{
"type": "group_element",
"key": "Sony WH-1000XM6 Wireless Noise Canceling Headphones",
"mentions": 2,
"ai_search_volume": 2181,
"impressions": 4362
},
{
"type": "group_element",
"key": "Withings ScanWatch 2",
"mentions": 2,
"ai_search_volume": 2127,
"impressions": 4254
}
],
"brand_entities_category": [
{
"type": "group_element",
"key": "product",
"mentions": 12,
"ai_search_volume": 20295,
"impressions": 243540
},
{
"type": "group_element",
"key": "mobile_app",
"mentions": 7,
"ai_search_volume": 25843,
"impressions": 180901
},
{
"type": "group_element",
"key": "software",
"mentions": 6,
"ai_search_volume": 24584,
"impressions": 147504
},
{
"type": "group_element",
"key": "company",
"mentions": 2,
"ai_search_volume": 4704,
"impressions": 9408
},
{
"type": "group_element",
"key": "local_business",
"mentions": 1,
"ai_search_volume": 1649,
"impressions": 1649
},
{
"type": "group_element",
"key": "organization",
"mentions": 2,
"ai_search_volume": 3108,
"impressions": 6216
},
{
"type": "group_element",
"key": "apple_program",
"mentions": 1,
"ai_search_volume": 1449,
"impressions": 1449
},
{
"type": "group_element",
"key": "disease",
"mentions": 1,
"ai_search_volume": 1068,
"impressions": 1068
},
{
"type": "group_element",
"key": "people",
"mentions": 1,
"ai_search_volume": 1889,
"impressions": 1889
}
]
},
"items": null
}
]
}
]
}
Here is the result. As you can see, the total number of mentions of the keyword “iphone” in ChatGPT with an AI search volume of more than 1000 is 96. The ai_search_volume field represents the sum of the individual AI search volumes for mentions that match the initial filtering conditions.
In a nutshell, the system pulled all relevant mentions from the initial dataset, filtered out those with AI search volume below 1000, and aggregated the results to display as total metrics.
List of the DataForSEO API endpoints that support initial dataset filters
Below is a list of the DataForSEO API endpoints that support the initial_dataset_filters. Note that you can’t pass the filters array in a request to each of these endpoints.
LLM Mentions API:
Business Data API:
Content Analysis API: