> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sutro.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-time Functions

> Run a published Function on a single input and wait for the answer.

# Real-time Functions

```text theme={null}
run_function(
    name: str,
    input_data: dict | str | BaseModel,
    langsmith_metadata: dict[str, Any] | None = None,
    langsmith_tags: list[str] | None = None,
    timeout_seconds: float | None = None,
    confidence_scoring: bool = True,
) -> FunctionRunResult
```

| Parameter | Description |
| - | - |
| `name` | Published Function name. Do not include a namespace or revision. |
| `input_data` | The Function's input fields. Keys must match the Function inputs; every field is required and unknown fields are rejected. A bare string is accepted when the Function has exactly one text input. Image and PDF fields take an `Asset` or `Image` value. |
| `langsmith_metadata`, `langsmith_tags` | Optional trace metadata when `LANGSMITH_TRACING=true`. |
| `timeout_seconds` | How long to wait for the answer. Defaults to just above the deployment's standard 90 s request deadline; raise it for a deployment whose deadline was raised. |
| `confidence_scoring` | Whether to compute a confidence score. On by default. `False` skips it and `confidence` is `None`. |

```python theme={null}
import sutro as so

result = so.run_function(
    "support-escalation",
    {"text": "The customer reports an unrecognized charge."},
)

label = result.output["label"]
if result.confidence <= 0.6:
    # Low confidence: log the request ID so someone can check this one by hand.
    print(f"check request {result.request_id}: {label} at {result.confidence:.2f}")
```

Use [`batch_run_function()`](/reference/python-sdk/functions) instead for large
tables; `run_function()` makes one synchronous request per call and can be rate
limited. See [Run a Function](/functions/run) for the walkthrough and the
[API reference](/reference/api/run-function) for the full request and response
contract, limits, and error codes.

## FunctionRunResult

The return value is a `dict` of the response payload, with its fields also
available as attributes.

| Attribute | Description |
| - | - |
| `output` | The answer, parsed against the Function's output schema. A string when the Function has no schema. |
| `confidence` | The confidence score for this answer, between 0 and 1. `None` when the request was made with `confidence_scoring=False`. |
| `usage` | Provider-reported `input_tokens` and `output_tokens`, plus estimated provider `cost_usd` when pricing is available. |
| `request_id` | The deployment's ID for this request, for log and support lookups. |
| `function` | The Function's `name`, `model`, and `model_source` (`model-sweep` or `sutro-default`). |

## Assets

Image and PDF input fields take a value built by `sutro.Image` or
`sutro.Asset`. Both return plain dicts, so they can also be written out by hand
or serialized with `json.dumps()`.

| Constructor | Value |
| - | - |
| `Image.from_path(path)` | Reads the file and infers its type from the extension. |
| `Image.from_bytes(data, mime_type, filename=None)` | Inline bytes with an explicit MIME type. |
| `Image.from_url(url)` | An `https://` URL the deployment downloads. |
| `Asset.from_path(path)`, `Asset.from_bytes(...)`, `Asset.from_url(...)` | The same, also accepting PDFs. |
| `Asset.from_name(name)` | An asset already stored in the deployment. |

```python theme={null}
import sutro as so

so.run_function(
    "invoice-reader",
    {
        "scan": so.Asset.from_path("invoices/april.pdf"),
        "logo": so.Image.from_url("https://cdn.example.com/logo.png"),
    },
)
```

`Image` accepts `image/png`, `image/jpeg`, and `image/webp`; `Asset` also
accepts `application/pdf`. Anything else raises `ValueError` before the request
is sent.

## Errors

`run_function()` never retries. Every failure raises a `requests.HTTPError`
subclass carrying the deployment's `detail`, `code`, and `request_id`.

| Exception | Raised for |
| - | - |
| `sutro.SutroRateLimitError` | `429`. `retry_after` is the number of seconds to wait, from the `Retry-After` header, or `None` when the deployment sent none. |
| `sutro.SutroValidationError` | `422`. The input does not match the Function, an asset could not be read, or the Function cannot run in real time on its current model. |
| `requests.HTTPError` | Every other API failure, including `404`, `409`, `502`, `503`, and `504`. |

```python theme={null}
import time
import sutro as so

try:
    result = so.run_function("support-escalation", {"text": text})
except so.SutroRateLimitError as error:
    time.sleep(error.retry_after or 1)
    result = so.run_function("support-escalation", {"text": text})
except so.SutroValidationError as error:
    print(error.detail, error.code)
    raise
```

## Command line

```bash theme={null}
sutro functions run support-escalation --input '{"text": "..."}'
sutro functions run support-escalation --input @request.json
```

`--input` takes a JSON object, or `@` followed by the path to a file holding
one. Add `--no-confidence-scoring` to skip the confidence score. The command
prints the JSON response and exits non-zero with the deployment's `detail` on
failure.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.