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

# Running a Function

> Run a deployed Sutro Function by name.

<Warning>Using the API directly is not recommended for most users. Instead, we recommend using the [Python SDK](/python-sdk/setup).</Warning>

Call a deployed Function by name and send the input fields it expects.

<Note>
  Use the Function name only. Do not include a namespace, owner, or revision. The authenticated API key determines which customer namespace Sutro searches, and the currently published revision is resolved automatically.
</Note>

<Warning>
  Only text Functions are supported on this endpoint today. Image, PDF, and other multimodal Functions are not supported yet.
</Warning>

## Request Body

<ParamField body="name" type="string" required>
  Name of the Function to execute.
</ParamField>

<ParamField body="input_data" type="object" required>
  Object containing the input fields for the Function.

  Include every required field. Extra fields are ignored unless the published Function uses them in its declared input field order.
</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>
  Your Sutro API key using the Key authentication scheme.

  Format: `Key YOUR_API_KEY`

  Example: `Authorization: Key sk_abc123...`
</ParamField>

## Response

Function responses use one of two shapes.

### Classification-style response

Returned when the Function has one primary output field, such as a label, verdict, route, or score.

<ResponseField name="response" type="string" required>
  Predicted value for the Function's primary output field.
</ResponseField>

<ResponseField name="confidence" type="float" required>
  Calibrated confidence score for `response`.
</ResponseField>

<ResponseField name="predictions" type="array" required>
  Candidate labels and confidence scores, sorted by confidence.
</ResponseField>

<ResponseField name="rationale" type="string">
  Explanation text when the Function output includes `rationale` or `reasoning`.
</ResponseField>

<ResponseField name="usage" type="object">
  Optional token usage details. When present, includes `input_tokens`, `output_tokens`, and `system_prompt`.
</ResponseField>

<ResponseExample>
  ```json Classification response theme={null}
  {
    "response": "qualified",
    "confidence": 0.91,
    "predictions": [
      {
        "label": "qualified",
        "confidence": 0.91
      },
      {
        "label": "not_qualified",
        "confidence": 0.09
      }
    ],
    "rationale": "The lead matches the qualification rubric.",
    "usage": {
      "input_tokens": 173,
      "output_tokens": 42,
      "system_prompt": "Return one lead qualification label."
    }
  }
  ```
</ResponseExample>

### Structured extraction response

Returned when the Function extracts multiple fields into a structured object.

<ResponseField name="output" type="object" required>
  Structured object matching the Function's output fields.
</ResponseField>

<ResponseField name="rationale" type="string" required>
  Explanation text for the structured output. This can be an empty string if the Function does not emit rationale text.
</ResponseField>

<ResponseField name="confidence" type="float" required>
  Confidence score for the representative structured output.
</ResponseField>

<ResponseField name="usage" type="object">
  Optional token usage details. When present, includes `input_tokens`, `output_tokens`, and `system_prompt`.
</ResponseField>

<ResponseExample>
  ```json Extraction response theme={null}
  {
    "output": {
      "company": "Acme Labs",
      "segment": "B2B analytics",
      "region": "APAC"
    },
    "rationale": "The requested company, segment, and region are present in the input.",
    "confidence": 0.82,
    "usage": {
      "input_tokens": 244,
      "output_tokens": 66,
      "system_prompt": "Extract the requested lead fields."
    }
  }
  ```
</ResponseExample>

There is no `run_id` in this response. For asynchronous execution over many rows, use the [Batch API](/batch-api-reference/running-batch-inference) or [`batch_run_function()`](/python-sdk/functions).

## Code Examples

Replace `lead-qualifier` and the input fields with your published Function name and schema.

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://serve.sutro.sh/functions/run",
      headers={
          "Authorization": "Key YOUR_SUTRO_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "name": "lead-qualifier",
          "input_data": {
              "query": "Find cybersecurity leaders evaluating AI vendors.",
              "region": "APAC",
          },
      },
  )

  result = response.json()
  print(result)
  ```

  ```bash cURL theme={null}
  curl -X POST https://serve.sutro.sh/functions/run \
    -H "Authorization: Key YOUR_SUTRO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "lead-qualifier",
      "input_data": {
        "query": "Find cybersecurity leaders evaluating AI vendors.",
        "region": "APAC"
      }
    }'
  ```
</CodeGroup>