Skip to main content
POST
Run a Function in Batch
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. Configure your deployment URL and API key before using the examples below. Use the deployment where you published the Function.

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/JSONL download URL. Object keys or remote columns must match the Function inputs. Direct text model calls use strings; native vision models also accept typed media rows. s3:// URIs are not accepted by this HTTP endpoint; the SDK signs them before submission.
string
default:"gemma-4-26b-a4b-it"
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 text rows to the model context window. If false, an oversized row fails the job. Native media rows exceeding page or model-context limits are always rejected rather than truncated.
string | null
default:"null"
Optional job name, up to 45 characters.
string | null
default:"null"
Optional description, up to 512 characters.
Batch supports typed image and PDF Functions when the selected native model and deployment support those inputs. Native PDF support is available for Qwen3.5 and Gemma 4 vision models. Asset fields accept HTTPS URLs, inline asset objects, or names already uploaded to the Function’s asset collection. Remote CSV asset columns can use HTTPS URLs or those stored names. Deployment operators must roll out the native sidecar and Batch GPU workers together before advertising native PDF support. Native Batch ingestion accepts PNG, JPEG, and WebP images up to 20 MiB each through HTTPS URLs or raw image data URI strings, including HTTPS URLs in remote CSV columns. Image uploads through the SDK or Harmonize, and images in dataset or Function collections, are limited to 5 MiB each, including review reimports. Use HTTPS URLs for Batch images larger than 5 MiB. Unencrypted PDFs are limited to 32 MiB each. PDFs are rendered on the server into page images with extracted text and page numbers, using the same representation as real-time Functions. The limit is eight images total per row, counting each PDF page and each separate image. Inputs exceeding that limit or the model’s context window are rejected rather than truncated. Asset bytes are retained during admission for inference and review. The Python SDK uploads inline images and PDFs once per content digest. Encrypted PDFs and XFA forms are unsupported; export XFA forms to standard PDFs first. Documents exceeding preprocessing resource limits, including one million extracted characters per PDF, are rejected without truncation.
Batch does not execute Function web search or tool calls.
string | null
default:"null"
Optional client-generated UUID for retry-safe S3 submission. Provide it together with input_source, persist it before sending, and reuse it when replaying the same logical request. Without it, ambiguous retries can create duplicate jobs.
object | null
default:"null"
Pinned S3 identity, provided together with idempotency_key: bucket, key, etag, size_bytes, and optional version_id. inputs must be a signed HTTPS GET URL for that same object and version.
For image and PDF Functions, refreshed asset receipts must identify the same authenticated owner, asset content, and field bindings. Renewing receipt tokens does not change the logical submission; changing an asset or its binding requires a new key. The upload endpoint and request catalog retain their existing image-assets and image_assets names for both images and PDFs. For ordinary URL input, use a sufficiently long-lived presigned HTTPS GET URL. Each ingestion attempt performs a full-object download; the transfer does not resume. Only public destinations on standard HTTP(S) ports are supported, and downloads never use service credentials. See remote-input limits. 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. For recoverable ingestion and safe replay, use the S3 submission protocol below.

Run a published Function

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.

Response

results and metadata.job_id are the same job ID. Monitor it with job status. Requests without idempotency_key are not idempotent: retrying after an uncertain response can create duplicate work, and execution validation can still fail after acceptance.

Retry-safe S3 submission

For the full client workflow, use batch_run_function() or the CLI. Custom API clients must first check deployment capabilities, then persist a UUID before the first POST. Keep request fields and source identity unchanged when retrying. The signed GET URL may be refreshed using local AWS credentials for the same pinned object.
Use metadata from S3 to populate input_source; omit version_id when the object is unversioned. The deployment retains and validates that exact object before accepting work. The first resolved Function configuration is retained across ingestion retries. Never log signed URLs or include them in receipts. While ingestion runs, POST returns HTTP 202:
Read GET /v1/batch-submissions/{idempotency_key} to recover its state after a lost response. Acceptance returns HTTP 200 with status: "ACCEPTED" and the original job ID. Replaying an accepted request returns that same job. A changed logical request with the same key returns 409; terminal input failure returns 422, and retryable ingestion failure may return 503. Check the reservation before replaying an uncertain POST; network errors are not a reason to generate a new key.