How to Use CosmiQ - StarTree Docs

CosmiQ can be used from the chat UI, from any MCP-compatible client, or directly against the REST API. Pick whichever fits your workflow — all three answer against the same Spaces and share the same verified-query library.

How to use it

Chat UI
MCP Tool
REST API

The easiest way to get started. Navigate to Data Portal → CosmiQ, pick a Space from the profile selector, and start asking questions.

Answers stream in token-by-token as Claude reasons through the query
A SQL side panel shows the generated query
A Plan panel shows the steps the agent took
A Tool Calls panel shows every MCP tool invocation
Rate answers 👍/👎 after each response to improve the Space’s verified-query library over time

CosmiQ exposes a text_to_sql tool over the Model Context Protocol (MCP), so it can be plugged directly into any MCP-compatible client — Claude Code, Cursor, Windsurf, or your own agent framework.Add the following to your .mcp.json:

{
  "mcpServers": {
    "cosmiq": {
      "type": "http",
      "url": "http://<cosmiq-host>/mcp"
    }
  }
}

Then call mcp__cosmiq__text_to_sql with a question and optional space parameter to ask questions without leaving your existing AI workflow.

A documented REST API with interactive Swagger/OpenAPI docs (/docs) lets you embed CosmiQ into any product or workflow. See the API Reference for the full endpoint list, request/response fields, and authentication details.Authentication: Bearer JWT (shared with the Chainlit session cookie access_token).

Getting started

Create a Space

Pick the Pinot tables you want to query and either bootstrap a Space automatically (POST /api/bootstrap/space) or create one manually via the Spaces editor.

Review the draft

The first bootstrap pass is a generated first draft. A quick human review of the business rules and relationships significantly improves accuracy — look especially for canonical metric definitions and join paths the LLM may have inferred incorrectly.

Ask questions

Use the chat UI, the MCP tool, or POST /query to start asking questions against your Space.

Rate answers

Use the 👍/👎 buttons after each answer. This is how the Space’s verified-query library grows, and how poor answers surface for review.

Promote verified queries

For your most important or frequently asked questions, add a verified query so CosmiQ always answers them the same trusted way — instant, consistent, and no additional LLM cost on cache hits.

Things to know

CosmiQ is read-only. It executes only SELECT queries and does not modify, insert, or delete data. Read-only mode, row limits, and query timeouts are all enforced via Space policy. See Security and Compliance for the full guardrail model.

Accuracy improves with Space quality. Internal benchmarking on real-world cost-analytics questions has shown roughly 90% first-try answer accuracy on numeric questions, with continued improvement as verified queries accumulate. The more curated your Space’s business rules and the more verified queries it contains, the better and faster CosmiQ answers.

Complex or open-ended questions that require judgment calls not covered by any business rule may take longer or require follow-up. Adding a verified query for that pattern once you have the right SQL makes future answers instant and consistent.

CosmiQ Overview

What CosmiQ is, how Spaces work, and how a question gets answered end to end.

API Reference

Full REST endpoint reference and system defaults.

​How to use it

​Getting started

​Things to know

​Related documentation

CosmiQ Overview

API Reference

How to use it

Getting started

Things to know

Related documentation