---
search:
  tags:
    - Functions
    - POST
seo:
  description: >-
    Run the function once and answer when it ends. Every call it makes acts for…
    Reference for the POST /api/v2/functions/{name}/runs endpoint in the Anlyon
    API.
sidebar:
  label: Run a function
  badge: POST
title: Run a function
type: openapi-operation
---
Run the function once and answer when it ends. Every call it makes acts for the end user in `Anlyon-End-User`: impact limits, approvals, the end user's connections, the halt switch and receipts apply as for any action call. Needs `actions:invoke` as well as `functions:run`.

`mode` says what happens to writes (a call to an action that is not a GET):

- `plan` (the default): reads run for real; each write is recorded and answered with `{ planned: true }`, and nothing is sent. The run ends `planned` when it made no writes. With writes it ends `awaiting_approval`, and `plan` lists them with one approval of kind `function_plan` bound to the plan's digest. The team decides it, or the end user when every write's approval policy says `decidedBy: end_user`.
- `apply`, with `planRunId`: carries out an approved plan, once, with the plan's version, input and end user. Each write must equal the plan's next write: same action, same input, same order. A matching write is sent as its own action invocation with its own receipt. A write that does not match ends the run `diverged` before it is sent, and nothing further is sent; plan again for a new approval. Reads may differ.
- `straight_through`: every call is sent as it is made. A write must be to an action in the version's `straightThrough` policy, within its `maxWrites`; any other write is refused with `PLAN_REQUIRED` and nothing is sent.

A run can also end `failed`, or `budget_exceeded` with `budget` naming the budget that ran out. `409` when an apply's plan is not approved (`PLAN_NOT_APPROVED`), has no writes (`PLAN_HAS_NO_WRITES`), was already applied (`PLAN_ALREADY_APPLIED`), was made with other input (`PLAN_INPUT_MISMATCH`) or was approved more than 24 hours ago (`PLAN_EXPIRED`).

`503 FUNCTION_RUNNER_UNAVAILABLE` when the function runner is not configured or cannot be reached. Nothing ran, and the run is not counted.

Runs are held to the workspace's plan (`GET /api/v2/billing/plans`, `planCatalogue[].functionRuns`). `402 PAYMENT_REQUIRED` when the workspace has no plan. `429 FUNCTION_RUN_CONCURRENCY_LIMIT` when the plan's runs at once are all going (retry when one ends), `429 FUNCTION_RUN_RATE_LIMITED` past the plan's run starts a minute, and `429 QUOTA_EXCEEDED` past the plan's runs a month (they come back on the 1st, UTC). In each case nothing ran and nothing was counted. A run's own action calls count as governed actions, as any action call does.

`POST /api/v2/functions/{name}/runs`