---
title: "Function Call"
method: POST
path: "/call"
tags: ["calls"]
---

# Function Call

`POST /call`

The Call endpoint is a simple interface to issue a task to an LLM.
It is a declarative interface with input and output schemas that supports text, image, audio inputs and outputs and is highly model agnostic.

## Request body

- AppApiPublicV2FunctionCallCallFunctionRequest
  - `name` string, required — Provide a unique name of the task. A function with this name will be created in the project. Functions configuration is overridden by the request parameters.
  - `instructions` string, nullable — Optionally provide an instruction for the model to complete the task. Recommended to be concise and to the point
  - `input_schema` object, nullable — Optionally provide an input schema for the task. Can preferably include field descriptions to allow the model to reason about the input variables. Schema is validated against the input data and issues an error if it does not match. With the Opper SDKs you can define these schemas through libraries like Pydantic and Zod. For schemas with definitions, prefer using '$defs' and '#/$defs/...' references.
  - `output_schema` object, nullable — Optionally provide an output schema for the task. Response is guaranteed to match the schema or throw an error. Can preferably include field descriptions to allow the model to reason about the output variables. With the Opper SDKs you can define these schemas through libraries like Pydantic and Zod. For schemas with definitions, prefer using '$defs' and '#/$defs/...' references. **Streaming with output_schema:** When used with streaming endpoints, enables precise field tracking via json_path. Each streaming chunk includes the exact schema field being populated (e.g., 'response.people[0].name'), allowing real-time UI updates by routing content to specific components.
  - `input` unknown
  - `model` union
    - string
    - Model
      - `name` string, required
      - `extra_headers` object, nullable
      - `options` object, nullable
    - object
    - union[]
      - union
        - string
        - Model
          - `name` string, required
          - `extra_headers` object, nullable
          - `options` object, nullable
        - object
  - `examples` Example[], nullable — Optionally provide examples of successful task completions. Will be added to the prompt to help the model understand the task from examples.
    - `input` unknown, required
    - `output` unknown, required
    - `comment` string, nullable
  - `parent_span_id` string, uuid, nullable — Optionally provide the parent span ID to add to the call event. This will automatically tie the call to a parent span in the UI.
  - `tags` object, nullable — Optionally provide a list of tags to add to the call event. Useful for being able to understand aggregate analytics on some dimension.
  - `configuration` FunctionCallConfigurationInput
    - `invocation.few_shot.count` integer — [DEPRECATED via /call] This field is ignored when passed via /call endpoint. The system enforces a default of 3. Configure via PATCH /v2/functions/{uuid} or the Platform UI instead. The number of few-shot examples to use for the call, selected using nearest neighbor search of the function's dataset.
    - `beta.evaluation` unknown
    - `invocation.structured_generation.max_attempts` integer — The maximum number of attempts to make when generating a response matching the output schema if provided.
    - `invocation.cache.ttl` integer — The time to live for the cache in seconds. If 0, the cache is disabled.
    - `beta.invocation.input_validation.enabled` boolean — Whether to enable input validation against the input schema. This is a beta feature and is disabled by default.
    - `beta.invocation.xml_mode.enabled` boolean — Experimental: enable XML structured output. The model receives an XML schema and its response is converted back to JSON. We have observed better adherence to multi-paragraph text fields (especially with Anthropic models) when this is enabled.

## Response `200`

Successful Response

- AppApiPublicV2FunctionCallCallFunctionResponse
  - `span_id` string, uuid, required — The ID of the span of the call
  - `message` string, nullable — Result of the task if the call does not use an output schema
  - `json_payload` union — Result of the task if the call uses an output schema
    - object
    - unknown[]
      - unknown
    - unknown
  - `cached` boolean, nullable — True if the result was returned from a cached results
  - `images` string[], nullable — The images generated by the call. Only available for image models. Depending on the configuration, the response can either be a list of image urls or a base64 encoded images.
  - `usage` object, nullable — The usage of the call split into input and output tokens as well as the total tokens and an optional breakdown of the input and output tokens.The input tokens are the tokens sent to the model and the output tokens are the tokens received from the model. The total tokens is the sum of input and output tokens.
  - `cost` object, nullable — The cost in USD of the call split into total, generation and platform costs where total is the sum of generation and platform costs

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `402` — Payment Required (out of credits)
- `404` — Not Found
- `422` — Request Validation Error

---

[API](https://skmtc.dev/opper/apis/opper-api-v2.md) · [All operations](https://skmtc.dev/opper/apis/opper-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/opper/opper-api-v2/revisions/d3ccdaa15678/schema)