Run a Function
A published Function can be run two ways:- Real time. One input, one answer. The SDK waits for completion. Use it for single requests and low-QPS integrations, and for Functions with image or PDF inputs.
- Batch. A job over a table, dataframe, or file. Use it for larger datasets, from thousands to millions of rows. Supported native vision models accept text, image, and PDF fields.
Install and authenticate
sutro login.
Native Functions and image Batch inputs require SDK 0.1.69 or later
for automatic polling and image uploads. Once that release is available, upgrade
existing installations with pip install --upgrade "sutro>=0.1.69"; installing
an older published SDK does not provide these features.
Run one input
Request
POST /v1/functions/{name}/run takes exactly
an input field. Input keys must match the Function’s configured input
fields; every field is required, and unknown fields are rejected. Values that
are not strings are converted the same way Batch converts a row: null becomes
an empty string, objects and lists become JSON, and anything else becomes its
plain string form. A bare string is accepted in place of the object when the
Function has exactly one text input.
Sampling parameters cannot be overridden per request. The Function’s published
settings are what make its answers reproducible.
Native worker startup and HTTP polling
Hosted providers return the completed answer with HTTP200. A Function served
by the native inference sidecar returns HTTP 202 immediately, including when
its GPU worker must start:
FunctionRunResult. Raw HTTP
callers send authenticated GET requests to poll_path on the same deployment.
HTTP 202 means pending; HTTP 200 contains the completed response below.
Use DELETE on that path to cancel pending work. Both operations require the
original API key and Function. Terminal failures retain the ordinary error
status and body. Polling does not start another inference request.
The native deadline defaults to 1,800 seconds, including startup. An explicit
SDK timeout_seconds bounds submission and polling together and requests
cancellation on expiry; cancellation cleanup may take up to two extra seconds.
Completed response
Image and PDF inputs
Image and PDF inputs work in real time and in Batch when the Function’s selected native model and deployment support those inputs. Native PDF Functions use Qwen3.5 or Gemma 4 vision models. Compatible hosted providers also accept PDFs in real time. An asset field takes one of three values. Deployment operators must roll out the native sidecar and Batch GPU workers together before advertising native PDF support.
Real-time calls accept PNG, JPEG, and WebP images up to 5 MiB each and hosted
PDFs up to 20 MiB each.
Native Batch ingestion accepts images
up to 20 MiB each through HTTPS URLs or raw image data URI strings. SDK image
uploads and Harmonize dataset or Function collection images remain limited to
5 MiB each, including review reimports. Use HTTPS URLs for larger Batch images.
Unencrypted native PDFs are limited to 32 MiB each in both modes. Each PDF is
rendered on the server into page images with extracted text and page numbers,
using the same representation in real time
and Batch. A row can contain at most eight images in total, counting every PDF
page and every separate image. For example, a six-page PDF and two images fit;
a nine-page PDF does not. Inputs exceeding the page or model-context limit are
rejected rather than truncated.
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.
The bytes are sniffed, so a declared
type or mime_type that disagrees with
the actual content is rejected. Inline base64 counts toward the request-body
limit; use an HTTPS URL or stored asset for larger PDFs.
Limits
A rate-limited request returns
429 with a Retry-After header; wait that many
seconds before retrying. The SDK surfaces it as
SutroRateLimitError.retry_after. Deployment operators can change these
defaults with the HARMONIZE_REALTIME_* environment variables, except the
240-second run timeout. Native runs use
HARMONIZE_NATIVE_FUNCTION_TIMEOUT_SECONDS and a shared 64 MiB pending-input
budget configured by HARMONIZE_NATIVE_FUNCTION_PENDING_BYTES.
Errors
Failures return{"detail": ..., "code": ..., "request_id": ...}. A run that
fails after its response started at 85 seconds ends a 200 body with an error
line instead; see
Runs longer than 85 seconds.
Requests are never retried automatically, in the SDK or the API: a Function run
can incur inference costs, and a caller waiting on an answer should decide for
itself whether to try again.
Submit many rows instead
For anything larger than a few hundred inputs, Batch is the better developer experience. It takes a list of dictionaries, Pandas or Polars DataFrames, local CSV or Parquet files, and HTTPS download URLs. It has no request rate limits and comfortably handles hundreds of thousands to millions of rows.batch_run_function() and
Run a Function in Batch.
For retry-safe S3 submission, supply a persisted key and pinned source identity
to batch_run_function().
The sutro batch-run command
also manages signing, a saved receipt, watching and file download. Repeat the
same command after interruption, or use sutro jobs resume with a known job ID.