> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sutro.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a Function in Batch

> Execute a published Function asynchronously over inline or remote inputs.

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](/reference/authentication) for the required
`Authorization: Key ...` header.

## Headers

<ParamField header="Authorization" type="string" required>
  Deployment API key in the form `Key YOUR_SUTRO_API_KEY`.
</ParamField>

## Body

<ParamField body="inputs" type="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.
</ParamField>

<ParamField body="model" type="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.
</ParamField>

<ParamField body="column_name" type="string | null" default="null">
  Input column for a standalone-model URL. Defaults to the first column. Omit for Functions.
</ParamField>

<ParamField body="id_column_name" type="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`.
</ParamField>

<ParamField body="system_prompt" type="string | null" default="null">
  System prompt for a standalone model. Functions use their published prompt.
</ParamField>

<ParamField body="json_schema" type="object | null" default="null">
  JSON Schema for standalone-model structured output. Functions use their published schema.
</ParamField>

<ParamField body="sampling_params" type="object | null" default="null">
  Generation settings. For Functions, request values override published runtime defaults.
</ParamField>

<ParamField body="job_priority" type="integer" default="0">
  `0` for prototyping or `1` for the [one-hour production SLA](/batch/run-model#job-priority-and-sla).
</ParamField>

<ParamField body="cost_estimate" type="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](/batch/production).
</ParamField>

<ParamField body="random_seed_per_input" type="boolean" default="false">
  Generate a random seed for each row.
</ParamField>

<ParamField body="truncate_rows" type="boolean" default="true">
  Trim oversized rows to the model context window. If `false`, an oversized row fails the job.
</ParamField>

<ParamField body="name" type="string | null" default="null">
  Optional job name, up to 45 characters.
</ParamField>

<ParamField body="description" type="string | null" default="null">
  Optional description, up to 512 characters.
</ParamField>

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

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

```bash theme={null}
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.

```bash theme={null}
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

```json theme={null}
{
  "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](/reference/api/job-status).