# ScaledThought

> Headless inference for open-weight models. Free to start. Day-zero model access, task benchmarks on arrival, a cost-aware router, and US or Canadian hosting by default. Sign up, pay, and operate entirely through your agent.

You are reading the agent surface of this site. There is no dashboard: signup, keys, budgets, billing and inference all work through the CLI, the API and the MCP server described below.

## Setup protocol

If your human asked you to set them up on ScaledThought, follow these steps in order. Every command is non-interactive. It prints one JSON object on stdout and exits 0. On failure it prints `{"error":{"code","message","hint"}}` on stderr and exits non-zero; look the code up in [Errors](#errors).

### 1. Pick the home region

- If the human named a country or region, use it: Canada is `ca`, the US is `us`.
- Otherwise, if the data could be Canadian-regulated (Canadian personal, health or financial data; PIPEDA, Quebec Law 25, provincial health privacy laws), ask one question and use the answer: "Should your data stay in Canada (ca) or the US (us)?"
- Otherwise use `us` without asking.
- The region is permanent. Prompts, completions, logs and billing records stay in that country. Keys start with `st_us_` or `st_ca_`, and that prefix decides where every request goes.

### 2. Create the account

Run this in the human's project directory, where their code will read `.env`:

```bash
npx -y scaledthought@latest init --region us   # or --region ca
```

Success: exit code 0 and JSON with `"already_initialized": false`, `account_id`, `region`, `plan: "free"`, `base_url`, `free_tier`, `newest_models`, `suggested_model` and `next_steps`. It also:

- writes `ST_API_KEY` and `ST_BASE_URL` to `./.env` (mode 0600), keeping any other lines;
- adds `.env` to `./.gitignore`;
- never prints the key. Don't print it, paste it into chat or commit it.

Re-running is safe. If `ST_API_KEY` is already set (in the environment or `./.env`), init creates nothing and returns the existing account with `"already_initialized": true`. Use that account. If it exits with `region_mismatch`, a key from the other region already exists: ask the human before doing anything else.

### 3. Pick a model that is live in the region

The [Models](#models) table below is the catalog. Not every model is live in every region, so pick from what is live right now:

```bash
npx -y scaledthought@latest models --live
```

Success: a JSON array, newest first. Each item has `id`, `category`, `live: true` and prices. Use the first item whose `category` isn't `embedding` (init's `suggested_model` is the same pick). Without the CLI, `GET $ST_BASE_URL/models` returns the live model ids in OpenAI list format (no auth needed).

### 4. Verify with one real completion

```bash
set -a; . ./.env; set +a   # load ST_API_KEY and ST_BASE_URL
curl -sS "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"<id from step 3>","max_tokens":32,"messages":[{"role":"user","content":"Reply with OK"}]}'
```

Success: HTTP 200, a non-empty `choices[0].message.content`, and a `usage` object. Then do the same with `"model":"auto"`: the router picks the cheapest live model that clears `quality_floor` (default 0.8), and the `x-st-routed-to` response header names it. The CLI does the same in one step:

```bash
npx -y scaledthought@latest chat -m auto "Reply with OK"   # JSON: model, routed_to, region, text, usage
```

### 5. Optional: connect MCP

Only if the human wants account tools (usage, keys, budgets, billing) inside their MCP client. MCP needs a key, so it comes after step 2.

```bash
npx -y scaledthought@latest mcp
```

Success: JSON with `url` (the region's `/mcp`), `claude_code` (a ready `claude mcp add --transport http scaledthought … --header "Authorization: Bearer $ST_API_KEY"` command) and `json_config` for other clients. Run `claude_code` in a shell where `ST_API_KEY` is loaded (see step 4), because the shell expands it.

### 6. Tell the human

Report in a few lines:

- **Region**: `us` or `ca`, and that their data stays in that country.
- **Plan**: free tier. $1/day of inference across the account, 60 requests/min per key, up to 5 keys, no card.
- **Key**: in `./.env` as `ST_API_KEY` (gitignored), with `ST_BASE_URL`. Any OpenAI SDK works with those two values.
- **Verified**: which model answered, from step 4.
- **Upgrade**: when they need more, run `npx -y scaledthought@latest billing upgrade --monthly-cap-usd <n>`. It returns an `approval_url` for the human to open, add a card and approve the cap. Nothing is charged beyond the cap.

## Use it from code

OpenAI-compatible. Read the base URL from `ST_BASE_URL`; don't hard-code a region's host.

```python
import os
from openai import OpenAI  # pip install openai; load .env first, e.g. python-dotenv's load_dotenv()

client = OpenAI(base_url=os.environ["ST_BASE_URL"], api_key=os.environ["ST_API_KEY"])
resp = client.chat.completions.create(
    model="auto",  # or a live model id
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={"quality_floor": 0.8},  # optional, auto only
)
print(resp.choices[0].message.content)
```

```ts
import OpenAI from "openai"; // npm i openai

process.loadEnvFile(); // Node 20.12+: reads ./.env
const client = new OpenAI({ baseURL: process.env.ST_BASE_URL, apiKey: process.env.ST_API_KEY });
const resp = await client.chat.completions.create({
  model: "auto", // or a live model id
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);
```

```bash
curl -sS "$ST_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ST_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"auto","quality_floor":0.85,"messages":[{"role":"user","content":"hi"}]}'
```

Streaming (`stream: true`), tools, `response_format` and embeddings (`POST $ST_BASE_URL/embeddings` with an embedding model) use the OpenAI request shapes. Requests without `max_tokens` get a default cap.

## Errors

API errors are `{"error":{"message","type","code"}}` with the HTTP status below. CLI errors are `{"error":{"code","message","hint"}}` on stderr; for API failures the CLI passes the API's `code` through and adds `status` (and `retry_after` or `base_url` when present).

| status | code | from | what to do |
|---|---|---|---|
| 400 | `invalid_request` | API | Fix the field named in message. Don't retry unchanged. |
| 400 | `invalid_body` | API | Fix the field named in message. Don't retry unchanged. |
| 400 | `invalid_json` | API | Send valid JSON with `content-type: application/json`. |
| 401 | `invalid_api_key` | API | Key missing, mistyped or revoked. Load ST_API_KEY from .env; don't create a new account. |
| 401 | `missing_api_key` | API | Send `Authorization: Bearer $ST_API_KEY`. |
| 402 | `budget_exceeded` | API | This key's daily budget is spent. Resets 00:00 UTC. Tell your human; don't retry now. |
| 402 | `daily_cap_exceeded` | API | Free tier's $1/day account cap is spent. Resets 00:00 UTC, or upgrade (see below). |
| 402 | `monthly_cap_exceeded` | API | Monthly cap reached. Ask your human to approve a higher one: `billing upgrade --monthly-cap-usd <higher>`. |
| 402 | `free_tier_key_limit` | API | Free accounts have 5 active keys. Revoke one (`keys revoke <id>`) or upgrade. |
| 402 | `free_tier_limit` | API | Free keys can't raise budgets or rate limits. Upgrade first. |
| 402 | `batches_require_paid` | API | Batches need a paid plan. Upgrade, then retry. |
| 402 | `fine_tuning_requires_paid` | API | Fine-tuning needs a paid plan. Upgrade, then retry. |
| 403 | `insufficient_scope` | API | This key lacks the scope. Use the default key from init. |
| 403 | `account_suspended` | API | Stop. Tell your human to email hello@scaledthought.com. |
| 404 | `model_not_found` | API | Not live here. Pick an id from `models --live` or `GET $ST_BASE_URL/models`, or use auto. |
| 404 | `not_found` | API | Wrong path. ST_BASE_URL already ends in /v1; append /chat/completions. |
| 421 | `wrong_region` | API | The key belongs to the other region. Use the `base_url` in the error body; remove any hard-coded host. |
| 429 | `rate_limit_exceeded` | API | Wait `Retry-After` seconds, then retry. |
| 502 | `upstream_error` | API | Transient. Retry with backoff, or use model auto. |
| 503 | `service_unavailable` | API | Transient. Retry in a few seconds. |
| exit 1 | `no_key` | CLI | No ST_API_KEY in the environment or ./.env. Run init in the project directory. |
| exit 1 | `region_mismatch` | CLI | A key from the other region already exists here. Use it, or ask your human before creating a second account elsewhere. |
| exit 1 | `wrong_region_endpoint` | CLI | ST_BASE_URL / ST_API_URL points at the other region. Unset it. Nothing was sent. |
| exit 1 | `network_error` | CLI | Couldn't reach the API. Check the network, then retry. |
| exit 1 | `bad_region` | CLI | Use `--region us` or `--region ca`. |
| exit 2 | `usage_error` | CLI | Unknown command, flag or missing argument. Run the command with --help. |

Upgrading: `billing upgrade --monthly-cap-usd <n>` (CLI), `POST /v1/billing/upgrade {"monthly_cap_usd": n}` (API) or `billing_upgrade` (MCP) returns an `approval_url`. Give it to the human; limits rise as soon as they approve.

## Models

**This is the catalog, not what is live.** Check live models with `npx -y scaledthought@latest models --live` or `GET $ST_BASE_URL/models`. New open-weight models go live within 24h of weights being published, or the month is free. AA Index = Artificial Analysis Intelligence Index v4.3.2 (Sep 23, 2026). Prices are USD per 1M tokens. One model's detail: `GET /v1/models/<id>` or https://scaledthought.com/models/<id>.

| id | lab | weights released | params (total/active) | context | AA Index | $ in | $ cached in | $ out |
|---|---|---|---|---|---|---|---|---|
| mimo-v2-6-pro | Xiaomi | 2026-09-22 | 1.0T / 42B | 1,000,000 | 46 | $0.43 | - | $0.87 |
| deepseek-v4-1-flash | DeepSeek | 2026-09-10 | 552B / 16B | 1,000,000 | 39 | $0.22 | $0.007 | $0.66 |
| k2-horizon-375b-a23b | IFM | 2026-09-03 | 375B / 23B | 524,288 | 31 | $0.50 | - | $0.50 |
| glm-5-3 | Z.ai | 2026-08-29 | 753B / 40B | 1,000,000 | 45 | $1.40 | $0.26 | $4.40 |
| tencent-hy4-preview | Tencent | 2026-08-28 | 770B / 49B | 1,000,000 | - | $0.834 | $0.042 | $2.50 |
| glm-5-3-flash | Z.ai | 2026-08-26 | 320B / 18B | 1,000,000 | 42 | $0.15 | $0.03 | $0.50 |
| qwen3-8-27b | Alibaba | 2026-08-14 | 27.8B | 262,144 | 34 | $0.15 | - | $1.88 |
| deepseek-v4-pro | DeepSeek | 2026-08-13 | 1.6T / 49B | 1,000,000 | 36 | $1.32 | $0.044 | $3.96 |
| qwen3-8-2-4t-a95b | Alibaba | 2026-08-12 | 2.4T / 95B | 984,000 | 40 | $2.00 | $0.25 | $6.00 |
| muse-glimmer | Meta | 2026-08-10 | 30B | - | 17 | $0.35 | $0.04 | $1.50 |
| kimi-k3 | Moonshot AI | 2026-07-27 | 2.8T / 104B | 1,048,576 | 44 | $3.00 | $0.30 | $15.00 |
| inkling | Thinking Machines | 2026-07-15 | 975B / 41B | 1,000,000 | 25 | $1.00 | $0.17 | $4.05 |
| nemotron-3-ultra-550b-a55b | NVIDIA | 2026-06-04 | 550B / 55B | - | 23 | $0.60 | $0.12 | $2.40 |
| minimax-m3 | MiniMax | 2026-06-01 | 428B / 23B | 1,000,000 | 29 | $0.30 | $0.06 | $1.20 |
| gemma-4-31b | Google DeepMind | 2026-04-02 | 31B | 262,144 | 19 | $0.09 | $0.05 | $0.34 |
| mistral-small-4 | Mistral AI | 2026-03-16 | 119B / 6B | 262,144 | - | $0.15 | - | $0.60 |
| mistral-large-3 | Mistral AI | 2025-12-01 | 675B | 262,144 | - | $0.50 | - | $1.50 |
| olmo-3-32b | Ai2 | 2025-11-20 | 32B | - | - | $0.90 | - | $0.90 |
| gpt-oss-120b | OpenAI | 2025-08-05 | 117B / 5.1B | 131,072 | - | $0.15 | $0.015 | $0.60 |
| qwen3-embedding-8b | Alibaba | 2025-06-05 | 8B | 32,768 | - | $0.10 | - | - |
| llama-4-maverick | Meta | 2025-04-05 | 400B / 17B | 1,000,000 | - | $0.27 | - | $0.85 |

## Pricing

Free tier: $1/day of inference on any live model (account-wide), 60 requests/min per key, up to 5 keys, no card. Batches and fine-tuning need a paid plan. After upgrading, pay as you go at each model's per-token price (USD per 1M tokens), up to the monthly cap your human approved. Same price in both regions. Cached input is billed at the model's cached rate. No router fee: model "auto" bills at the price of the model that served the request.

## Router

Set `model: "auto"` and an optional `quality_floor` (0 to 1, default 0.8). The router classifies the task, then picks the cheapest live model whose benchmark score for that task clears the floor, or the best-scoring one if none does. Auto responses carry `x-st-routed-to` (the model) and `x-st-reason`; every inference response carries `x-st-region` and `x-st-request-id`. Pass a model id instead to pin.

## MCP server

Remote MCP at `https://api.{us|ca}.scaledthought.com/mcp` (Streamable HTTP, 2026-07-28), authenticated with your API key as a bearer token. **MCP can't create accounts**: sign up first with `npx -y scaledthought@latest init` or `POST /v1/accounts`, then run `npx -y scaledthought@latest mcp` for the exact config. Inference stays on the OpenAI-compatible API. Tools:

- `account_status`: Plan, region, spend today and this month, key count, how to upgrade. Call it first.
- `keys_manage`: List, create or revoke keys (action: list | create | revoke). Create returns the full key once.
- `budget_manage`: Set or clear a key's hard daily budget (USD) and rate limits.
- `models_search`: Models with prices, context, benchmarks and live status in your region (live_only, category, search).
- `benchmarks_get`: Our own per-task scores and speed for one model.
- `usage_query`: Requests, tokens and cost over the last N days, by model, day or key.
- `billing_upgrade`: With monthly_cap_usd: an approval_url for your human. With no arguments: billing status.
- `fine_tuning`: List, get, cancel fine-tuning jobs and their events; list your fine-tuned models.
- `docs_search`: Where the docs, llms.txt and your base URL are.

## Batches, fine-tuning, billing

- **Batch inference**: OpenAI-compatible Files + Batches (`POST /v1/files` purpose=batch, `POST /v1/batches`). 50% of the normal price, results within 24h. Paid plans. CLI: `npx -y scaledthought@latest batches create requests.jsonl`.
- **Fine-tuning (LoRA)**: `POST /v1/files` purpose=fine-tune (chat JSONL, at least 10 examples), then `POST /v1/fine_tuning/jobs`. Fine-tunable base models: `qwen3-8-27b`, `gemma-4-31b`, `olmo-3-32b`, `muse-glimmer`, `gpt-oss-120b`, `mistral-small-4`. The resulting model is private to your account and billed at its base model's price. Paid plans. CLI: `npx -y scaledthought@latest fine-tune create examples.jsonl --model qwen3-8-27b`.
- **Billing**: the free tier needs no card. `POST /v1/billing/upgrade {"monthly_cap_usd": n}` returns an `approval_url` for your human; after approval, limits rise and nothing is charged beyond the cap. Lowering the cap needs no approval.
- **OpenAPI**: the control-plane spec is at `/openapi.json` on your region's API host.

## Hosting and data

- Two regions, each with its own API host: `https://api.us.scaledthought.com/v1` and `https://api.ca.scaledthought.com/v1`. `ST_BASE_URL` in `.env` is already the right one.
- Every key is pinned to `us` or `ca`. Requests are served, logged and billed only in that country. A key sent to the other region's host gets `421 wrong_region` and the body is never read.
- Zero data retention by default. Prompts and outputs are never logged or used for training.

## CLI reference

`npx -y scaledthought@latest <command>`. Output is JSON whenever stdout isn't a terminal (or with `--json`). Keys come from `ST_API_KEY` or `./.env`, never from flags. `--help` works on every command.

- `init --region us|ca`: Free account (no card). Writes ST_API_KEY and ST_BASE_URL to .env. Safe to re-run.
- `models --live`: Models serving in your region now, newest first. Filter with --category or --search.
- `models <id>`: Pricing, context, benchmarks and live status for one model.
- `chat -m auto "prompt"`: Send one message. -m <id> pins a model; auto lets the router pick.
- `account`: Plan, region, spend today and this month.
- `keys create --name <name> --budget-usd 5`: New key with a hard daily budget in USD. The key is printed once.
- `keys list`: Your keys (prefixes only).
- `keys revoke <id>`: Revoke a key.
- `usage --days 7 --by model`: Requests, tokens and cost by model, day or key.
- `billing upgrade --monthly-cap-usd 50`: Returns an approval_url for your human. Only needed past the free tier.
- `billing status`: Plan, monthly cap and spend.
- `batches create requests.jsonl`: Upload a JSONL file and start a batch at 50% off. Paid plans.
- `fine-tune create examples.jsonl --model <base-id>`: Upload a dataset and start a LoRA job. Paid plans.
- `mcp`: Prints the `claude mcp add` command and JSON config for your region.
- `status`: Per-model health in your region over the last hour.

## API endpoints

On your region's host (`$ST_BASE_URL` is `https://api.{us|ca}.scaledthought.com/v1`). Authenticate with `Authorization: Bearer $ST_API_KEY` unless noted.

- `POST /v1/accounts`: Create a free account in this host's region. Returns api_key (once) and base_url. No auth.
- `POST /v1/chat/completions`: Chat, tools, JSON output, streaming. OpenAI-compatible. model: auto routes.
- `POST /v1/completions`: Raw text completion.
- `POST /v1/embeddings`: Embeddings for embedding models.
- `GET /v1/models`: Model ids live in this region (OpenAI list format). No auth.
- `GET /v1/models/{id}`: One model: pricing, context, benchmarks and live_in_region. No auth.
- `GET /v1/models/{id}/benchmarks`: Our own per-task scores and speed.
- `GET /v1/account`: Plan, region, spend and key count.
- `GET /v1/keys`: List keys.
- `POST /v1/keys`: Create a key with an optional daily_budget_usd.
- `PATCH /v1/keys/{id}`: Change a key's name, daily budget or rate limits.
- `DELETE /v1/keys/{id}`: Revoke a key.
- `GET /v1/usage`: Requests, tokens and cost (days, group_by).
- `GET /v1/billing`: Plan, cap and spend.
- `POST /v1/billing/upgrade`: Get an approval_url for a monthly cap (or lower an existing cap).
- `POST /v1/files`: Upload JSONL (purpose=batch or fine-tune).
- `POST /v1/batches`: Start a batch. GET /v1/batches/{id} to poll, POST /v1/batches/{id}/cancel to stop.
- `POST /v1/fine_tuning/jobs`: Start a LoRA job from an uploaded purpose=fine-tune file.
- `GET /v1/status`: Per-model health in this region, last hour.

Human docs: https://scaledthought.com/docs