---
title: "Invoke function"
method: POST
path: "/v1/function/{function_id}/invoke"
tags: ["Functions"]
---

# Invoke function

`POST /v1/function/{function_id}/invoke`

Invoke a function.

## Path parameters

- `function_id` string, uuid, required — Function id

## Request body

- InvokeApi — The request to invoke a function
  - `input` unknown
  - `messages` ChatCompletionMessageParam[] — If the function is an LLM, additional messages to pass along to it
    - union
      - object
        - `content` string
        - `role` 'system', required
        - `name` string
      - object
        - `content` union
          - string
          - ChatCompletionContentPart[]
            - union
              - …
        - `role` 'user', required
        - `name` string
      - object
        - `role` 'assistant', required
        - `content` string, nullable
        - `function_call` object, nullable
          - `arguments` string, required
          - `name` string, required
        - `name` string, nullable
        - `tool_calls` ChatCompletionMessageToolCall[], nullable
          - `id` string, required
          - `function` object, required
            - `arguments` string, required
            - `name` string, required
          - `type` 'function', required
      - object
        - `content` string
        - `role` 'tool', required
        - `tool_call_id` string
      - object
        - `content` string
        - `name` string, required
        - `role` 'function', required
      - object
        - `role` 'model', required
        - `content` string, nullable
  - `parent` union — Options for tracing the function call
    - object — Span parent properties
      - `object_type` 'project_logs' | 'experiment', required
      - `object_id` string, required — The id of the container object you are logging to
      - `row_ids` object, nullable — Identifiers for the row to to log a subspan under
        - `id` string, required — The id of the row
        - `span_id` string, required — The span_id of the row
        - `root_span_id` string, required — The root_span_id of the row
      - `propagated_event` object, nullable — Include these properties in every span created under this parent
    - string — The parent's span identifier, created by calling `.export()` on a span
  - `stream` boolean, nullable — Whether to stream the response. If true, results will be returned in the Braintrust SSE format.
  - `mode` 'auto' | 'parallel' | 'null', nullable — The mode format of the returned value (defaults to 'auto')
  - `version` string — The version of the function

## Response `200`

Function invocation response

- unknown

## Changes

- **2024-09-30** `ac2727014d93` — 1 breaking, 2 info
  - the response's body became nullable
  - the request property `input` became nullable
  - the request property `parent/anyOf[subschema #1: span_parent_struct]/propagated_event/additionalProperties/` became nullable
- **2024-09-24** `a774951c03d7` — 3 info
  - added the new optional request property `messages`
  - added the new optional request property `mode`
  - the request property `stream` became nullable
- **2024-09-23** `35ca662bf690` — 1 breaking, 1 info
  - removed `subschema #1` from the `parent` request property `anyOf` list
  - added `subschema #1: span_parent_struct` to the `parent` request property `anyOf` list
- **2024-09-21** `1e677afe2f7b` — 2 info
  - added the new optional request property `parent/anyOf[subschema #1]/propagated_event`
  - added the new optional request property `parent/anyOf[subschema #1]/row_ids`
- **2024-07-30** `9635568dd298` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/function/:function_id/invoke/post.md)

---

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