Skip to main content
The Spark API and MCP provide access to GWI’s full suite of syndicated data sets, scoped to your subscription. This guide covers the key behaviors to know when querying across multiple data sets so you get accurate, efficient results.

​
Our syndicated offer includes two types of data sets

​
Default behavior: GWI Core and add-ons

When you don’t specify a data set, Spark defaults searching for insights within GWI Core and all of its add-on studies. This gives you the broadest possible coverage and is the right starting point for most queries.
Rule of thumb: If you’re not sure which data set to use, don’t specify one. The default (GWI Core + add-ons) has the most survey coverage of any single selection.

​
Switching to another primary data set narrows your coverage

If you select GWI USA or GWI Kids instead of GWI Core, you’re switching to an independent primary data set with no shared respondents with GWI Core. That selection doesn’t include any add-ons, so the data universe Spark will be searching is narrower.

​
Spark picks the data set, so help it pick the right one

Spark uses natural language to decide which data set to query. When your prompt could match multiple data sets (for example, ‘sports’ exists in both GWI Core and GWI Sports), Spark’s selection can be unpredictable. Be explicit in your prompts when you want data from a specific data set.

​
Querying a specific add-on data set directly

You don’t need to query all of GWI Core just to access an add-on. Because add-on respondents are a subset of GWI Core respondents, you can select a specific add-on like GWI Work or GWI Gaming directly and still apply GWI Core-based audience filters. Example: “Give me insights on gaming habits using GWI Gaming”. You can still apply a saved GWI Core audience (e.g. 18-34 males) as the base, because GWI Gaming respondents are a subset of GWI Core respondents.

​
Saved audiences and data set compatibility

Audiences built using GWI Core data points are compatible with GWI Core and any of its add-on studies. They are not compatible with GWI USA, GWI Kids, or any other primary data set, as these have entirely separate respondent pools. If a user applies an audience built using GWI Core to a non-compatible data set query, Spark will return an error. Make sure your prompt templates guide users toward compatible selections.
Currently the saved audiences endpoint is search-based and not browse-based. To find your audiences, you need to enter a keyword; asking “what audiences do I have?” won’t return a full list. For the most comprehensive results, search by topic instead: “what audiences do I have related to social media?”

​
The data set list is now much larger

The list_datasets tool previously returned a handful of options. It now returns the full suite of syndicated studies you have access to in your subscription. This has practical implications:
  • Context window: The full list consumes significantly more tokens. Call list_datasets once per session and reuse the result. Don’t call it on every turn.
  • Filtering: Where possible, filter by category before passing the list downstream. Avoid sending the full unfiltered payload into a prompt.
  • User-facing responses: When surfacing available data sets to users, group them by type (Core, add-ons, USA, Kids) rather than listing everything flat.

​
Combining data sets: the compatibility rules

Not all data set combinations are valid in a single query. The underlying rule is: you can only combine data sets that share a respondent pool.
  • Add-ons can be combined with Core. Their respondents are a subset of Core.
  • Primary data sets (Core, GWI USA, GWI Kids) cannot be combined with each other.
  • Two add-ons cannot be combined with each other. They don’t share a direct respondent overlap.
If you hit a compatibility error: Check whether the data sets being combined share a parent-child relationship. If you’re unsure, use the Core default which handles all of this automatically.

​
Quick reference