Skip to main content
POST
Run a Function in real time
Run a published Function on a single input. Hosted providers return the answer with HTTP 200; native sidecar Functions return HTTP 202 and an authenticated polling path. 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.
boolean
default:"true"
Whether to compute a confidence score for the answer. When false, confidence is null. The answer still appears in Monitoring but is never added to Needs Review.
Any other field returns 422 invalid_input.

Run a published Function

Confidence scores

The confidence score is computed the same way as in Batch and adds cost and latency to a request. A caller that will not act on the score can turn it off per request:
The response then carries the single answer with "confidence": null.

Image and PDF inputs

An image or PDF input field takes one of three values.
Hosted providers accept PNG, JPEG, WebP, and PDF up to 20 MiB per asset. Native vision models accept PNG, JPEG, and WebP up to 5 MiB each, with at most eight images per row. 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.

Native acceptance, polling, and cancellation

A native sidecar Function returns HTTP 202 with a run handle:
Send GET to the returned poll_path on the same deployment with the original API key. Wait the Retry-After interval between polls. HTTP 202 means the run is still pending; HTTP 200 returns the completed response. A terminal failure returns its ordinary error status and body. Polling does not repeat inference or charge the request rate limit again.
DELETE returns HTTP 202 while cancellation is pending, or HTTP 200 once the run is terminal. Polling a cancelled run returns 409 cancelled. Unknown run IDs and runs owned by another key or Function return 404 request_not_found. The original deadline defaults to 1,800 seconds and includes worker startup; polling does not extend it. Interrupted runs return 503 interrupted without replaying inference. Hosted Functions keep their existing synchronous behavior. The Python SDK handles this protocol automatically while run_function() waits for the answer.

Completed 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 | null
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. null when the request set confidence_scoring to false.
object
Provider-reported input_tokens and output_tokens, plus estimated provider cost_usd when pricing is available, 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 hosted defaults with HARMONIZE_REALTIME_*. Native deadlines use HARMONIZE_NATIVE_FUNCTION_TIMEOUT_SECONDS; aggregate pending inputs default to 64 MiB with HARMONIZE_NATIVE_FUNCTION_PENDING_BYTES.

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 can incur inference costs, and a caller waiting on an answer should decide for itself whether to try again. The Python SDK wraps this endpoint as run_function().