> ## Documentation Index > Fetch the complete documentation index at: https://api.globalwebindex.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Execute GWI MCP v2beta tool calls > JSON-RPC endpoint for the v2beta MCP profile. Supported tools: 1. **global_filters** 2. **audience_generation** 3. **generate_insights** 4. **explore_insight** 5. **list_datasets** 6. **search_audiences** ## OpenAPI ````yaml post /v2beta/spark-api/mcp openapi: 3.0.0 info: title: GWI Spark API - MCP Server (v2beta) version: 2.0.0-beta description: > # GWI MCP Server v2beta for AI Assistants The v2beta MCP profile exposes a workflow-oriented tool chain for audience insights. It replaces v1 discovery tools (`chat_gwi` / `search`) with `generate_insights`, and adds `global_filters` and `audience_generation` for scope resolution. Enrichment uses **`explore_insight`** (replaces v1 `explore_insight_gwi` on the client) and returns structured JSON rather than prose. **Endpoint:** `POST /v2beta/spark-api/mcp` ## HTTP headers | Header | Value | | --- | --- | | `Content-Type` | `application/json` | | `Accept` | `application/json, text/event-stream` | | `Mcp-Protocol-Version` | `2025-11-25` | | `Authorization` | `Bearer YOUR_TOKEN` | ## Suggested workflow 1. **list_datasets** — optional; discover dataset codes when explicit scope is needed 2. **global_filters** — required before audience and insight tools 3. **audience_generation** — when the user describes a cohort (or **search_audiences** when they name a saved audience) 4. **generate_insights** — pass `enforced_audiences`, `location_codes`, and `wave_codes` from earlier steps 5. **explore_insight** — replaces v1 `explore_insight_gwi`; returns structured JSON (`id`, `title`, `text`, `url`, `metadata`). Call only when the user explicitly asks for more detail on a specific `insights[].id` from `generate_insights` (reactive-only; do not call automatically after step 4) Example chain: `global_filters` → `audience_generation` ("Gen Z") → `generate_insights` ("social media habits") → `explore_insight` (optional, user-initiated). Never call `audience_generation`, `search_audiences`, or `generate_insights` before `global_filters` on a new analysis. ## Request/response format All requests use JSON-RPC 2.0 format: ### Request structure ```json { "jsonrpc": "2.0", "id": "unique-request-id", "method": "tools/call", "params": { "name": "tool_name", "arguments": { // tool-specific arguments } } } ``` ### Response structure ```json { "jsonrpc": "2.0", "id": "unique-request-id", "result": { "content": [ { "type": "text", "text": "..." } ] } } ``` On success, tools return **`structuredContent`** — a typed object that mirrors the JSON in `content[0].text`. Prefer `structuredContent` for programmatic parsing; the object shape depends on the tool (see response examples). ### Tool errors (`result.isError`) **When to check** After a successful JSON-RPC envelope (HTTP **200**, no top-level `error` field), look at **`result.isError`**: | `result.isError` | Meaning | | --- | --- | | `true` | Tool failed. Read `result.content` — usually one `text` item with a human-readable message. No `structuredContent` was returned. | **Why HTTP can still be 200** A failed tool is still a completed JSON-RPC call. The failure is signaled in **`result`**, not by HTTP status alone. **Common reasons for `isError: true`** 1. **Invalid arguments** — bad or missing inputs before or during validation, for example: - `global_filters`: empty `prompt` - `audience_generation`: empty `audiences` - `generate_insights`: empty `prompt`; invalid UUIDs in `enforced_audiences`; `limit` outside `1..20` - `explore_insight`: missing or invalid UUID `insight_id` - `search_audiences`: missing/empty `query`; invalid UUIDs in `exclude_audience_ids`; `limit` outside `1..100` - Other tools: same pattern where IDs or required strings are wrong 2. **Downstream / service errors** — GWI or infrastructure issues after arguments are accepted, for example: - Resource not found (insight, dataset, audience, etc.) - `enforced_audiences` incompatible with `dataset_codes` or mixed audiences from different datasets - Timeouts, cancelled requests, or generic internal failures **`_meta.isInternalError`** When **`result._meta.isInternalError`** is **`true`**, the server classified the failure as internal or timeout-style. It may be omitted or `false` for validation or not-found style errors. **Not covered here: JSON-RPC protocol errors** Invalid `method`, malformed JSON-RPC, and similar issues use the standard JSON-RPC **`error`** field. They are **not** expressed as `result.isError`. ### Soft failures and partial success These are **not** `result.isError`. The tool call completed; surface the warning or partial outcome to the user: - **`generate_insights`:** non-empty `structuredContent.error` — use `structuredContent.message` as the user-facing text. - **`global_filters`:** `structuredContent.global_filters.inaccessible_location_names` — some location terms were excluded for access; other filters still resolved. See example `global_filters_partial_access`. - **`audience_generation`:** `structuredContent.failed_audiences` — map of prompts that could not be mapped; `audiences` may be empty or partial. See example `audience_generation_all_failed`. servers: - url: https://api.globalwebindex.com security: [] paths: /v2beta/spark-api/mcp: post: tags: - MCP Tools summary: Execute GWI MCP v2beta tool calls description: | JSON-RPC endpoint for the v2beta MCP profile. Supported tools: 1. **global_filters** 2. **audience_generation** 3. **generate_insights** 4. **explore_insight** 5. **list_datasets** 6. **search_audiences** operationId: mcpV2BetaToolCall requestBody: required: true description: JSON-RPC request for any supported v2beta MCP tool content: application/json: schema: oneOf: - $ref: '#/components/schemas/GlobalFiltersRequest' - $ref: '#/components/schemas/AudienceGenerationRequest' - $ref: '#/components/schemas/GenerateInsightsRequest' - $ref: '#/components/schemas/ExploreInsightRequest' - $ref: '#/components/schemas/ListDatasetsRequest' - $ref: '#/components/schemas/SearchAudiencesRequest' responses: '200': description: > JSON-RPC response. HTTP 200 means the JSON-RPC call was processed, not that the tool succeeded. Inspect `result.isError` if present: - `true` — tool failed; the message is in `result.content[0].text`, and `result._meta.isInternalError` may be `true` for internal or timeout-style failures. See **Tool errors (`result.isError`)** in the overview above for full behavior. content: application/json: schema: $ref: '#/components/schemas/JsonRpcSuccessResponse' examples: global_filters_response: summary: global_filters value: jsonrpc: '2.0' id: 4 result: content: - type: text text: >- {"global_filters":{"location_codes":["s2_44"],"location_names":["UK"],"wave_codes":["q1_2025"],"wave_names":["Q1 2025"]}} structuredContent: global_filters: location_codes: - s2_44 location_names: - UK wave_codes: - q1_2025 wave_names: - Q1 2025 global_filters_partial_access: summary: global_filters (partial access) value: jsonrpc: '2.0' id: 4 result: content: - type: text text: >- {"global_filters":{"inaccessible_location_names":["Albania"],"location_codes":["s2_30"],"location_names":["Greece"],"wave_codes":["q3_2025","q4_2025","q1_2026","q2_2026"],"wave_names":[]}} structuredContent: global_filters: inaccessible_location_names: - Albania location_codes: - s2_30 location_names: - Greece wave_codes: - q3_2025 - q4_2025 - q1_2026 - q2_2026 wave_names: [] audience_generation_response: summary: audience_generation value: jsonrpc: '2.0' id: 5 result: content: - type: text text: >- {"audiences":[{"datasets":["ds-core"],"description":"This audience consists of individuals who are part of Gen Z.","id":"259f6394-436c-4801-b83b-bbc926e8b4b9","name":"Generation: Gen Z"}]} structuredContent: audiences: - datasets: - ds-core description: >- This audience consists of individuals who are part of Gen Z. id: 259f6394-436c-4801-b83b-bbc926e8b4b9 name: 'Generation: Gen Z' audience_generation_all_failed: summary: audience_generation (all failed) value: jsonrpc: '2.0' id: 5 result: content: - type: text text: >- {"audiences":[],"failed_audiences":{"mars explorers":"no relevant attributes found for the terms: mars explorers: audience not found"}} structuredContent: audiences: [] failed_audiences: mars explorers: >- no relevant attributes found for the terms: mars explorers: audience not found generate_insights_response: summary: generate_insights value: jsonrpc: '2.0' id: 7 result: content: - type: text text: >- {"has_more_insights":true,"inaccessible_locations":[],"insights":[{"id":"95c35f2c-9235-4536-ad46-44867a3a5996","text":"9.5% of Gen Z are social media scrollers, making them 100% more likely to do so than the average person.","url":"https://platform.globalwebindex.com/chart-builder/insights-v2/95c35f2c-9235-4536-ad46-44867a3a5996"}],"message":"Based on the prompt social media habits, the Insights tool generated the following insights:","sources":{"audiences":[{"description":"This audience consists of individuals who are part of Gen Z.","id":"259f6394-436c-4801-b83b-bbc926e8b4b9","name":"Generation: Gen Z"}],"datasets":[{"code":"ds-core","name":"GWI Core"}],"locations":[{"code":"s2_44","name":"UK"}],"topics":["social media habits"],"waves":[{"code":"q1_2025","name":"Q1 2025"}]},"state_id":"f08cef8d-1995-4097-9d6e-0d1a5ccddd40"} structuredContent: has_more_insights: true inaccessible_locations: [] insights: - id: 95c35f2c-9235-4536-ad46-44867a3a5996 text: >- 9.5% of Gen Z are social media scrollers, making them 100% more likely to do so than the average person. url: >- https://platform.globalwebindex.com/chart-builder/insights-v2/95c35f2c-9235-4536-ad46-44867a3a5996 - id: a6b5d9a0-e0d3-486b-ac03-e09ac80e7d09 text: >- 24% of Gen Z use social media to avoid missing out on things, making them 64% more likely to do so than the average person. message: >- Based on the prompt social media habits, the Insights tool generated the following insights: sources: audiences: - description: >- This audience consists of individuals who are part of Gen Z. id: 259f6394-436c-4801-b83b-bbc926e8b4b9 name: 'Generation: Gen Z' datasets: - code: ds-core name: GWI Core locations: - code: s2_44 name: UK topics: - social media habits waves: - code: q1_2025 name: Q1 2025 state_id: f08cef8d-1995-4097-9d6e-0d1a5ccddd40 explore_insight_response: summary: explore_insight value: jsonrpc: '2.0' id: 8 result: content: - type: text text: >- {"id":"95c35f2c-9235-4536-ad46-44867a3a5996","metadata":{"attributes":[{"answer":"I am a social learner.","index":177.89999389648438,"percentage":16.899999618530273,"question":"This data is auto-generated based on responses to a variety of questions from GWI Core","sample":327,"universe_size":1737501},{"answer":"I am a Social TV Viewer.","index":130.5,"percentage":14.600000381469727,"question":"This data is auto-generated based on responses to a variety of questions from GWI Core","sample":287,"universe_size":1504625},{"answer":"I am interested in the data generated from responses to questions about memers in GWI Core.","index":193,"percentage":12.899999618530273,"question":"This data is auto-generated based on responses to a variety of questions from GWI Core","sample":248,"universe_size":1330784},{"answer":"I am a social media scroller.","index":200.39999389648438,"percentage":9.5,"question":"This data is auto-generated based on responses to a variety of questions from GWI Core","sample":185,"universe_size":978191}],"audiences":[{"description":"This audience consists of individuals who are part of Gen Z.","id":"259f6394-436c-4801-b83b-bbc926e8b4b9","title":"Generation: Gen Z"}],"datasets":[{"description":"Our primary data set on the attitudes and behaviors of digital consumers","id":"ds-core","title":"GWI Core","url":"https://help.globalwebindex.com/en/collections/11937099-gwi-core"}],"location_groups":[{"details":{"description":"Europe","locations":[{"id":"s2_44","name":"UK"}]},"group":"Europe"}],"timeframe_groups":[{"details":{"description":"2025 (Q1)","timeframes":[{"id":"q1_2025","name":"Q1 2025"}]},"group":"2025 (Q1)"}]},"text":"9.5% of Gen Z are social media scrollers, making them 100% more likely to do so than the average person.","title":"GWI Insight"} structuredContent: id: 95c35f2c-9235-4536-ad46-44867a3a5996 title: GWI Insight text: >- 9.5% of Gen Z are social media scrollers, making them 100% more likely to do so than the average person. metadata: attributes: - answer: I am a social learner. index: 177.89999389648438 percentage: 16.899999618530273 question: >- This data is auto-generated based on responses to a variety of questions from GWI Core sample: 327 universe_size: 1737501 - answer: I am a Social TV Viewer. index: 130.5 percentage: 14.600000381469727 question: >- This data is auto-generated based on responses to a variety of questions from GWI Core sample: 287 universe_size: 1504625 - answer: >- I am interested in the data generated from responses to questions about memers in GWI Core. index: 193 percentage: 12.899999618530273 question: >- This data is auto-generated based on responses to a variety of questions from GWI Core sample: 248 universe_size: 1330784 - answer: I am a social media scroller. index: 200.39999389648438 percentage: 9.5 question: >- This data is auto-generated based on responses to a variety of questions from GWI Core sample: 185 universe_size: 978191 audiences: - description: >- This audience consists of individuals who are part of Gen Z. id: 259f6394-436c-4801-b83b-bbc926e8b4b9 title: 'Generation: Gen Z' datasets: - description: >- Our primary data set on the attitudes and behaviors of digital consumers id: ds-core title: GWI Core url: >- https://help.globalwebindex.com/en/collections/11937099-gwi-core location_groups: - group: Europe details: description: Europe locations: - id: s2_44 name: UK timeframe_groups: - group: 2025 (Q1) details: description: 2025 (Q1) timeframes: - id: q1_2025 name: Q1 2025 list_datasets_response: summary: list_datasets (truncated tree) value: jsonrpc: '2.0' id: 3 result: content: - type: text text: >- {"datasets":[{"code":"ds-core","name":"GWI Core","description":"Our primary data set on the attitudes and behaviors of digital consumers","type":"dataset","children":[{"id":446,"name":"GWI Syndicated","type":"folder","children":[{"code":"ds-work","name":"GWI Work","description":"Attitudes and behaviors of business professionals in the workplace","type":"dataset"},{"id":435,"name":"GWI Pulse","type":"folder","children":[{"code":"ds-gwi-gwi-jos","name":"July 2026 Pulse Week 1 (USA)","description":"FIFA World Cup 2026, AI Saturation, NBA Finals, AI","type":"dataset"}]}]}]},{"code":"ds-usa","name":"GWI USA","description":"A 360-degree view of today's America","type":"dataset"},{"code":"ds-zqy-gyv","name":"GWI Kids","description":"Our data set on the attitudes and behaviors of kids aged 8-15.","type":"dataset"}]} structuredContent: datasets: - code: ds-core name: GWI Core description: >- Our primary data set on the attitudes and behaviors of digital consumers type: dataset children: - id: 446 name: GWI Syndicated type: folder children: - code: ds-work name: GWI Work description: >- Attitudes and behaviors of business professionals in the workplace type: dataset - id: 435 name: GWI Pulse type: folder children: - code: ds-gwi-gwi-jos name: July 2026 Pulse Week 1 (USA) description: >- FIFA World Cup 2026, AI Saturation, NBA Finals, AI type: dataset - code: ds-usa name: GWI USA description: A 360-degree view of today's America type: dataset - code: ds-zqy-gyv name: GWI Kids description: >- Our data set on the attitudes and behaviors of kids aged 8-15. type: dataset search_audiences_response: summary: search_audiences value: jsonrpc: '2.0' id: 6 result: content: - type: text text: >- {"audiences":[{"datasets":["ds-core"],"description":"","id":"d1125cd5-8384-4368-83a9-db9f9077165b","title":"Gen Z","type":"instant"}]} structuredContent: audiences: - datasets: - ds-core description: '' id: d1125cd5-8384-4368-83a9-db9f9077165b title: Gen Z type: instant tool_error_invalid_arguments: summary: validation error value: jsonrpc: '2.0' id: req-validation-1 result: isError: true content: - type: text text: 'could not validate input: insight ID is required' '401': description: Unauthorized - Invalid or missing bearer token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] components: schemas: GlobalFiltersRequest: title: global_filters description: > Resolve location and wave filters. Required before audience_generation, search_audiences (when used in the same workflow), and generate_insights. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 4 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - global_filters arguments: type: object required: - prompt properties: prompt: type: string description: > Non-empty. When the user named location and/or timeframe, include only terms needed to extract that scope. When `current_filters` is provided and new scope is requested, state whether to append or overwrite. example: social media habits of Gen Z in the UK in Q1 2025 dataset_codes: type: array description: Optional dataset codes from list_datasets (same tree). items: type: string example: - ds-core current_filters: type: object description: >- Prior successful response only — carry forward resolved names, not codes. properties: location_names: type: array items: type: string example: - UK wave_names: type: array items: type: string example: - Q1 2025 example: jsonrpc: '2.0' id: 4 method: tools/call params: name: global_filters arguments: prompt: social media habits of Gen Z in the UK in Q1 2025 AudienceGenerationRequest: title: audience_generation description: | Create platform audiences from natural-language descriptions. Call only after global_filters on the same user message. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 5 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - audience_generation arguments: type: object required: - audiences properties: audiences: type: array description: Required natural-language audience descriptions. minItems: 1 items: type: string example: - Gen Z dataset_codes: type: array items: type: string example: - ds-core location_codes: type: array description: >- Forward non-empty values from global_filters.global_filters.location_codes. items: type: string example: - s2_44 wave_codes: type: array description: >- Forward non-empty values from global_filters.global_filters.wave_codes. items: type: string example: - q1_2025 example: jsonrpc: '2.0' id: 5 method: tools/call params: name: audience_generation arguments: audiences: - Gen Z location_codes: - s2_44 wave_codes: - q1_2025 GenerateInsightsRequest: title: generate_insights description: > Generate structured audience insights. Primary discovery tool on v2beta. Pass `enforced_audiences` with UUIDs from audience_generation or search_audiences. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 7 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - generate_insights arguments: type: object required: - prompt properties: prompt: type: string description: Short, focused research question for one topic. example: social media habits dataset_codes: type: array description: >- Optional. Only when dataset scope was established earlier in the workflow. items: type: string example: - ds-core enforced_audiences: type: array description: | Optional platform audience UUIDs (max 10). Use IDs from audience_generation or search_audiences only. maxItems: 10 items: type: string format: uuid example: - 259f6394-436c-4801-b83b-bbc926e8b4b9 location_codes: type: array description: Forward from global_filters when non-empty. items: type: string example: - s2_44 wave_codes: type: array description: Forward from global_filters when non-empty. items: type: string example: - q1_2025 limit: type: integer description: >- Optional maximum insights to return (1-20). Default 10 when omitted. minimum: 1 maximum: 20 example: 5 example: jsonrpc: '2.0' id: 7 method: tools/call params: name: generate_insights arguments: prompt: social media habits enforced_audiences: - 259f6394-436c-4801-b83b-bbc926e8b4b9 location_codes: - s2_44 wave_codes: - q1_2025 limit: 5 ExploreInsightRequest: title: explore_insight description: > Deep dive into a specific insight from generate_insights. Returns structured JSON with narrative text, per-answer statistics in `metadata.attributes[]`, and provenance (audiences, datasets, locations, timeframes). Reactive-only on v2beta — call only when the user explicitly requests more detail on a specific `insights[].id`. Do not call automatically after `generate_insights`. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 8 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - explore_insight arguments: type: object required: - insight_id properties: insight_id: type: string description: >- Exact UUID from a prior generate_insights response (insights[].id). pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ example: 95c35f2c-9235-4536-ad46-44867a3a5996 example: jsonrpc: '2.0' id: 8 method: tools/call params: name: explore_insight arguments: insight_id: 95c35f2c-9235-4536-ad46-44867a3a5996 ListDatasetsRequest: title: list_datasets description: > List accessible GWI datasets and valid dataset codes for downstream tools. Returns a hierarchical tree: `type: dataset` and `type: folder` nodes, with nested `children` where present. The live response can be large; examples below are truncated. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: oneOf: - type: string - type: integer example: 3 method: type: string enum: - tools/call params: type: object required: - name properties: name: type: string enum: - list_datasets arguments: type: object description: No arguments required. example: jsonrpc: '2.0' id: 3 method: tools/call params: name: list_datasets arguments: {} SearchAudiencesRequest: title: search_audiences description: > Search saved platform audiences. Pass audiences[].id to generate_insights.enforced_audiences. Response items use `title` (not `name`) for the audience label. type: object required: - jsonrpc - id - method - params properties: jsonrpc: type: string enum: - '2.0' id: type: string example: 6 method: type: string enum: - tools/call params: type: object required: - name - arguments properties: name: type: string enum: - search_audiences arguments: type: object required: - query properties: query: type: string description: Required free-text audience search query. example: Gen Z dataset_codes: type: array items: type: string example: - ds-core exclude_audience_ids: type: array items: type: string pattern: >- ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$ limit: type: integer minimum: 1 maximum: 100 example: 5 example: jsonrpc: '2.0' id: 6 method: tools/call params: name: search_audiences arguments: query: Gen Z limit: 5 JsonRpcSuccessResponse: type: object description: > JSON-RPC 2.0 success envelope for MCP `tools/call` (no top-level `error` field). When the tool fails, HTTP status is still typically **200** and this object is returned with `result.isError: true`. Use that flag rather than HTTP status alone. required: - jsonrpc - id - result properties: jsonrpc: type: string enum: - '2.0' id: type: string description: Request identifier echoed back result: type: object description: > MCP tool result. Inspect `isError` for tool-level success or failure. **`isError: true`** — the tool failed; `content` usually has one `text` item with a human-readable explanation. Typical causes: - **Invalid arguments** (e.g. empty `prompt`, invalid UUID for `insight_id` where required). - **Downstream errors** (e.g. resource not found, timeout, cancelled request, or generic internal failure). **`_meta.isInternalError`** — when present and `true`, the server classified the failure as internal or timeout-style. Omitted or `false` for most validation and not-found style errors. This is **not** the same as a JSON-RPC protocol error: invalid `method` or malformed requests use the standard JSON-RPC `error` field instead of a tool `result`. required: - content properties: content: type: array items: type: object required: - type - text properties: type: type: string enum: - text text: type: string description: >- Tool response if successful. When `result.isError` is `true`, it is the error message (exact wording may vary; do not rely on it for branching except for documented validation cases). On success, this is typically a JSON-encoded mirror of `structuredContent`. structuredContent: type: object description: >- Typed tool output when the call succeeds. Prefer this over parsing `content[0].text`. The object shape depends on the tool that was called — see the response examples below and the Tools overview. isError: type: boolean description: >- Tool-level failure indicator. `true` means the tool did not return a successful result; read `content[0].text` (when present) for details. Optional `_meta.isInternalError` refines internal failures. _meta: type: object description: Optional MCP result metadata. properties: isInternalError: type: boolean description: >- When `true`, indicates an internal or timeout-style failure path at the server. May be omitted for other error types. ErrorResponse: type: object properties: error: type: string example: unauthorized message: type: string example: Invalid or missing bearer token code: type: integer example: 401 securitySchemes: BearerAuth: type: apiKey in: header name: Authorization description: 'Format: Bearer YOUR_TOKEN' ````