Answers, data, and links
Understand routed answers, deterministic results, and authenticated channel links.
Twin queries have two explicit result shapes. A natural-language question is a session query; a typed records, aggregate, or saved-view intent is deterministic.
Session query states
| State | Meaning | What the client should do |
|---|---|---|
queued | The Twin accepted the question | Poll again |
running | The canonical session router is working | Poll again |
completed | The answer is ready | Present the answer and permitted channel links |
failed | Execution ended with a typed error | Show the safe error and query ID |
cancelled | The query was cancelled | Stop polling |
Keep the query, task, and session IDs available for support. The public result does not expose internal run events, prompts, model configuration, SQL, or relations.
Receive progress updates
The CLI normally waits quietly for the terminal result. Use twin query --stream to receive newline-delimited query.queued, query.running, and
terminal events, so a coding agent can keep the user informed. Intermediate
events contain only query, task, and session identifiers; the full governed
result is emitted once, at completion, to avoid repeatedly consuming agent
context.
REST and MCP clients create the query and poll its query ID. The TypeScript SDK
can report the same observed lifecycle through onUpdate, or a client can use
the lower-level create and get methods. There is no public token or reasoning
stream: these interfaces expose query status and the final governed result
only.
Deterministic results
A deterministic query completes in its create response. It contains bounded
data.rows and a complete marker. Every object type and field is validated
against the selected channel before the server compiles a parameterised query.
Saved-view queries instead evaluate the inspected view and optional widget IDs
through the same server-owned dashboard engine as the web app.
Deterministic does not mean unrestricted: the caller cannot supply raw SQL, tenant or organisation IDs, internal relations, or product selection.
Feedback
An assistant can submit feedback that you provide or confirm. Include a routed session query ID when the feedback concerns a particular answer; MLX verifies that the signed-in user can access that query before attaching its session and run context. General Twin feedback does not require a query ID.
Agents should not infer feedback from ordinary conversation or submit it without the user's knowledge. Deterministic queries are not persisted as sessions, so their result IDs cannot be used as feedback query IDs.
Links back to your workspace
A completed session answer can include an authenticated link to a supporting Twin Channel. The link appears only when the server can resolve an accessible, active channel for the result.
Opening the link requires normal workspace authentication. Copying the URL to another person does not grant them access.