> ## 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,
) -> 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.                                                                                             |

```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 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.                                             |
| `usage`      | `input_tokens`, `output_tokens`, and `cost_usd` for the request.                                   |
| `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. The command prints the JSON response and exits non-zero with the
deployment's `detail` on failure.