Skip to main content

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.
Both run the same published prompt, model, output schema, and sampling defaults, so the answers agree. Open Integrate on a ready Function to see code snippets to integrate into your pipeline or script.

Install and authenticate

Use the origin of the deployment where you published the Function and a deployment API key. Verify your connection before submitting a job. You can persist the same values with 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

The same call over HTTP:
Or from the command line:

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 HTTP 200. A Function served by the native inference sidecar returns HTTP 202 immediately, including when its GPU worker must start:
The SDK polls automatically and returns the same 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.
See 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.

Run with your own provider

The OpenAI-compatible endpoints section in Integrate provides the optimized system prompt, output schema, and recommended model. Copy these artifacts into your own compatible provider when you want to run the Function’s configuration on your own infrastructure. That path runs the exported configuration: it does not invoke the published Function by name.