---
title: "Run a Function"
method: POST
path: "/functions/{function_name}/runs"
tags: ["Core", "Functions"]
---

# Run a Function

`POST /functions/{function_name}/runs`

## Request

- Base URL: `https://api.evervault.com`
- URL: `https://api.evervault.com/functions/{function_name}/runs`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
- TypeScript: <https://skmtc.dev/evervault/apis/evervault-api/docs/functions/:function_name/runs/post.ts> (a function with typed inputs; its response is checked against the schema)

The Function run endpoint lets you invoke an [Evervault Function](/primitives/functions). The body of the request should contain a payload, the value of which will be decrypted and passed as an argument to the Function.

## Path parameters

- `function_name` string, required

## Request body

- object
  - `payload` object, required: The data payload that the Function will use during its execution. Any encrypted values will be decrypted before being passed to the function.
  - `async` boolean: If you want your Function to run asynchronously and notify a callback URL, this can be set to `true` and the API will queue your Function run and return a `202` response code.

## Response `200`

The Function run has completed

- FunctionRun
  - `id` string, required: A unique identifier representing this specific Function execution instance.
  - `status` 'success' | 'failure' | 'scheduled', required: The outcome of the Function execution.
  - `result` object: This field represents the output returned by the Function. This is provided only when the Function execution status is 'success'.
  - `error` object, nullable: This field details any error that occurred during Function execution. This is present only if the status is 'failure'.
    - `message` string: A concise explanation of the error that occurred during Function execution.
    - `stack` string: A trace detailing the sequence of events leading to the error, useful for debugging purposes.
  - `createdAt` integer, required: The exact time, in epoch milliseconds, when this Function execution was triggered.

## Other responses

- `202`: The asynchronous Function invocation has been queued.
- `408`: The request has timed out.
- `409`: The Function is not ready to be invoked yet. This can occur when it hasn't been executed in a while. Retrying to run the Function after a short time should resolve this.

## Changes

- **2026-11-06** `8d0ca833fa04`: 18 info
  - the response property `code` became required for the status `408`
  - the response property `code` became required for the status `409`
  - the response property `createdAt` became required for the status `200`
  - the response property `createdAt` became required for the status `202`
  - …14 more
- **2026-04-17** `5e1eb58d42d5`: 2 info
  - added the optional property `fields` to the response with the `408` status
  - added the optional property `fields` to the response with the `409` status
- **2025-11-18** `30ea25af4354`: 2 breaking, 1 info
  - the response property `error` became nullable for the status `200`
  - the response property `error` became nullable for the status `202`
  - api tag `Core` added

[Operation history](https://skmtc.dev/evervault/apis/evervault-api/changes/functions/:function_name/runs/post.md)

---

[API](https://skmtc.dev/evervault/apis/evervault-api.md) - [All operations](https://skmtc.dev/evervault/apis/evervault-api/llms.txt) - [OpenAPI document](https://skmtc.dev/evervault/apis/evervault-api/revisions/8d0ca833fa04?raw)