> ## 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.

# Stream an Agent Spark response

> Streams a Server-Sent Events response for an Agent Spark turn.
Event order follows wire order on the connection. The `loading` events expose provisional thinking text that may differ from the final `natural_language` answer.
Pre-stream validation and upstream failures return JSON error responses. After the stream starts, terminal failures are delivered as an in-band `error` event.




## OpenAPI

````yaml post /beta/spark-api/agents/spark
openapi: 3.0.0
info:
  title: SPARK Agentic API
  description: Agent Spark streaming REST API.
  version: 1.0.0
servers:
  - url: https://api.globalwebindex.com
security: []
paths:
  /beta/spark-api/agents/spark:
    post:
      tags:
        - Chat
      summary: Stream an Agent Spark response
      description: >
        Streams a Server-Sent Events response for an Agent Spark turn.

        Event order follows wire order on the connection. The `loading` events
        expose provisional thinking text that may differ from the final
        `natural_language` answer.

        Pre-stream validation and upstream failures return JSON error responses.
        After the stream starts, terminal failures are delivered as an in-band
        `error` event.
      operationId: agentSpark
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentSparkRequest'
        description: Agent Spark request payload.
        required: true
      responses:
        '200':
          description: >
            Successful Server-Sent Events stream. Each frame is one of the
            AgentSparkStream event types. Event order follows wire order on the
            connection.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentSparkStream'
              examples:
                stream:
                  summary: Successful stream
                  value: >
                    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"}
                error:
                  summary: Terminal in-band error
                  value: >
                    event: chat_init

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


                    event: error

                    data:
                    {"chat_id":"e1a593b8-3cf0-40c3-a7a8-a3b7dc0a2bd7","code":"upstream_timeout","message":"upstream
                    timeout","retryable":true}
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '422':
          description: Unprocessable entity.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UnprocessableEntity'
                  - $ref: '#/components/schemas/AgentSparkPreStreamError'
        '429':
          description: Rate limited before the stream starts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSparkPreStreamError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
        '502':
          description: Upstream error before the stream starts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSparkPreStreamError'
        '504':
          description: Upstream timeout before the stream starts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentSparkPreStreamError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AgentSparkRequest:
      type: object
      description: Request payload for the Agent Spark stream.
      required:
        - prompt
      properties:
        prompt:
          type: string
          description: The chat prompt.
        chat_id:
          type: string
          description: Optional existing chat session ID.
        dataset_code:
          type: string
          description: >
            Optional root dataset code used to scope the chat.

            When both are provided, a non-empty dataset_codes list takes
            precedence.
          example: ds-core
        dataset_codes:
          type: array
          description: >
            Dataset codes that must belong to the same dataset tree. Takes
            precedence over dataset_code when both are provided.
          items:
            type: string
        docked_audiences:
          type: array
          description: Optional docked audience UUIDs.
          items:
            type: string
      example:
        prompt: What is Gen Z car ownership in the UK?
        dataset_code: ds-core
    AgentSparkStream:
      description: >
        One Server-Sent Events frame from POST /beta/spark-api/agents/spark. The
        `event` field is the SSE event name. `data` is the JSON object on the
        corresponding `data:` line.
      oneOf:
        - $ref: '#/components/schemas/AgentSparkInitEvent'
        - $ref: '#/components/schemas/AgentSparkLoadingEvent'
        - $ref: '#/components/schemas/AgentSparkSourcesEvent'
        - $ref: '#/components/schemas/AgentSparkInsightsEvent'
        - $ref: '#/components/schemas/AgentSparkNaturalLanguageEvent'
        - $ref: '#/components/schemas/AgentSparkEndEvent'
        - $ref: '#/components/schemas/AgentSparkErrorEvent'
    BadRequest:
      type: object
      description: Response payload for bad request.
      properties:
        code:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: The reason for the error.
      example:
        code: 400
        message: Bad request reason
    Unauthorized:
      type: object
      description: Response payload for unauthorized.
      properties:
        message:
          type: string
      example:
        message: Unauthorized
    UnprocessableEntity:
      type: object
      description: Response payload unprocessable entity.
      properties:
        code:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: The reason for the error.
      example:
        code: 422
        message: Unprocessable entity reason
    AgentSparkPreStreamError:
      type: object
      description: Public error returned before the Server-Sent Events stream starts.
      required:
        - code
        - message
        - retryable
      properties:
        chat_id:
          type: string
          description: Chat session ID from the request when provided.
        code:
          type: string
          enum:
            - invalid_request
            - audience_not_resolved
            - upstream_timeout
            - upstream_error
            - rate_limited
        message:
          type: string
        retryable:
          type: boolean
    InternalServerError:
      type: object
      description: Response payload for internal server error.
      properties:
        code:
          type: integer
          description: The HTTP status code.
        message:
          type: string
          description: Generic error reason.
      example:
        code: 500
        message: There was an error processing your request. Please try again later.
    AgentSparkInitEvent:
      title: chat_init
      description: Fires once, first. Confirms the stream opened.
      type: object
      required:
        - event
        - data
      properties:
        event:
          type: string
          enum:
            - chat_init
        data:
          $ref: '#/components/schemas/AgentSparkInitData'
    AgentSparkLoadingEvent:
      title: loading
      description: >
        Provisional thinking text. May fire up to three times before sources.
        Content can differ from the final answer.
      type: object
      required:
        - event
        - data
      properties:
        event:
          type: string
          enum:
            - loading
        data:
          $ref: '#/components/schemas/AgentSparkLoadingData'
    AgentSparkSourcesEvent:
      title: sources
      description: >
        Fires once. Scope for the whole response (topics, audiences, locations,
        timeframes, datasets, questions). chat_id is at the top of data.
      type: object
      required:
        - event
        - data
      properties:
        event:
          type: string
          enum:
            - sources
        data:
          $ref: '#/components/schemas/AgentSparkSourcesData'
    AgentSparkInsightsEvent:
      title: insights
      description: >
        Fires once. Cited insights for the response. Origins expose only
        audience id and name.
      type: object
      required:
        - event
        - data
      properties:
        event:
          type: string
          enum:
            - insights
        data:
          $ref: '#/components/schemas/AgentSparkInsightsData'
    AgentSparkNaturalLanguageEvent:
      title: natural_language
      description: >-
        Fires once. Finished Markdown answer with spark:// citation markers
        removed.
      type: object
      required:
        - event
        - data
      properties:
        event:
          type: string
          enum:
            - natural_language
        data:
          $ref: '#/components/schemas/AgentSparkNaturalLanguageData'
    AgentSparkEndEvent:
      title: end
      description: Fires once, last, on a successful stream. Carries only chat_id.
      type: object
      required:
        - event
        - data
      properties:
        event:
          type: string
          enum:
            - end
        data:
          $ref: '#/components/schemas/AgentSparkEndData'
    AgentSparkErrorEvent:
      title: error
      description: >
        Terminal in-band failure after the stream has started. There is no later
        end event on this connection.
      type: object
      required:
        - event
        - data
      properties:
        event:
          type: string
          enum:
            - error
        data:
          $ref: '#/components/schemas/AgentSparkErrorData'
    AgentSparkInitData:
      type: object
      required:
        - chat_id
        - message
      properties:
        chat_id:
          type: string
        message:
          type: string
          example: ChatSSE opened successfully. Let's chat!
    AgentSparkLoadingData:
      type: object
      required:
        - chat_id
        - natural_language_response
      properties:
        chat_id:
          type: string
        natural_language_response:
          type: string
          description: Markdown thinking trace for this loading stage.
    AgentSparkSourcesData:
      type: object
      required:
        - chat_id
      properties:
        chat_id:
          type: string
        topics:
          type: array
          items:
            type: string
        audiences:
          type: array
          items:
            $ref: '#/components/schemas/AgentSparkAudience'
        location_groups:
          type: array
          items:
            $ref: '#/components/schemas/AgentSparkLocationGroup'
        timeframe_groups:
          type: array
          items:
            $ref: '#/components/schemas/AgentSparkTimeframeGroup'
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/AgentSparkDataset'
        attribute_codes:
          type: array
          items:
            $ref: '#/components/schemas/AgentSparkAttributeCode'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/AgentSparkQuestion'
        namespaces:
          type: array
          items:
            type: string
    AgentSparkInsightsData:
      type: object
      required:
        - chat_id
        - insights
      properties:
        chat_id:
          type: string
        insights:
          type: array
          items:
            $ref: '#/components/schemas/AgentSparkInsight'
    AgentSparkNaturalLanguageData:
      type: object
      required:
        - chat_id
        - natural_language_response
        - sources_available
      properties:
        chat_id:
          type: string
        natural_language_response:
          type: string
          description: Finished Markdown answer.
        sources_available:
          type: boolean
    AgentSparkEndData:
      type: object
      required:
        - chat_id
      properties:
        chat_id:
          type: string
    AgentSparkErrorData:
      type: object
      required:
        - chat_id
        - code
        - message
        - retryable
      properties:
        chat_id:
          type: string
        code:
          type: string
          enum:
            - invalid_request
            - audience_not_resolved
            - upstream_timeout
            - upstream_error
            - rate_limited
        message:
          type: string
        retryable:
          type: boolean
    AgentSparkAudience:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        is_origin:
          type: boolean
        type:
          type: string
        is_outdated:
          type: boolean
        sample_size:
          type: integer
        universe:
          type: integer
        datapoint_percentage:
          type: number
        datasets:
          type: array
          items:
            type: string
        datasets_full:
          type: array
          items:
            $ref: '#/components/schemas/AgentSparkDataset'
    AgentSparkLocationGroup:
      type: object
      properties:
        group:
          type: string
        details:
          type: object
          properties:
            description:
              type: string
            locations:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
    AgentSparkTimeframeGroup:
      type: object
      properties:
        group:
          type: string
        details:
          type: object
          properties:
            description:
              type: string
            timeframes:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
    AgentSparkDataset:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        url:
          type: string
    AgentSparkAttributeCode:
      type: object
      properties:
        namespace_code:
          type: string
        question_code:
          type: string
        datapoint_code:
          type: string
        suffix_code:
          type: string
    AgentSparkQuestion:
      type: object
      properties:
        question_key:
          type: object
          properties:
            namespace_code:
              type: string
            question_code:
              type: string
        question_description:
          type: string
        question_name:
          type: string
    AgentSparkInsight:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        origins:
          type: object
          properties:
            audiences:
              type: array
              items:
                $ref: '#/components/schemas/AgentSparkInsightOriginAudience'
    AgentSparkInsightOriginAudience:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey

````