> ## Documentation Index
> Fetch the complete documentation index at: https://docs.btca.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask a question (stream)

Streams server-sent events for the query lifecycle.

## Events

SSE format:

```txt theme={null}
event: <type>
data: <json>
```

Event types:

* `meta`
* `reasoning.delta`
* `text.delta`
* `tool.updated`
* `done`
* `error`

### done

The final event is `done`. It always includes `text`, `reasoning`, and `tools`, and may include optional `usage` and `metrics`:

```json theme={null}
{
	"type": "done",
	"text": "final answer",
	"reasoning": "full reasoning",
	"tools": [],
	"usage": {
		"inputTokens": 1234,
		"outputTokens": 456,
		"reasoningTokens": 120,
		"totalTokens": 1690
	},
	"metrics": {
		"timing": { "totalMs": 5321, "genMs": 2710 },
		"throughput": {
			"outputTokensPerSecond": 168.3,
			"totalTokensPerSecond": 623.6
		},
		"pricing": {
			"source": "models.dev",
			"modelKey": "openai/gpt-4o-mini",
			"ratesUsdPerMTokens": { "input": 0.14, "output": 0.54 },
			"costUsd": { "input": 0.000173, "output": 0.000246, "total": 0.000419 }
		}
	}
}
```

Notes:

* Pricing is best-effort and may be omitted.
* Pricing rates are USD per 1M tokens from `https://models.dev/api.json`.


## OpenAPI

````yaml /api-reference/openapi.local.json POST /question/stream
openapi: 3.1.0
info:
  title: btca Local Server API
  version: 2.0.0
  description: Local HTTP API exposed by btca-server.
servers:
  - url: http://localhost:{port}
    variables:
      port:
        default: '8080'
security: []
paths:
  /question/stream:
    post:
      summary: Ask a question (SSE stream)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuestionRequest'
      responses:
        '200':
          description: >-
            Server-sent events stream. Event types: meta, reasoning.delta,
            text.delta, tool.updated, done, error. The final done event may
            include optional usage and metrics fields.
          content:
            text/event-stream:
              schema:
                type: string
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    QuestionRequest:
      type: object
      required:
        - question
      properties:
        question:
          type: string
        resources:
          type: array
          items:
            type: string
        quiet:
          type: boolean
    ErrorResponse:
      type: object
      required:
        - error
        - tag
      properties:
        error:
          type: string
        tag:
          type: string
        hint:
          type: string

````