Skip to main content

[1.5.0] - 2026-11-18

Tool responses on /v2/spark-api/mcp now flag simulated data, and audience_generation limits the number of audiences per call.

Added

  • Structured tool output includes is_simulated on each record that can use simulated data. true means that specific record uses simulated data:
    • list_datasets and render_dataset_picker: is_simulated on dataset nodes in the datasets tree.
    • search_audiences and audience_generation: is_simulated on each audiences[] item.
    • explore_datasets: is_simulated on each returned dataset.
    • explore_taxonomy: is_simulated on each returned dataset, audience, question, and attribute.
    • generate_insights: is_simulated on each results[].insights[] item.
    • explore_insight: top-level is_simulated for the insight, plus is_simulated on nested metadata records such as attributes, audiences, and datasets.
  • Server instructions and tool descriptions now tell host LLMs to place a `[✦ Simulated]` marker immediately after the name of each simulated record they present. The marker applies only to the record whose own flag is true. It is never inherited from a parent dataset or related audience.

Changed

  • audience_generation accepts 1–10 audience descriptions in audiences. Calls with more than 10 audiences, or with empty or whitespace-only entries, are rejected as invalid input before any audience is created.

Notes

  • Existing clients that treat unknown fields as optional need no code changes.
  • To create more than 10 audiences, split the request across multiple audience_generation calls. Calls with 10 or fewer audiences behave as before.

[1.4.0] - 2026-11-06

render_dataset_picker is now available on /v2/spark-api/mcp and /v2beta/spark-api/mcp.

Added

  • render_dataset_picker lets users browse and choose datasets before global_filters. On hosts that support MCP Apps, the host renders an interactive dataset picker. On text-only hosts, the agent presents a short overview of the dataset catalog. Pass optional audiences for dataset compatibility checks and selected_datasets to pre-fill the picker when re-opening it.

Notes

  • Use render_dataset_picker when the user wants to browse or choose datasets, and list_datasets when the user already named a dataset. Do not call both in the same dataset-selection step. See Overview for the full call order.
  • Clients that build calls from tools/list pick up the new tool automatically.

[1.3.0] - 2026-11-04

Spark MCP v2 is now available at /v2/spark-api/mcp.

Added

  • New endpoint: POST https://api.globalwebindex.com/v2/spark-api/mcp. It exposes the same tools, tool descriptions, and call order as /v2beta/spark-api/mcp, and uses the same authorization.

Notes

  • /v2beta/spark-api/mcp remains available and unchanged. To move to v2, replace /v2beta/ with /v2/ in your MCP server URL. No other client changes are needed.

[1.2.0] - 2026-10-07

The v2 MCP server (/v2beta/spark-api/mcp) now exposes ten tools.

Added

  • list_skills returns workflow skill keys and short descriptions. Hosts call it at the start of each new analysis.
  • get_skills returns the full markdown instructions for the skill keys you pass in skill_keys. Unknown or empty keys return isError: true.
  • explore_datasets returns short or verbose summaries for 1–5 dataset codes from list_datasets. A dataset whose summary is unavailable carries summary_error, and the other datasets still return.
  • explore_taxonomy returns the survey questions and attributes relevant to a topic, scoped by optional dataset_codes, enforced_audiences, location_codes, and wave_codes.

Notes

  • Existing tools and call order are unchanged. Clients that build calls from tools/list pick up the new tools automatically. See Overview for when to call each tool.

[1.1.0] - 2026-09-18

The v2 MCP server (/v2beta/spark-api/mcp) is updated.

Added

  • MCP protocol version 2026-07-28 is now supported. New clients negotiate 2026-07-28 via the server/discover handshake; clients that use the legacy initialize handshake continue to negotiate down to 2025-11-25 and keep working unchanged.
  • tools/list responses now include SEP-2549 cache hints (ttlMs, cacheScope) so clients can cache the tool catalogue between calls.
  • Tool annotations always include idempotentHint and readOnlyHint (previously omitted when unset).

Changed

  • Breaking: generate_insights now takes a prompts array (1–10 per call) instead of a single prompt, and returns results[] with one entry per prompt in the same order. Downstream calls run concurrently, so hosts can batch related topics into one tool call. Update clients to send prompts and read results[].

Added

  • Per-result failure isolation on generate_insights: when one prompt fails, its results[] entry carries message and error, and sibling successes are preserved. The tool call itself only returns isError: true for batch-wide failures such as validation errors or a missing referrer.

Notes

  • Batch concurrency is capped server-side (default 5 concurrent downstream calls per request). Latency scales with the slowest prompt, so calls with many prompts can exceed 10 seconds.
  • Transport remains stateless HTTP JSON-RPC: no Mcp-Session-Id is issued or required, and every request stands on its own.
  • Existing clients that treat unknown fields as optional need no code changes.

[1.0.1] - 2026-08-19

Fixed

  • search_audiences: results now include only saved platform audiences (authored, shared, curated) and exclude ephemeral instant audiences, which previously dominated results

[1.0.0] - 2026-08-14

Added

  • New channel: /v2beta/spark-api/mcp — single MCP endpoint for all clients (no /openai/mcp route on this channel)
  • global_filters tool for location and timeframe scope
  • audience_generation tool for creating audiences from natural language prompts
  • generate_insights tool for insight discovery

Changed

  • OpenAI / ChatGPT clients use the same endpoint and standard tool names as every other client
  • explore_insight is the follow-up enrichment tool for all clients and returns structured JSON
See the Transition guide for endpoint and tool mapping from earlier releases.

[0.4.0] - 2026-07-15

Both MCP servers are updated:
  • standard MCP (/v1/spark-api/mcp)
  • ChatGPT MCP (/v1/spark-api/openai/mcp)

Added

  • search_audiences tool for searching saved/platform audiences by free-text query; optional dataset_codes, exclude_audience_ids, and limit (1–100)

Changed

  • chat_gwi / search: supports optional dataset_codes to query a root dataset together with one or more of its add-on studies (values must belong to the same dataset tree)
  • chat_gwi / search: supports optional docked_audiences to scope insights to platform audience UUIDs (max 10; use IDs from search_audiences)
  • chat_gwi / search: when both dataset_code and dataset_codes are provided, dataset_codes takes precedence and dataset_code is ignored
  • chat_gwi / search: when both dataset_code and dataset_codes are omitted, the default dataset available to the user is used (previously hard-coded to ds-core)
  • list_datasets: returns hierarchical folders and nested dataset nodes so clients can identify valid root/child combinations
  • explore_insight_gwi / fetch: response now includes the origin datasets of the corresponding insight
  • explore_insight_gwi: attribute output now includes Universe Size alongside question, answer, percentage, sample, and index — the estimated number of real-world internet users within the audience
  • fetch: response now includes structured metadata with an attributes array (question, answer, percentage, sample, universe_size, index) plus timeframe_groups, location_groups, audiences, and datasets for the source insight
  • search and fetch now return typed structured results instead of JSON encoded inside content text blocks; clients that already parse the tool result payload need no changes, but clients reading raw text MAY switch to the structured result

[0.3.0] - 2026-07-07

Both MCP servers are updated:
  • standard MCP (/v1/spark-api/mcp)
  • ChatGPT MCP (/v1/spark-api/openai/mcp)

Changed

  • chat_gwi / search: supports optional limit to set the maximum number of insights returned per call (1–20; default 10)

[0.2.0] - 2026-03-11

Added

  • list_datasets tool for listing available GWI datasets; use to discover dataset codes for chat_gwi
  • chat_gwi: optional dataset_code argument to specify which dataset to query; default: ds-core

[0.1.0] - 2025-12-01

Added

  • chat_gwi tool for gathering insights about audiences based on GWI data
  • explore_insight_gwi for exploring detailed information about the insight statistics
  • OAuth2 support for secure authentication

Changed

  • Initial release of the Spark MCP