Skip to main content
POST
Run a Function in real time
Run a published Function on a single input and receive the answer in the response. The Function supplies its optimized prompt, model, output schema, and sampling defaults; none of them can be overridden per request. Use Batch instead for tables of inputs. Configure your deployment URL and API key before using the examples below. Use the deployment where you published the Function.
string
required
The published Function name, without a namespace or revision.

Headers

string
required
Deployment API key in the form Key YOUR_SUTRO_API_KEY.
string
required
application/json. The body is limited to 32 MB.

Body

object | string
required
The Function’s input fields. Keys must match the Function’s configured inputs; 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. Image and PDF fields take an asset value.
input is the only accepted field. Any other field returns 422 invalid_input.

Run a published Function

Image and PDF inputs

An image or PDF input field takes one of three values.
PNG, JPEG, WebP, and PDF are accepted, up to 20 MB per asset. The bytes are sniffed, so a declared type or mime_type that disagrees with the actual content is rejected rather than passed to the model.

Response

string
This request’s ID. It also appears in the Function’s Monitoring tab and in every error body, for log and support lookups.
object
The Function that answered: its name, the base model, and model_source. model_source is model-sweep when a model was set active from a model sweep, or sutro-default when the Function ran its latest iteration’s prompt on the Sutro default model.
object | string
The answer, parsed against the Function’s output schema. A string when the Function has no schema.
number
A confidence score between 0 and 1 for this answer, computed the same way as in Batch. Answers at or below 0.6 are the ones worth a human look. See confidence scores.
object
input_tokens, output_tokens, and cost_usd for the whole request.
Every successful answer is also recorded in the Function’s Monitoring tab, and low-confidence answers are added to Needs Review.

Limits

Deployment operators can change these defaults with the HARMONIZE_REALTIME_* environment variables.

Errors

Failures return {"detail": ..., "code": ..., "request_id": ...}. A 429 or 503 that can be retried carries a Retry-After header with the number of seconds to wait. Requests are never retried automatically: a Function run costs tokens, and a caller waiting on an answer should decide for itself whether to try again. The Python SDK wraps this endpoint as run_function().