Stream responses with Agent Spark (beta)

curl -N -X POST "https://api.globalwebindex.com/beta/spark-api/agents/spark" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "prompt": "What is Gen Z car ownership in the UK?", "dataset_code": "ds-core" }'

event: chat_init
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","message":"ChatSSE opened successfully. Let's chat!"}

event: loading
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","natural_language_response":"#### Thinking..."}

event: sources
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","topics":["car ownership"],"audiences":[],"location_groups":[],"timeframe_groups":[],"datasets":[],"attribute_codes":[],"questions":[],"namespaces":[]}

event: insights
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","insights":[{"id":"32c56b1d-3b42-4b68-a356-ab71360f6a0e","text":"11% of Gen Z car or van owners own an electric car or van.","origins":{"audiences":[{"id":"259f6394-436c-4801-b83b-bbc926e8b4b9","name":"Generation: Gen Z"}]}}]}

event: natural_language
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","natural_language_response":"Answer","sources_available":true}

event: end
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7"}

curl -N -X POST "https://api.globalwebindex.com/beta/spark-api/agents/spark" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "prompt": "What is Gen Z car ownership in the UK?", "dataset_code": "ds-core" }'

event: chat_init
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","message":"ChatSSE opened successfully. Let's chat!"}

event: loading
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","natural_language_response":"#### Thinking..."}

event: sources
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","topics":["car ownership"],"audiences":[],"location_groups":[],"timeframe_groups":[],"datasets":[],"attribute_codes":[],"questions":[],"namespaces":[]}

event: insights
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","insights":[{"id":"32c56b1d-3b42-4b68-a356-ab71360f6a0e","text":"11% of Gen Z car or van owners own an electric car or van.","origins":{"audiences":[{"id":"259f6394-436c-4801-b83b-bbc926e8b4b9","name":"Generation: Gen Z"}]}}]}

event: natural_language
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","natural_language_response":"Answer","sources_available":true}

event: end
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7"}

Agent Spark is a beta Spark API endpoint that streams a chat response as Server-Sent Events (SSE). Instead of waiting for one JSON response, you receive the answer in stages: provisional thinking text, the sources Spark used, cited insights, and a finished Markdown answer. Use Agent Spark when end users or agents ask open-ended questions and you need progress, citations, and a finished Markdown answer in one stream. The v1 /v1/spark-api/generic endpoint is a separate, narrower tool: it returns one JSON payload, but only tends to produce meaningful insights when the prompt is deliberately structured (audience, question, and often dataset or timeframe). See Structuring a Query and the Quickstart for that pattern.

Agent Spark is in beta. The request and event formats can change.

Agent Spark and `/v1/spark-api/generic`

Both endpoints accept the same core chat payload: a required prompt, plus optional chat_id, dataset_code, dataset_codes, and docked_audiences. They share authentication and the same insight engine, but they solve different product problems.

	`POST /v1/spark-api/generic`	`POST /beta/spark-api/agents/spark` (Agent Spark)
Who writes the prompt	Your integration (templates, forms, or generated text you control)	Your users or agent (free text, follow-ups, vague wording)
Prompt quality bar	High. Broad or chatty prompts often miss the mark. Plan audience + question (+ scope) as in Structuring a Query.	Lower for integrators. Spark does more interpretation inside the agent workflow.
Response shape	One JSON document when the request completes	Named SSE events until `end` or `error`
Latency UX	Wait for the full answer	`loading` events with provisional thinking text, then the final Markdown answer
Insights	JSON `insights` array with `id` and `text`	`insights` event with `id`, `text`, and audience `origins`
Sources	`sources` with `topics`, `audiences`, `datasets`, `locations`, `waves`	`sources` event with `location_groups`, `timeframe_groups`, `attribute_codes`, `questions`, `namespaces`, and richer audience metadata
Natural language	Introductory `message` plus insight bullets	`natural_language_response` (Markdown) and `sources_available`
Extra request fields	Optional `limit` (1–20)	No `limit`
Errors	Standard Spark API JSON errors	JSON before the stream, or in-band `error` with `code`, `message`, `retryable`

Choose generic for repeatable, backend-driven lookups where you invest in prompt design once. Choose Agent Spark for chat surfaces, copilots, and agents where you cannot enforce that prompt shape on every request.

Send a request

Send a POST request to /beta/spark-api/agents/spark with the same Authorization header you use for other Spark API requests. Keep the connection open to read the stream.

curl -N -X POST "https://api.globalwebindex.com/beta/spark-api/agents/spark" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "prompt": "What is Gen Z car ownership in the UK?", "dataset_code": "ds-core" }'

Request body

Field	Type	Required	Description
`prompt`	string	Yes	The chat prompt.
`chat_id`	string	No	An existing chat ID. Use it to ask a follow-up question in the same conversation.
`dataset_code`	string	No	A root dataset code that scopes the chat, for example `ds-core`.
`dataset_codes`	array of strings	No	Dataset codes from the same dataset tree. A non-empty `dataset_codes` list takes precedence over `dataset_code`.
`docked_audiences`	array of strings	No	Audience UUIDs to dock to the chat.

For more on dataset scoping, see Working with multiple data sets.

Read the stream

A successful request returns 200 with Content-Type: text/event-stream. Each frame has an event name and a JSON data payload that includes the chat_id. Events arrive in this order:

Event	Fires	Description
`chat_init`	Once, first	Confirms the stream opened and returns the `chat_id`.
`loading`	Up to three times	Provisional Markdown thinking text in `natural_language_response`. This text can differ from the final answer.
`sources`	Once	The scope of the response: `topics`, `audiences`, `location_groups`, `timeframe_groups`, `datasets`, `attribute_codes`, `questions`, and `namespaces`.
`insights`	Once	The cited insights. Each insight has an `id`, `text`, and `origins` with the audience `id` and `name`.
`natural_language`	Once	The finished Markdown answer in `natural_language_response`, plus a `sources_available` boolean.
`end`	Once, last	Marks a successful end of the stream.

event: chat_init
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","message":"ChatSSE opened successfully. Let's chat!"}

event: loading
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","natural_language_response":"#### Thinking..."}

event: sources
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","topics":["car ownership"],"audiences":[],"location_groups":[],"timeframe_groups":[],"datasets":[],"attribute_codes":[],"questions":[],"namespaces":[]}

event: insights
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","insights":[{"id":"32c56b1d-3b42-4b68-a356-ab71360f6a0e","text":"11% of Gen Z car or van owners own an electric car or van.","origins":{"audiences":[{"id":"259f6394-436c-4801-b83b-bbc926e8b4b9","name":"Generation: Gen Z"}]}}]}

event: natural_language
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","natural_language_response":"Answer","sources_available":true}

event: end
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7"}

To ask a follow-up question, send a new request with the chat_id from the stream.

Handle errors

Agent Spark reports errors in two ways, depending on whether the stream has started. Before the stream starts, the API returns a JSON error response with an HTTP status code:

Status	Meaning
`400`	Bad request.
`401`	Missing or invalid API key.
`422`	The request could not be processed, for example `invalid_request` or `audience_not_resolved`.
`429`	Rate limited (`rate_limited`).
`502`	Upstream error (`upstream_error`).
`504`	Upstream timeout (`upstream_timeout`).
`500`	Internal server error.

Agent Spark-specific errors include code, message, and retryable fields, and chat_id when you provided one:

{
  "chat_id": "e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7",
  "code": "upstream_timeout",
  "message": "upstream timeout",
  "retryable": true
}

After the stream starts, a terminal failure arrives as an error event with the same code, message, and retryable fields. No end event follows an error event, so treat error as the end of the stream.

event: error
data: {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","code":"upstream_timeout","message":"upstream timeout","retryable":true}

If retryable is true, you can retry the request.

Getting started

Agentic API

Stream responses with Agent Spark (beta)

Agent Spark and `/v1/spark-api/generic`

Send a request

Request body

Read the stream

Handle errors

​Agent Spark and /v1/spark-api/generic

​Send a request

​Request body

​Read the stream

​Handle errors

Agent Spark and `/v1/spark-api/generic`

Send a request

Request body

Read the stream

Handle errors