Start a GRPO run
curl --request POST \
--url https://gateway.errorbar.ai/v1/grpo/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reward": {
"criterionId": "<string>",
"criterionIds": [
"<string>"
],
"assertions": "<array>"
},
"model": "<string>",
"promptCount": 2,
"rewardBudgetUsd": 123,
"gpuHourBudget": 123,
"promptTag": "<string>",
"groupSize": 123,
"maxSteps": 123,
"useCandidateQueue": true,
"allowSideEffects": false,
"useVllm": true,
"vllmGpuMemoryUtilization": 123,
"qlora": true,
"paramsB": 123,
"autoProvision": true,
"curriculumMixRatio": 0.45,
"holdoutCount": 123,
"maxCompletionTokens": 123,
"tasksInline": "<array>"
}
'import requests
url = "https://gateway.errorbar.ai/v1/grpo/runs"
payload = {
"reward": {
"criterionId": "<string>",
"criterionIds": ["<string>"],
"assertions": "<array>"
},
"model": "<string>",
"promptCount": 2,
"rewardBudgetUsd": 123,
"gpuHourBudget": 123,
"promptTag": "<string>",
"groupSize": 123,
"maxSteps": 123,
"useCandidateQueue": True,
"allowSideEffects": False,
"useVllm": True,
"vllmGpuMemoryUtilization": 123,
"qlora": True,
"paramsB": 123,
"autoProvision": True,
"curriculumMixRatio": 0.45,
"holdoutCount": 123,
"maxCompletionTokens": 123,
"tasksInline": "<array>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reward: {criterionId: '<string>', criterionIds: ['<string>'], assertions: '<array>'},
model: '<string>',
promptCount: 2,
rewardBudgetUsd: 123,
gpuHourBudget: 123,
promptTag: '<string>',
groupSize: 123,
maxSteps: 123,
useCandidateQueue: true,
allowSideEffects: false,
useVllm: true,
vllmGpuMemoryUtilization: 123,
qlora: true,
paramsB: 123,
autoProvision: true,
curriculumMixRatio: 0.45,
holdoutCount: 123,
maxCompletionTokens: 123,
tasksInline: '<array>'
})
};
fetch('https://gateway.errorbar.ai/v1/grpo/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://gateway.errorbar.ai/v1/grpo/runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reward' => [
'criterionId' => '<string>',
'criterionIds' => [
'<string>'
],
'assertions' => '<array>'
],
'model' => '<string>',
'promptCount' => 2,
'rewardBudgetUsd' => 123,
'gpuHourBudget' => 123,
'promptTag' => '<string>',
'groupSize' => 123,
'maxSteps' => 123,
'useCandidateQueue' => true,
'allowSideEffects' => false,
'useVllm' => true,
'vllmGpuMemoryUtilization' => 123,
'qlora' => true,
'paramsB' => 123,
'autoProvision' => true,
'curriculumMixRatio' => 0.45,
'holdoutCount' => 123,
'maxCompletionTokens' => 123,
'tasksInline' => '<array>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://gateway.errorbar.ai/v1/grpo/runs"
payload := strings.NewReader("{\n \"reward\": {\n \"criterionId\": \"<string>\",\n \"criterionIds\": [\n \"<string>\"\n ],\n \"assertions\": \"<array>\"\n },\n \"model\": \"<string>\",\n \"promptCount\": 2,\n \"rewardBudgetUsd\": 123,\n \"gpuHourBudget\": 123,\n \"promptTag\": \"<string>\",\n \"groupSize\": 123,\n \"maxSteps\": 123,\n \"useCandidateQueue\": true,\n \"allowSideEffects\": false,\n \"useVllm\": true,\n \"vllmGpuMemoryUtilization\": 123,\n \"qlora\": true,\n \"paramsB\": 123,\n \"autoProvision\": true,\n \"curriculumMixRatio\": 0.45,\n \"holdoutCount\": 123,\n \"maxCompletionTokens\": 123,\n \"tasksInline\": \"<array>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://gateway.errorbar.ai/v1/grpo/runs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reward\": {\n \"criterionId\": \"<string>\",\n \"criterionIds\": [\n \"<string>\"\n ],\n \"assertions\": \"<array>\"\n },\n \"model\": \"<string>\",\n \"promptCount\": 2,\n \"rewardBudgetUsd\": 123,\n \"gpuHourBudget\": 123,\n \"promptTag\": \"<string>\",\n \"groupSize\": 123,\n \"maxSteps\": 123,\n \"useCandidateQueue\": true,\n \"allowSideEffects\": false,\n \"useVllm\": true,\n \"vllmGpuMemoryUtilization\": 123,\n \"qlora\": true,\n \"paramsB\": 123,\n \"autoProvision\": true,\n \"curriculumMixRatio\": 0.45,\n \"holdoutCount\": 123,\n \"maxCompletionTokens\": 123,\n \"tasksInline\": \"<array>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://gateway.errorbar.ai/v1/grpo/runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reward\": {\n \"criterionId\": \"<string>\",\n \"criterionIds\": [\n \"<string>\"\n ],\n \"assertions\": \"<array>\"\n },\n \"model\": \"<string>\",\n \"promptCount\": 2,\n \"rewardBudgetUsd\": 123,\n \"gpuHourBudget\": 123,\n \"promptTag\": \"<string>\",\n \"groupSize\": 123,\n \"maxSteps\": 123,\n \"useCandidateQueue\": true,\n \"allowSideEffects\": false,\n \"useVllm\": true,\n \"vllmGpuMemoryUtilization\": 123,\n \"qlora\": true,\n \"paramsB\": 123,\n \"autoProvision\": true,\n \"curriculumMixRatio\": 0.45,\n \"holdoutCount\": 123,\n \"maxCompletionTokens\": 123,\n \"tasksInline\": \"<array>\"\n}"
response = http.request(request)
puts response.read_body{
"trigger_run_id": "<string>"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "Invalid API key",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}{
"error": {
"message": "Insufficient balance: deploying this endpoint requires at least 1h of runway. Top up and try again.",
"type": "insufficient_quota",
"code": "insufficient_balance"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": "<string>",
"type": "<string>"
}Reinforcement learning API
Start a GRPO run
Start an online-RL run with a validated reward and hard budgets. Requires an owner/admin key. Refusals are explicit: unaligned or drift-flagged reward judges, a prompt population below the floor, missing platform-GPU configuration, or insufficient balance. The reward budget is enforced ledger-true: the reward server refuses scoring calls past it.
POST
/
v1
/
grpo
/
runs
Start a GRPO run
curl --request POST \
--url https://gateway.errorbar.ai/v1/grpo/runs \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reward": {
"criterionId": "<string>",
"criterionIds": [
"<string>"
],
"assertions": "<array>"
},
"model": "<string>",
"promptCount": 2,
"rewardBudgetUsd": 123,
"gpuHourBudget": 123,
"promptTag": "<string>",
"groupSize": 123,
"maxSteps": 123,
"useCandidateQueue": true,
"allowSideEffects": false,
"useVllm": true,
"vllmGpuMemoryUtilization": 123,
"qlora": true,
"paramsB": 123,
"autoProvision": true,
"curriculumMixRatio": 0.45,
"holdoutCount": 123,
"maxCompletionTokens": 123,
"tasksInline": "<array>"
}
'import requests
url = "https://gateway.errorbar.ai/v1/grpo/runs"
payload = {
"reward": {
"criterionId": "<string>",
"criterionIds": ["<string>"],
"assertions": "<array>"
},
"model": "<string>",
"promptCount": 2,
"rewardBudgetUsd": 123,
"gpuHourBudget": 123,
"promptTag": "<string>",
"groupSize": 123,
"maxSteps": 123,
"useCandidateQueue": True,
"allowSideEffects": False,
"useVllm": True,
"vllmGpuMemoryUtilization": 123,
"qlora": True,
"paramsB": 123,
"autoProvision": True,
"curriculumMixRatio": 0.45,
"holdoutCount": 123,
"maxCompletionTokens": 123,
"tasksInline": "<array>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
reward: {criterionId: '<string>', criterionIds: ['<string>'], assertions: '<array>'},
model: '<string>',
promptCount: 2,
rewardBudgetUsd: 123,
gpuHourBudget: 123,
promptTag: '<string>',
groupSize: 123,
maxSteps: 123,
useCandidateQueue: true,
allowSideEffects: false,
useVllm: true,
vllmGpuMemoryUtilization: 123,
qlora: true,
paramsB: 123,
autoProvision: true,
curriculumMixRatio: 0.45,
holdoutCount: 123,
maxCompletionTokens: 123,
tasksInline: '<array>'
})
};
fetch('https://gateway.errorbar.ai/v1/grpo/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://gateway.errorbar.ai/v1/grpo/runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reward' => [
'criterionId' => '<string>',
'criterionIds' => [
'<string>'
],
'assertions' => '<array>'
],
'model' => '<string>',
'promptCount' => 2,
'rewardBudgetUsd' => 123,
'gpuHourBudget' => 123,
'promptTag' => '<string>',
'groupSize' => 123,
'maxSteps' => 123,
'useCandidateQueue' => true,
'allowSideEffects' => false,
'useVllm' => true,
'vllmGpuMemoryUtilization' => 123,
'qlora' => true,
'paramsB' => 123,
'autoProvision' => true,
'curriculumMixRatio' => 0.45,
'holdoutCount' => 123,
'maxCompletionTokens' => 123,
'tasksInline' => '<array>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://gateway.errorbar.ai/v1/grpo/runs"
payload := strings.NewReader("{\n \"reward\": {\n \"criterionId\": \"<string>\",\n \"criterionIds\": [\n \"<string>\"\n ],\n \"assertions\": \"<array>\"\n },\n \"model\": \"<string>\",\n \"promptCount\": 2,\n \"rewardBudgetUsd\": 123,\n \"gpuHourBudget\": 123,\n \"promptTag\": \"<string>\",\n \"groupSize\": 123,\n \"maxSteps\": 123,\n \"useCandidateQueue\": true,\n \"allowSideEffects\": false,\n \"useVllm\": true,\n \"vllmGpuMemoryUtilization\": 123,\n \"qlora\": true,\n \"paramsB\": 123,\n \"autoProvision\": true,\n \"curriculumMixRatio\": 0.45,\n \"holdoutCount\": 123,\n \"maxCompletionTokens\": 123,\n \"tasksInline\": \"<array>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://gateway.errorbar.ai/v1/grpo/runs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reward\": {\n \"criterionId\": \"<string>\",\n \"criterionIds\": [\n \"<string>\"\n ],\n \"assertions\": \"<array>\"\n },\n \"model\": \"<string>\",\n \"promptCount\": 2,\n \"rewardBudgetUsd\": 123,\n \"gpuHourBudget\": 123,\n \"promptTag\": \"<string>\",\n \"groupSize\": 123,\n \"maxSteps\": 123,\n \"useCandidateQueue\": true,\n \"allowSideEffects\": false,\n \"useVllm\": true,\n \"vllmGpuMemoryUtilization\": 123,\n \"qlora\": true,\n \"paramsB\": 123,\n \"autoProvision\": true,\n \"curriculumMixRatio\": 0.45,\n \"holdoutCount\": 123,\n \"maxCompletionTokens\": 123,\n \"tasksInline\": \"<array>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://gateway.errorbar.ai/v1/grpo/runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reward\": {\n \"criterionId\": \"<string>\",\n \"criterionIds\": [\n \"<string>\"\n ],\n \"assertions\": \"<array>\"\n },\n \"model\": \"<string>\",\n \"promptCount\": 2,\n \"rewardBudgetUsd\": 123,\n \"gpuHourBudget\": 123,\n \"promptTag\": \"<string>\",\n \"groupSize\": 123,\n \"maxSteps\": 123,\n \"useCandidateQueue\": true,\n \"allowSideEffects\": false,\n \"useVllm\": true,\n \"vllmGpuMemoryUtilization\": 123,\n \"qlora\": true,\n \"paramsB\": 123,\n \"autoProvision\": true,\n \"curriculumMixRatio\": 0.45,\n \"holdoutCount\": 123,\n \"maxCompletionTokens\": 123,\n \"tasksInline\": \"<array>\"\n}"
response = http.request(request)
puts response.read_body{
"trigger_run_id": "<string>"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "Invalid API key",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}{
"error": {
"message": "Insufficient balance: deploying this endpoint requires at least 1h of runway. Top up and try again.",
"type": "insufficient_quota",
"code": "insufficient_balance"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": "<string>",
"type": "<string>"
}Authorizations
Your workspace API key, e.g. sk_sovereign_..., sent as Authorization: Bearer <key>.
Body
application/json
This body is camelCase (promptCount, rewardBudgetUsd), unlike the snake_case loop endpoints. Types and presence are validated at the route; numeric bounds live in the shared service, the same source of truth the dashboard uses.
The validated reward. Agentic runs (environment set) require a trace-unit aligned criterion.
Show child attributes
Show child attributes
The base model to train.
How many logged prompts feed the run.
Required range:
x >= 1Hard ceiling on judge/reward spend. The reward server refuses scoring calls past it (ledger-true kill switch).
Wall-clock GPU budget, enforced by the orchestrator.
Sample training prompts from traffic with this tag.
Completions sampled per prompt per step (the G in GRPO).
Train on the workspace's GRPO-candidate queue (prompts offline RAFT gave up on) instead of a tag sample.
Platform-provisioned GPU: rate and markup are frozen at start and billed hourly while ACTIVE. Omit for a BYO-GPU run (no GPU billing).
Show child attributes
Show child attributes
Agentic runs: permit calls to tools not declared read-only. Default false.
Agentic mode: run episodes against the declared tool environment (see /v1/env/tools).
Show child attributes
Show child attributes
vLLM colocated rollouts. Forced on for agentic runs.
QLoRA 4-bit training.
Parameter-count override for models whose name doesn't carry it.
The platform provisions the GPU box (auto-sized). Refused when platform provisioning isn't configured.
Candidate-queue runs: fraction of the training slice drawn from regular successful traffic.
Required range:
0 <= x <= 0.9Holdout size for the bake-off; use 50+ for a real claim.
Per-rollout generated-token budget. Agentic default 8192; single-turn 1024.
Task objects: {goal, image?, recorded?, verifier?: [{command, timeout_sec}]}. Max 10000. The unit of agentic work; benchmark suites import here.
Maximum array length:
10000Opt-in per run: an "improved" bake-off verdict triggers deploy, then a canary on this alias under the online gate.
Show child attributes
Show child attributes
Mid-run anchor. Every everySteps steps the trainer generates one completion per frozen anchor prompt; the server scores them with the run's reward and with the anchor judge corrected for its measured error. Reward rising while the anchor does not, or the anchor falling from its best, HOLDS the run (never kills it) and pins the best anchor checkpoint, which is what ships. A held run's reward calls answer 409 held until a person resumes it.
Show child attributes
Show child attributes
Response
Started. The run id appears in GET /v1/grpo/runs.
Internal orchestration handle.