Quickstart

Go from zero to a fine-tuned model in a handful of commands. This guide walks through a real example — a customer support bot — using the open-source tt CLI. REST API equivalents are shown under each step for programmatic use.

Prerequisites

A Tuned Tensor account
An API key (create one in Dashboard → Settings → API Keys)
Node.js 18+ (for the CLI)

Install the CLI and authenticate:

npm install -g @tuned-tensor/cli
tt auth login tt_your_api_key
tt auth status

The CLI is open source (MIT) — github.com/tunedtensor/tuned-tensor-cli. See the CLI Tool reference for every command. Prefer curl? Jump to Using the REST API.

Step 1: Create a Behaviour Spec

A behaviour spec defines what your model should do. Scaffold one locally with tt init, edit it, then push it to Tuned Tensor:

tt init --name "Customer Support Bot" \
  --model Qwen/Qwen2.5-7B-Instruct-Turbo

This creates tunedtensor.json. Open it and fill in guidelines, constraints, and examples:

{
  "name": "Customer Support Bot",
  "description": "Handles billing, account, and technical support questions",
  "system_prompt": "You are a helpful customer support agent for Acme SaaS...",
  "guidelines": [
    "Keep responses under 150 words",
    "Always acknowledge the user concern before providing a solution",
    "Use bullet points for multi-step instructions"
  ],
  "constraints": [
    "Never promise refunds without directing to the refund policy",
    "Do not make up pricing — refer to the pricing page"
  ],
  "examples": [
    {
      "input": "How do I cancel my subscription?",
      "output": "I understand you would like to cancel. Go to Settings > Billing > Cancel Plan."
    },
    {
      "input": "I was charged twice this month",
      "output": "I am sorry about the double charge. Please contact billing@acme.com."
    },
    {
      "input": "How much does the Pro plan cost?",
      "output": "For up-to-date pricing, please check acme.com/pricing."
    },
    {
      "input": "My dashboard is loading slowly",
      "output": "Try clearing your cache, using a different browser, or incognito mode."
    },
    {
      "input": "Can I get a refund?",
      "output": "Please review our refund policy at acme.com/refund-policy."
    }
  ],
  "base_model": "Qwen/Qwen2.5-7B-Instruct-Turbo"
}

Push it to the API:

tt push

The CLI prints the spec id — save it for the next step (you can also list your specs any time with tt specs list).

Equivalent REST call

curl -X POST https://api.tunedtensor.com/v1/behavior-specs \
  -H "Authorization: Bearer tt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "description": "Handles billing, account, and technical support questions",
    "system_prompt": "You are a helpful customer support agent for Acme SaaS...",
    "guidelines": [
      "Keep responses under 150 words",
      "Always acknowledge the user concern before providing a solution",
      "Use bullet points for multi-step instructions"
    ],
    "constraints": [
      "Never promise refunds without directing to the refund policy",
      "Do not make up pricing — refer to the pricing page"
    ],
    "examples": [
      {
        "input": "How do I cancel my subscription?",
        "output": "I understand you would like to cancel. Go to Settings > Billing > Cancel Plan."
      }
    ],
    "base_model": "Qwen/Qwen2.5-7B-Instruct-Turbo"
  }'

The response includes the spec id:

{
  "data": {
    "id": "cafd8799-9180-482e-b0b2-c46d08e4b045",
    "name": "Customer Support Bot",
    "base_model": "Qwen/Qwen2.5-7B-Instruct-Turbo",
    "examples": [ ... ],
    "guidelines": [ ... ],
    "constraints": [ ... ],
    "created_at": "2026-03-06T08:27:33.492Z"
  }
}

Step 2: Start a Run

A run compiles your spec into training data, augments your 5 examples into ~36 diverse training rows using AI, fine-tunes the model, and auto-evaluates the result. New accounts start at a zero balance, so add credits before your first run. Runs reserve their estimated cost at start, so use available credits, not total balance, to decide whether another run can start. If your available balance is too low, POST /runs returns 402 insufficient_credits with the required and available amounts; top up at Dashboard → Billing or run tt topup.

tt runs start cafd8799-... --epochs 4 --lora-rank 8 --lora-alpha 16

The CLI returns immediately with the new run id and the status preparing.

Equivalent REST call

curl -X POST https://api.tunedtensor.com/v1/behavior-specs/cafd8799-.../runs \
  -H "Authorization: Bearer tt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "augment": true,
    "hyperparameters": {
      "n_epochs": 4,
      "lora_rank": 8,
      "lora_alpha": 16
    }
  }'

{
  "data": {
    "id": "e0b7694b-2c65-4199-89a1-fc54a6a6010c",
    "run_number": 1,
    "status": "preparing",
    "spec_snapshot": { ... },
    "hyperparameters": { "augment": true, "n_epochs": 4, "lora_rank": 8 }
  }
}

Behind the scenes, the platform:

Compiles your spec into JSONL training format
Augments your examples into ~36 diverse training rows using Claude
Uploads the dataset to Together AI
Starts a LoRA fine-tuning job

Step 3: Check Run Status

Watch a run until it reaches a terminal state — the CLI polls and streams status transitions:

tt runs watch e0b7694b-...

For one-shot status, use:

tt runs get e0b7694b-...

Equivalent REST call

curl https://api.tunedtensor.com/v1/runs/e0b7694b-... \
  -H "Authorization: Bearer tt_your_api_key"

The run moves through these statuses:

Status	What's happening
`preparing`	Compiling spec, augmenting examples, uploading dataset
`training`	Fine-tuning in progress on Together AI
`evaluating`	Auto-evaluating the fine-tuned model against your spec
`completed`	Done — eval results are available
`failed`	Something went wrong — check the `error` field

When completed, tt runs get (or the REST response) includes eval results:

{
  "data": {
    "status": "completed",
    "eval_summary": {
      "total": 5,
      "avg_score": 0.82,
      "pass_rate": 0.8,
      "scoring_method": "llm_judge",
      "regressions": 0
    },
    "_evals": [
      {
        "prompt": "Can I get a refund?",
        "expected": "Please review our refund policy...",
        "actual": "I understand you're looking for a refund...",
        "score": 0.9,
        "passed": true,
        "reasoning": "Correctly directs to the refund policy..."
      }
    ]
  }
}

Step 4: Test in the Playground

Before iterating on your spec, test the fine-tuned model interactively in the Playground. You can compare it against the base model to see the effect of fine-tuning.

Note: Playground commands are not yet available in the CLI. Use the dashboard Playground, or the REST endpoints below.

Using the REST API

# List available models (base + your fine-tuned models)
curl https://api.tunedtensor.com/v1/playground/models \
  -H "Authorization: Bearer tt_your_api_key"

# Run inference against your fine-tuned model
curl -X POST https://api.tunedtensor.com/v1/playground/completions \
  -H "Authorization: Bearer tt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-fine-tuned-model-id",
    "messages": [
      { "role": "system", "content": "You are a helpful customer support agent for Acme SaaS..." },
      { "role": "user", "content": "How do I cancel my subscription?" }
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

The response includes the generated text, latency, and token usage:

{
  "data": {
    "content": "I understand you would like to cancel your subscription. You can do so by going to Settings > Billing > Cancel Plan...",
    "latency_ms": 645,
    "usage": {
      "prompt_tokens": 42,
      "completion_tokens": 38
    }
  }
}

Or use the dashboard: go to Playground, enable Compare mode, select the base model and your fine-tuned model, and run the same prompt side by side.

Step 5: Iterate

Review the eval results. If some examples failed, update your local tunedtensor.json with better examples or clearer guidelines, then push and kick off another run:

# Edit tunedtensor.json to add/change examples, guidelines, etc.

tt push
tt runs start cafd8799-...

Equivalent REST call

# Update the spec with a new example
curl -X PUT https://api.tunedtensor.com/v1/behavior-specs/cafd8799-... \
  -H "Authorization: Bearer tt_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "examples": [
      ...existing examples...,
      {
        "input": "How do I change my email address?",
        "output": "Go to Settings > Profile > Email and verify the new address."
      }
    ]
  }'

# Start another run
curl -X POST .../v1/behavior-specs/cafd8799-.../runs \
  -d '{"augment": true}'

Run #2 will be automatically compared to Run #1. The eval summary shows regressions (examples that got worse) and improvements.

Using the REST API

Every tt command maps to a REST endpoint under https://api.tunedtensor.com/v1. All endpoints accept Authorization: Bearer tt_your_api_key.

Behaviour Specs — create, list, get, update, delete
Runs — start, list, get, cancel
Datasets — upload, list, delete
Models — list, get, delete
Playground — list models, run completions
Authentication — API keys, response format

What's Next

CLI Tool — full command reference, local evals, and configuration
Behaviour Specs — full schema and endpoints
Runs — cancellation, eval results, regression detection
Playground — test and compare models interactively
Authentication — API keys and response format