Sending messages & streaming

sendMessage() (Node.js) / send_message() (Python) returns a MessageTurn — an async-iterable you loop over to read tokens as Finn generates them.

Node.js

const turn = finn.sendMessage('How many active members do I have?');

for await (const chunk of turn) {
  process.stdout.write(chunk.text); // each chunk is a piece of the answer
}

Python

turn = await finn.send_message("How many active members do I have?")

async for chunk in turn:
    print(chunk.text, end="", flush=True)  # each chunk is a piece of the answer

Each chunk is a TokenChunk — text plus messageId/message_id and conversationId/conversation_id.

The final result

After the stream ends, await turn.completed for the TurnResult — the conversation id, token usage, and final state:

Node.js

const result = await turn.completed;
// {
//   conversationId: 'conv-…',
//   messageId: 'msg-…',
//   tokenUsage: { input: 412, output: 88, total: 500 },
//   turnState: 'idle',
//   interrupted: false,
// }

Python

result = await turn.completed
# TurnResult(
#   conversation_id='conv-…',
#   message_id='msg-…',
#   token_usage={'input': 412, 'output': 88, 'total': 500},
#   turn_state='idle',
#   interrupted=False,
# )

You can also get the conversation id before the stream finishes — useful for persisting it early:

Node.js

const conversationId = await turn.conversationId;

Python

conversation_id = await turn.conversation_id

Note

turn.completed fails with a FinnError if the turn breaks mid-stream. The streaming loop raises the same error, so wrap it in try/catch (Node.js) or try/except (Python). See Error handling.

Not streaming? Use ask()

If you just want the final answer in a single call, use ask() instead. It sends the message, accumulates the streamed tokens for you, and resolves once with the full text plus the turn result — no loop required.

Node.js

const { text, conversationId, tokenUsage } = await finn.ask(
  'How many active members do I have?',
);
console.log(text); // the whole answer, one shot

Python

result = await finn.ask("How many active members do I have?")
print(result.text)  # the whole answer, one shot
# result also has .conversation_id, .token_usage, ...

ask takes the same options as sendMessage/send_message (so conversationId and systemPrompt work the same way) and returns an AskResult — a TurnResult plus a text field. It fails with a FinnError if the turn breaks, exactly like the stream would.

Note

ask() is a convenience wrapper over sendMessage()/send_message() — the backend still streams under the hood; ask() just hides the token loop and hands you the final result. Reach for the streaming call when you want to render tokens live or interrupt a turn.

Want JSON? Use askJson()

For programmatic use, askJson() (Node.js) / ask_json() (Python) returns parsed JSON instead of text. It calls ask(), extracts the JSON from the answer (stripping ```json fences and any prose around it), and parses it.

Node.js

const data = await finn.askJson(`
  How many active members did I have over the last 3 months?
  Return ONLY a JSON array like [{ "month": "2026-06", "active_members": 0 }].
  No prose, no markdown.
`);
console.log(data[0].active_members); // already an object

With TypeScript you assert the shape:

type Row = { month: string; active_members: number };
const rows = await finn.askJson<Row[]>(prompt);

Python

data = await finn.ask_json(
    "How many active members did I have over the last 3 months? "
    'Return ONLY a JSON array like [{"month": "2026-06", "active_members": 0}]. '
    "No prose, no markdown."
)
print(data[0]["active_members"])  # already a Python object (list/dict)

Best-effort, parse-only

askJson()/ask_json() does not add instructions — tell Finn to return JSON in your prompt (be explicit: “JSON only, no prose”). Because Finn generates text, valid JSON isn’t guaranteed: if the answer can’t be parsed it fails with a FinnError of code invalid_json, with the raw answer on error.details.raw (Node.js) / error.details["raw"] (Python) so you can see what came back.

Interrupting a turn

Call interrupt() to ask the backend to stop generating the current turn:

Node.js

const turn = finn.sendMessage('Summarize every transaction this year…');

setTimeout(() => turn.interrupt(), 2000); // change your mind after 2s

for await (const chunk of turn) process.stdout.write(chunk.text);
const result = await turn.completed;
console.log('interrupted?', result.interrupted); // true

Python

import asyncio

turn = await finn.send_message("Summarize every transaction this year…")

loop = asyncio.get_event_loop()
loop.call_later(2, turn.interrupt)  # change your mind after 2s

async for chunk in turn:
    print(chunk.text, end="", flush=True)
result = await turn.completed
print("interrupted?", result.interrupted)  # True

The stream ends cleanly and interrupted is true/True.