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

# How to Use CosmiQ

> Chat UI, MCP tool, and REST API walkthroughs, plus how to set up your first Space.

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**

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

**MCP Tool**

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`:

```json theme={null}
{
  "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.

**REST API**

A documented REST API with interactive Swagger/OpenAPI docs (`/docs`) lets you embed CosmiQ into any product or workflow. See the [API Reference](https://docs.startree.ai/corecapabilities/ai/cosmiq/api-reference.md) for the full endpoint list, request/response fields, and authentication details.

Authentication: Bearer JWT (shared with the Chainlit session cookie `access_token`).

***

## Getting started

**1. 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.

**2. 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.

**3. Ask questions**

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

**4. 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.

**5. 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

> [!NOTE]
>
> 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](https://docs.startree.ai/corecapabilities/ai/cosmiq/security-and-compliance.md) for the full guardrail model.

> [!TIP]
>
> 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.

> [!NOTE]
>
> 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.

***

## Related documentation

> **[CosmiQ Overview](https://docs.startree.ai/corecapabilities/ai/cosmiq/overview.md)**
>
> What CosmiQ is, how Spaces work, and how a question gets answered end to end.

> **[API Reference](https://docs.startree.ai/corecapabilities/ai/cosmiq/api-reference.md)**
>
> Full REST endpoint reference and system defaults.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.