Run a function

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

Authorization

AuthorizationBearer token (Anlyon API key) · headerrequired

Workspace API key sent as Authorization: Bearer <key>.

better-auth.session_tokenAPI key · cookierequired

Browser session used by dashboard-only operations.

Path parameters

namestringrequired

The function's name or id (fn_...).

min length 1 · max length 100

Header parameters

X-Request-Idstring

Optional caller correlation ID. Unsafe or oversized values are replaced.

max length 128

Anlyon-End-Userstring

The end user this call acts for: your own id for them, 1 to 128 characters of letters, digits and . _ : @ -. Accepted only with an API key, which stays on your server; a session or an OAuth token that sends it is refused. A key created with endUserRequired must send it on every action call (400 END_USER_REQUIRED). On an /end-users/{endUserId} route it must name the same end user as the path.

min length 1 · max length 128 · matches ^[A-Za-z0-9._:@-]{1,128}$

Request body

requiredapplication/json

inputobject

Passed to `run(input

modestring

What happens to writes: plan records them for approval, apply carries out an approved plan, straight_through sends them under the version's straight-through policy.

default: "plan"

Allowed:planapplystraight_through

planRunIdstring

For apply: the approved plan run to carry out. Required with apply, and refused with another mode.

max length 100

Responses

200

The finished run.

successbooleanrequired

Allowed:true

dataFunctionRunrequired

Show properties

idstringrequired

functionIdstringrequired

functionNamestringrequired

functionVersionIdstringrequired

modestringrequired

Allowed:straight_throughplanapply

statusstringrequired

Allowed:runningsucceededfailedbudget_exceededplannedawaiting_approvaldiverged

endUserIdstring | nullrequired

The end user the run acted for. Every call carried it.

inputobjectrequired

inputDigeststringrequired

outputany | nullrequired

What run returned

errorobject | nullrequired

Show properties

codestringrequired

messagestringrequired

logsstring[]required

Lines from anlyon.log. At most 100.

budgetstring | nullrequired

The budget that ended the run.

Allowed:maxActionCallsmaxCpuMsmaxSubrequeststimeoutMs

actionCallsintegerrequired

min 0

callsFunctionRunCall[]required

Show properties

Array of FunctionRunCall

sequenceintegerrequired

min 1

actionstringrequired

kindstringrequired

From the action's method. A GET reads.

Allowed:readwrite

statestringrequired

intent is a write a plan run recorded and did not send.

Allowed:intentdispatchedrefusedfailed

invocationIdstring | nullrequired

The invocation the call became

refusalstring | nullrequired

Why the call was refused, when it was. RUN_DIVERGED for an apply run's write that did not match its plan.

plannedSequenceinteger | nullrequired

An apply run's write

createdAtstring<date-time>required

planFunctionRunPlan | nullrequired

A plan run's plan

Show properties

Any of:

FunctionRunPlan

digeststringrequired

Covers the version

writesobject[]required

Show properties

Array of object

sequenceintegerrequired

actionstringrequired

inputanyrequired

The write's input

approvalobject | nullrequired

Null when the plan has no writes. It needs no approval.

Show properties

idstringrequired

statusstringrequired

Allowed:pendingapproveddeniedexpired

deciderstringrequired

Allowed:teamend_user

appliedByRunIdstring | nullrequired

The apply run that carried out the plan. A plan is applied at most once.

null

null

planRunIdstring | nullrequired

An apply run's plan run.

planDigeststring | nullrequired

An apply run's approved plan digest.

approvalIdstring | nullrequired

An apply run's plan approval.

receiptFunctionRunReceipt | nullrequired

Show properties

Any of:

FunctionRunReceipt

functionIdstringrequired

functionVersionIdstringrequired

digeststringrequired

inputDigeststringrequired

modestringrequired

Allowed:straight_throughplanapply

planDigeststring | nullrequired

A plan run's plan

approvalIdstring | nullrequired

planRunIdstring | nullrequired

For an apply run

callsobject[]required

Show properties

Array of object

sequenceintegerrequired

actionstringrequired

kindstringrequired

Allowed:readwrite

statestringrequired

Allowed:intentdispatchedrefusedfailed

invocationIdstring | nullrequired

refusalstring | nullrequired

plannedSequenceinteger | nullrequired

outcomestringrequired

Allowed:succeededfailedbudget_exceededplannedawaiting_approvaldiverged

budgetstring | nullrequired

Allowed:maxActionCallsmaxCpuMsmaxSubrequeststimeoutMs

finishedAtstring<date-time>required

null

null

durationMsinteger | nullrequired

createdAtstring<date-time>required

finishedAtstring<date-time> | nullrequired

400

Bad Request - Invalid input data

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

How to get past this error, for a person or an agent. Present on refusals with a known next step, such as a missing scope or role, a plan or billing limit, a halted environment, or a missing secret, connected account, OAuth app or end-user header. Absent when there is no fix to give. Kept in production responses, unlike details.

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

401

Unauthorized - Invalid or missing API key

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

402

Payment Required - Usage quota exceeded

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

403

Authenticated credential lacks the required scope or workspace access.

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

404

Not Found - Resource does not exist

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

409

The request conflicts with current resource state or a concurrent decision.

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

429

Too Many Requests - either the request rate limit, or the plan's cap on how many of this resource may exist. The code distinguishes them: RATE_LIMIT_EXCEEDED clears on its own, QUOTA_EXCEEDED does not until you remove one or upgrade.

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

503

A required provider or platform dependency is not configured or available.

successbooleanrequired

requestIdstringrequired

Correlation ID matching the X-Request-Id response header.

errorobjectrequired

Show properties

codestring

messagestring

detailsobject

fixErrorFix

Show properties

summarystringrequired

One sentence that says what to do.

commandstring

An exact anlyon CLI command that fixes it. Absent when no command does.

urlstring<uri>

An absolute console link where a person fixes it.

docsstring<uri>

A docs page that explains it.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer token (Anlyon API key)Remember on this deviceInclude my values in samples

Parameters

X-Request-IdheaderOptional caller correlation ID. Unsafe or oversized values are replaced.namepath*The function's name or id (fn_...).Anlyon-End-UserheaderThe end user this call acts for: your own id for them, 1 to 128 characters of letters, digits and `. _ : @ -`. Accepted only with an API key, which stays on your server; a session or an OAuth token that sends it is refused. A key created with `endUserRequired` must send it on every action call (`400 END_USER_REQUIRED`). On an /end-users/{endUserId} route it must name the same end user as the path.

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.anlyon.com/api/v2/functions/string/runs' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "input": {
    "order": "ord_123"
  },
  "mode": "plan",
  "planRunId": "frn_V1StGXR8_Z5jdHi6B-myT"
}'

const response = await fetch("https://api.anlyon.com/api/v2/functions/string/runs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"input\": {\n    \"order\": \"ord_123\"\n  },\n  \"mode\": \"plan\",\n  \"planRunId\": \"frn_V1StGXR8_Z5jdHi6B-myT\"\n}"
});

import requests

response = requests.post(
    "https://api.anlyon.com/api/v2/functions/string/runs",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"input\": {\n    \"order\": \"ord_123\"\n  },\n  \"mode\": \"plan\",\n  \"planRunId\": \"frn_V1StGXR8_Z5jdHi6B-myT\"\n}",
)

Response

{
  "success": true,
  "data": {
    "id": "frn_V1StGXR8_Z5jdHi6B-myT",
    "functionId": "fn_V1StGXR8_Z5jdHi6B-myT",
    "functionName": "refund-with-checks",
    "functionVersionId": "fnv_V1StGXR8_Z5jdHi6B-myT",
    "mode": "straight_through",
    "status": "running",
    "endUserId": "user_123",
    "input": {},
    "inputDigest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "output": null,
    "error": {
      "code": "FUNCTION_THREW",
      "message": "string"
    },
    "logs": [
      "string"
    ],
    "budget": "maxActionCalls",
    "actionCalls": 2,
    "calls": [
      {
        "sequence": 1,
        "action": "refund",
        "kind": "read",
        "state": "intent",
        "invocationId": "inv_V1StGXR8_Z5jdHi6B-myT",
        "refusal": "ACTION_NOT_ALLOWED",
        "plannedSequence": 2,
        "createdAt": "2019-08-24T14:15:22Z"
      }
    ],
    "plan": {
      "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "writes": [
        {
          "sequence": 2,
          "action": "refund",
          "input": null
        }
      ],
      "approval": {
        "id": "apr_V1StGXR8_Z5jdHi6B-myT",
        "status": "pending",
        "decider": "team"
      },
      "appliedByRunId": "string"
    },
    "planRunId": "string",
    "planDigest": "string",
    "approvalId": "string",
    "receipt": {
      "functionId": "fn_V1StGXR8_Z5jdHi6B-myT",
      "functionVersionId": "fnv_V1StGXR8_Z5jdHi6B-myT",
      "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "inputDigest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "mode": "straight_through",
      "planDigest": "string",
      "approvalId": "string",
      "planRunId": "string",
      "calls": [
        {
          "sequence": 1,
          "action": "refund",
          "kind": "read",
          "state": "intent",
          "invocationId": "string",
          "refusal": "string",
          "plannedSequence": 0
        }
      ],
      "outcome": "succeeded",
      "budget": "maxActionCalls",
      "finishedAt": "2019-08-24T14:15:22Z"
    },
    "durationMs": 0,
    "createdAt": "2019-08-24T14:15:22Z",
    "finishedAt": "2019-08-24T14:15:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "url": "Invalid URL format"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key"
  }
}

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Daily message quota exceeded. Upgrade your plan to continue."
  }
}

{
  "success": false,
  "requestId": "req_0123456789abcdef0123456789abcdef",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {},
    "fix": {
      "summary": "Log in again and approve the anlyon:secrets consent group, which grants secrets:write.",
      "command": "anlyon auth login --scope anlyon:secrets",
      "url": "https://console.anlyon.com/settings/api-keys",
      "docs": "https://docs.anlyon.com/cli/authentication"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

{
  "success": false,
  "requestId": "req_0123456789abcdef0123456789abcdef",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {},
    "fix": {
      "summary": "Log in again and approve the anlyon:secrets consent group, which grants secrets:write.",
      "command": "anlyon auth login --scope anlyon:secrets",
      "url": "https://console.anlyon.com/settings/api-keys",
      "docs": "https://docs.anlyon.com/cli/authentication"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Free plan allows up to 10 active schedules. You have 10. Upgrade to Pay as You Go for unlimited schedules."
  }
}

{
  "success": false,
  "requestId": "req_0123456789abcdef0123456789abcdef",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {},
    "fix": {
      "summary": "Log in again and approve the anlyon:secrets consent group, which grants secrets:write.",
      "command": "anlyon auth login --scope anlyon:secrets",
      "url": "https://console.anlyon.com/settings/api-keys",
      "docs": "https://docs.anlyon.com/cli/authentication"
    }
  }
}