Streaming

curl -N https://api.pramaan.dev/v1/capabilities/llm.chat \
  -H "Authorization: Bearer $PRAMAAN_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Say hello."}]}'

event: text_delta
data: {"text":"Hel"}

event: text_delta
data: {"text":"lo."}

event: usage
data: {"inputTokens":12,"outputTokens":3}

event: done
data: {"finishReason":"stop","result":{"text":"Hello.","toolCalls":[],"finishReason":"stop","usage":{"inputTokens":12,"outputTokens":3}},"price_micro":1000}

​

With the SDK

import { Pramaan } from "@pramaan/sdk";

const p = new Pramaan({ apiKey: process.env.PRAMAAN_API_KEY! });

let shown = "";
for await (const event of p.stream("llm.chat", {
  messages: [{ role: "user", content: "Say hello." }],
})) {
  if (event.type === "text_delta") {
    shown += event.text;
    render(shown);
  }
  if (event.type === "done") save(event.result); // the whole reply, as p.run returns it
}

​

Events

​

What to know

• Tools and JSON output work the same. Tool arguments and JSON-schema output are checked when the reply is complete. If the check fails (the JSON does not match, or the reply was cut off at maxTokens) you get an error event after the pieces, and the reply is charged: you received it. The plain call makes the same failure free because it returns nothing.
• Errors before the first piece are plain JSON with the usual status (400, 402, 429 and so on), not an event stream. Check the status before you read events.
• Price. A finished reply costs what the plain call costs; the price is price_micro in done (there is no price header on a stream). If the reply breaks after pieces were sent, or you disconnect, you pay for what was generated, never more than the estimate. When the break leaves no token count, the charge is a ceiling: your input at the estimate’s bound and one token per byte sent. That can be more than the finished reply would have cost, so let a reply finish when you can. A call that sent nothing costs nothing. The estimate is held from your credit while the stream is open.
• Idempotency. A repeated Idempotency-Key returns the stored reply as plain JSON, not a stream; while the first is still running it answers 409. A reply that broke is not stored, so the same key runs, and is charged, again.
• Limits. A stream is stopped after 120 seconds, or after 50 seconds when the call carries an Idempotency-Key. An organisation may have 20 streams open at once; one more answers 429. Nothing is sent until the first piece is ready, which can take several seconds.
• Disconnecting stops the reply.
• MCP returns the whole reply; it does not stream.