Skip to main content
POST
/
functions
/
run
Running a Function
curl --request POST \
  --url https://serve.sutro.sh/functions/run \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "input_data": {}
}
'
{
  "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."
  }
}

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.

Using the API directly is not recommended for most users. Instead, we recommend using the Python SDK.
Call a deployed Function by name and send the input fields it expects.
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.
Only text Functions are supported on this endpoint today. Image, PDF, and other multimodal Functions are not supported yet.

​
Request Body

​
name
string
required
Name of the Function to execute.
​
input_data
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.

​
Headers

​
Authorization
string
required
Your Sutro API key using the Key authentication scheme.Format: Key YOUR_API_KEYExample: Authorization: Key sk_abc123...

​
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.
​
response
string
required
Predicted value for the Function’s primary output field.
​
confidence
float
required
Calibrated confidence score for response.
​
predictions
array
required
Candidate labels and confidence scores, sorted by confidence.
​
rationale
string
Explanation text when the Function output includes rationale or reasoning.
​
usage
object
Optional token usage details. When present, includes input_tokens, output_tokens, and system_prompt.
{
  "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."
  }
}

​
Structured extraction response

Returned when the Function extracts multiple fields into a structured object.
​
output
object
required
Structured object matching the Function’s output fields.
​
rationale
string
required
Explanation text for the structured output. This can be an empty string if the Function does not emit rationale text.
​
confidence
float
required
Confidence score for the representative structured output.
​
usage
object
Optional token usage details. When present, includes input_tokens, output_tokens, and system_prompt.
{
  "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."
  }
}
There is no run_id in this response. For asynchronous execution over many rows, use the Batch API or batch_run_function().

​
Code Examples

Replace lead-qualifier and the input fields with your published Function name and schema. 
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)