Run a Function in Batch

curl --request POST \
  --url https://your-sutro-deployment/v1/batch-inference \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {},
  "model": "<string>",
  "column_name": {},
  "id_column_name": {},
  "system_prompt": {},
  "json_schema": {},
  "sampling_params": {},
  "job_priority": 123,
  "cost_estimate": true,
  "random_seed_per_input": true,
  "truncate_rows": true,
  "name": {},
  "description": {}
}
'

import requests

url = "https://your-sutro-deployment/v1/batch-inference"

payload = {
    "inputs": {},
    "model": "<string>",
    "column_name": {},
    "id_column_name": {},
    "system_prompt": {},
    "json_schema": {},
    "sampling_params": {},
    "job_priority": 123,
    "cost_estimate": True,
    "random_seed_per_input": True,
    "truncate_rows": True,
    "name": {},
    "description": {}
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    inputs: {},
    model: '<string>',
    column_name: {},
    id_column_name: {},
    system_prompt: {},
    json_schema: {},
    sampling_params: {},
    job_priority: 123,
    cost_estimate: true,
    random_seed_per_input: true,
    truncate_rows: true,
    name: {},
    description: {}
  })
};

fetch('https://your-sutro-deployment/v1/batch-inference', 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://your-sutro-deployment/v1/batch-inference",
  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([
    'inputs' => [
        
    ],
    'model' => '<string>',
    'column_name' => [
        
    ],
    'id_column_name' => [
        
    ],
    'system_prompt' => [
        
    ],
    'json_schema' => [
        
    ],
    'sampling_params' => [
        
    ],
    'job_priority' => 123,
    'cost_estimate' => true,
    'random_seed_per_input' => true,
    'truncate_rows' => true,
    'name' => [
        
    ],
    'description' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "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://your-sutro-deployment/v1/batch-inference"

	payload := strings.NewReader("{\n  \"inputs\": {},\n  \"model\": \"<string>\",\n  \"column_name\": {},\n  \"id_column_name\": {},\n  \"system_prompt\": {},\n  \"json_schema\": {},\n  \"sampling_params\": {},\n  \"job_priority\": 123,\n  \"cost_estimate\": true,\n  \"random_seed_per_input\": true,\n  \"truncate_rows\": true,\n  \"name\": {},\n  \"description\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	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://your-sutro-deployment/v1/batch-inference")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": {},\n  \"model\": \"<string>\",\n  \"column_name\": {},\n  \"id_column_name\": {},\n  \"system_prompt\": {},\n  \"json_schema\": {},\n  \"sampling_params\": {},\n  \"job_priority\": 123,\n  \"cost_estimate\": true,\n  \"random_seed_per_input\": true,\n  \"truncate_rows\": true,\n  \"name\": {},\n  \"description\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://your-sutro-deployment/v1/batch-inference")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inputs\": {},\n  \"model\": \"<string>\",\n  \"column_name\": {},\n  \"id_column_name\": {},\n  \"system_prompt\": {},\n  \"json_schema\": {},\n  \"sampling_params\": {},\n  \"job_priority\": 123,\n  \"cost_estimate\": true,\n  \"random_seed_per_input\": true,\n  \"truncate_rows\": true,\n  \"name\": {},\n  \"description\": {}\n}"

response = http.request(request)
puts response.read_body

POST

batch-inference

Run a Function in Batch

curl --request POST \
  --url https://your-sutro-deployment/v1/batch-inference \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "inputs": {},
  "model": "<string>",
  "column_name": {},
  "id_column_name": {},
  "system_prompt": {},
  "json_schema": {},
  "sampling_params": {},
  "job_priority": 123,
  "cost_estimate": true,
  "random_seed_per_input": true,
  "truncate_rows": true,
  "name": {},
  "description": {}
}
'

import requests

url = "https://your-sutro-deployment/v1/batch-inference"

payload = {
    "inputs": {},
    "model": "<string>",
    "column_name": {},
    "id_column_name": {},
    "system_prompt": {},
    "json_schema": {},
    "sampling_params": {},
    "job_priority": 123,
    "cost_estimate": True,
    "random_seed_per_input": True,
    "truncate_rows": True,
    "name": {},
    "description": {}
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    inputs: {},
    model: '<string>',
    column_name: {},
    id_column_name: {},
    system_prompt: {},
    json_schema: {},
    sampling_params: {},
    job_priority: 123,
    cost_estimate: true,
    random_seed_per_input: true,
    truncate_rows: true,
    name: {},
    description: {}
  })
};

fetch('https://your-sutro-deployment/v1/batch-inference', 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://your-sutro-deployment/v1/batch-inference",
  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([
    'inputs' => [
        
    ],
    'model' => '<string>',
    'column_name' => [
        
    ],
    'id_column_name' => [
        
    ],
    'system_prompt' => [
        
    ],
    'json_schema' => [
        
    ],
    'sampling_params' => [
        
    ],
    'job_priority' => 123,
    'cost_estimate' => true,
    'random_seed_per_input' => true,
    'truncate_rows' => true,
    'name' => [
        
    ],
    'description' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "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://your-sutro-deployment/v1/batch-inference"

	payload := strings.NewReader("{\n  \"inputs\": {},\n  \"model\": \"<string>\",\n  \"column_name\": {},\n  \"id_column_name\": {},\n  \"system_prompt\": {},\n  \"json_schema\": {},\n  \"sampling_params\": {},\n  \"job_priority\": 123,\n  \"cost_estimate\": true,\n  \"random_seed_per_input\": true,\n  \"truncate_rows\": true,\n  \"name\": {},\n  \"description\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	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://your-sutro-deployment/v1/batch-inference")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"inputs\": {},\n  \"model\": \"<string>\",\n  \"column_name\": {},\n  \"id_column_name\": {},\n  \"system_prompt\": {},\n  \"json_schema\": {},\n  \"sampling_params\": {},\n  \"job_priority\": 123,\n  \"cost_estimate\": true,\n  \"random_seed_per_input\": true,\n  \"truncate_rows\": true,\n  \"name\": {},\n  \"description\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://your-sutro-deployment/v1/batch-inference")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"inputs\": {},\n  \"model\": \"<string>\",\n  \"column_name\": {},\n  \"id_column_name\": {},\n  \"system_prompt\": {},\n  \"json_schema\": {},\n  \"sampling_params\": {},\n  \"job_priority\": 123,\n  \"cost_estimate\": true,\n  \"random_seed_per_input\": true,\n  \"truncate_rows\": true,\n  \"name\": {},\n  \"description\": {}\n}"

response = http.request(request)
puts response.read_body

Use the Batch API to execute a published Function over production data. The Function supplies its optimized prompt, model, output schema, and runtime defaults. You may also call an available model ID directly when you do not need a Function. See Authentication for the required Authorization: Key ... header.

Headers

string

required

Deployment API key in the form Key YOUR_SUTRO_API_KEY.

Body

string[] | object[] | string

required

Function input objects, already-rendered strings, or an HTTPS CSV/Parquet download URL. Object keys or remote columns must match the Function inputs. Direct model calls require strings. s3:// URIs are not accepted.

string

default:"gpt-oss-20b"

The published Function name. Sutro resolves it within the API key owner’s account to the currently published revision. An available model ID may be supplied instead to run that model directly.

string | null

default:"null"

Input column for a standalone-model URL. Defaults to the first column. Omit for Functions.

string | null

default:"null"

Remote-input column to preserve in every result format. It must exist, differ from inference columns, and not use SKYSIGHT_, inputs, outputs, confidence_score, or cumulative_logprobs.

string | null

default:"null"

System prompt for a standalone model. Functions use their published prompt.

object | null

default:"null"

JSON Schema for standalone-model structured output. Functions use their published schema.

object | null

default:"null"

Generation settings. For Functions, request values override published runtime defaults.

integer

default:"0"

0 for prototyping or 1 for the one-hour production SLA.

boolean

default:"false"

Create an estimate job instead of a full job. After it succeeds, read cost_estimate from the job record. See Production Batch.

boolean

default:"false"

Generate a random seed for each row.

boolean

default:"true"

Trim oversized rows to the model context window. If false, an oversized row fails the job.

string | null

default:"null"

Optional job name, up to 45 characters.

string | null

default:"null"

Optional description, up to 512 characters.

Batch currently supports text Functions only. It does not execute Function web search or tool calls.

For remote input, use a sufficiently long-lived presigned HTTPS GET URL. Sutro performs one full-object download without resume or retry. Set column_name explicitly for standalone models; for Functions, omit it and provide columns matching the Function inputs. Null Function values become empty strings, and extra fields are ignored.

Run a published Function

curl https://YOUR-SUTRO-DEPLOYMENT/v1/batch-inference \
  -H "Authorization: Key YOUR_SUTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lead-qualifier",
    "inputs": [{"query": "Find security leaders", "region": "EMEA"}],
    "name": "lead-smoke"
  }'

Call a model ID directly

For generation without a published Function, set model to an available model ID and provide rendered string inputs. In this mode you may set system_prompt, json_schema, and sampling_params directly.

curl https://YOUR-SUTRO-DEPLOYMENT/v1/batch-inference \
  -H "Authorization: Key YOUR_SUTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-20b",
    "inputs": ["Summarize this report.", "Classify this request."],
    "system_prompt": "Answer concisely.",
    "job_priority": 0
  }'

Response

{
  "metadata": {
    "job_id": "job-12345678-1234-1234-1234-1234567890ab",
    "message": "Job created successfully"
  },
  "results": "job-12345678-1234-1234-1234-1234567890ab"
}

results and metadata.job_id are the same job ID. Creation is asynchronous and not idempotent: input download and quota validation can fail later, and retrying an ambiguous submission can create duplicate work. Monitor the returned ID with job status.

Product

MCP

Python SDK

API

Run a Function in Batch

Headers

Body

Run a published Function

Call a model ID directly

Response

​Headers

​Body

​Run a published Function

​Call a model ID directly

​Response

Headers

Body

Run a published Function

Call a model ID directly

Response