---
title: "Execute function"
method: POST
path: "/v1/execute-function"
tags: ["Sandbox"]
---

# Execute function

`POST /v1/execute-function`

Run a function in a secure, isolated environment. Define a function named `execute`. The function will be passed `input` as an object.

## Request body

- ExecuteFunctionRequest
  - `code` string, required — The function to execute. Your code must define a function named "execute" that takes in a single argument and returns a JSON-serializable value.
  - `env` object — Set of key-value pairs to add to the function's execution environment.
  - `files` File[] — List of input files.
    - `contents` string — The contents of the file.
    - `path` string — The relative path of the file.
  - `http` HTTP — Configuration for HTTP requests and authentication.
    - `allow` HTTPAllow[] — List of allowed HTTP hosts and associated authentication.
      - `auth` HTTPAuth — Authentication configuration for outbound requests to this host.
        - `basic` HTTPBasic
          - `password` string
          - `user_id` string
        - `bearer` HTTPBearer — Configuration to add an 'Authorization' header using the 'Bearer' scheme.
          - `token` string — The token to set, e.g. 'Authorization: Bearer <token>'.
        - `header` HTTPHeader
          - `name` string
          - `value` string
        - `query` HTTPQuery
          - `key` string
          - `value` string
      - `host` string — The hostname to allow.
  - `input` unknown
  - `language` 'python' | 'javascript' | 'typescript', required — The interpreter to use when executing code.
  - `limits` Limits — Configuration for execution environment limits.
    - `execution_timeout` integer — The maximum time allowed for execution (in seconds). Default is 30.
    - `memory_size` integer — The maximum memory allowed for execution (in MiB). Default is 128.
  - `runtime_revision_id` string — The ID of the runtime revision to use when executing code.

## Response `200`

OK

- ExecuteFunctionResponse
  - `execution` ExecutionResult, required — The execution details of the function.
    - `duration` integer, required — The execution time of the function in milliseconds.
    - `exit_code` integer, required — The exit code returned by the function. Will often be '0' on success and non-zero on failure.
    - `id` string, required — The ID of the execution.
    - `stderr` string, required — The contents of 'stderr' after executing the function.
    - `stdout` string, required — The contents of 'stdout' after executing the function.
  - `output` unknown, required
  - `output_status` 'error' | 'json_serialization_error' | 'valid', required — The status of the output. "valid" means your function executed successfully and returned a valid JSON-serializable object, or void. "json_serialization_error" means your function executed successfully, but returned a nonserializable object. "error" means your function failed to execute.

## Other responses

- `401` — Unauthenticated error response

## Changes

- **2025-06-29** `bab65e0b0c2b` — 1 info
  - added the required property `execution/id` to the response with the `200` status
- **2025-03-12** `63ab580806f0` — 1 info
  - added the required property `execution/duration` to the response with the `200` status
- **2025-02-05** `4ca61d8b4e33` — 10 breaking, 6 info
  - the request property `http` became not nullable
  - the request property `http/allow/items/auth/basic` became not nullable
  - the request property `http/allow/items/auth/bearer` became not nullable
  - the request property `http/allow/items/auth/header` became not nullable
  - …12 more
- **2025-01-23** `53d443fce326` — 1 info
  - added the optional property `output_status` to the response with the `200` status
- **2025-01-16** `00b3e89b997f` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/riza-io/apis/execute/changes/v1/execute-function/post.md)

---

[API](https://skmtc.dev/riza-io/apis/execute.md) · [All operations](https://skmtc.dev/riza-io/apis/execute/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/riza-io/execute/revisions/bab65e0b0c2b/schema)