Batch and fine-tuning API

# Agent quickstart

Point an AI agent at Gridline and let it fine-tune, evaluate and batch open models for you. There are no GPUs, containers or sandboxes to manage: the agent calls the same API you would.

## Overview

Gridline's MCP server gives any MCP client (Claude Code, Claude Desktop and others) tools for the whole loop: upload data, fine-tune, evaluate the result against its base, batch on the winner and download the merged weights. Each tool wraps one OpenAI-compatible route under Gridline's base URL, so an agent without MCP can do the same over HTTP.

```
https://api.gridlinegpu.com/openai/v1
```

## Connect an agent

Create an API key in the dashboard and give it to the server as `GRIDLINE_TOKEN`. The key stays on your machine: the server sends it only to Gridline's API, never prints it and never returns it in a tool result.

Claude Code:

```
claude mcp add gridline --env GRIDLINE_TOKEN=$GRIDLINE_TOKEN -- npx -y @gridlinegpu/mcp
```

Any MCP client that reads a JSON config:

```
{
  "mcpServers": {
    "gridline": {
      "command": "npx",
      "args": ["-y", "@gridlinegpu/mcp"],
      "env": { "GRIDLINE_TOKEN": "<your Gridline API key>" }
    }
  }
}
```

The server runs over stdio as `gridline-mcp`.

## A worked loop

Ask the agent in plain language, for example:

```
Fine-tune qwen2.5-7b-instruct on ./train.jsonl. Then compare the fine-tuned model
with the base on ./eval.jsonl, and run ./requests.jsonl as a batch on whichever scores
higher. Tell me what each paid step will cost before you run it.
```

A capable agent then:

1. Uploads `train.jsonl` with `upload_file`, purpose `fine-tune`.
2. Checks the model's fine-tuning price, tells you, and starts the job with `create_fine_tune`, then polls `get_fine_tune` and `list_fine_tune_events` until it has an `ft:` model.
3. Defines an eval with `create_eval`, quotes a run on the base and on the `ft:` model with `create_eval_run` and `dry_run`, and runs both once you agree.
4. Compares the scores with `get_eval_run` and `list_output_items`.
5. Uploads `requests.jsonl` (purpose `batch`), runs it on the better model with `create_batch`, and saves the results with `download_results`.

## Spending credit

Three tools spend credit: `create_fine_tune`, `create_batch` and `create_eval_run` (unless `dry_run` is true). Each refuses unless the call carries `confirm_spend: true`, so an agent cannot spend by accident: it has to read the quote or the price first, and a well-behaved agent tells you before it confirms. Every other tool is free. What each job costs is on the [pricing page](https://gridlinegpu.com/pricing); fine-tunes are charged per training token, batches per input and output token, each with its minimum.

## Tools

| Tool | Spends credit | What it does |
| --- | --- | --- |
| `list_models` | No | Base models you can batch or fine-tune on, and your ft: models. |
| `get_credit_balance` | No | Your credit balance and recent charges. |
| `upload_file` | No | Upload a local JSONL file (purpose fine-tune or batch). |
| `create_fine_tune` | Yes | Start a LoRA, QLoRA or DPO fine-tuning job. |
| `list_fine_tunes` | No | Your fine-tuning jobs. |
| `get_fine_tune` | No | A job's status, its quote and its ft: model once it succeeds. |
| `list_fine_tune_events` | No | A job's progress and loss. |
| `cancel_fine_tune` | No | Cancel a fine-tuning job. |
| `create_batch` | Yes | Run a batch on a base model or your ft: model. |
| `get_batch` | No | A batch's status, counts and output file ids. |
| `cancel_batch` | No | Cancel a batch. |
| `download_results` | No | Save a batch's output or error file to a local path. |
| `create_eval` | No | Define an eval: its item schema and graders. |
| `create_eval_run` | Yes | Run an eval, or quote it with dry_run. |
| `get_eval_run` | No | A run's status and per-grader results. |
| `list_output_items` | No | A run's graded rows. |
| `request_merged_weights` | No | Export an ft: model merged into its base. |
| `get_merged_weights` | No | A merged-weights export's status and files. |
| `get_merged_file_url` | No | A short-lived download URL for one merged file. |

## Plain HTTP

An agent without MCP can run the same loop with any HTTP client, using a Gridline API key as the bearer token. The routes and objects are OpenAI's (see the [quickstart](https://gridlinegpu.com/docs#access)).

```
# 1. Upload training data
curl https://api.gridlinegpu.com/openai/v1/files -H "Authorization: Bearer $GRIDLINE_TOKEN" \
  -F purpose=fine-tune -F [[email protected]](https://gridlinegpu.com/cdn-cgi/l/email-protection)

# 2. Fine-tune (the answer carries the job's quote)
curl https://api.gridlinegpu.com/openai/v1/fine_tuning/jobs -H "Authorization: Bearer $GRIDLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen2.5-7b-instruct", "training_file": "file-...", "method": "qlora"}'

# 3. Quote an eval run first (dry_run), then run it without dry_run
curl https://api.gridlinegpu.com/openai/v1/evals/eval_.../runs -H "Authorization: Bearer $GRIDLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data_source": {...}, "dry_run": true}'

# 4. Batch on the fine-tuned model
curl https://api.gridlinegpu.com/openai/v1/batches -H "Authorization: Bearer $GRIDLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input_file_id": "file-...", "endpoint": "/v1/chat/completions", "completion_window": "24h"}'
```

---

Source: https://gridlinegpu.com/docs/agents