# Invoke function

URL: https://docs.hanzo.ai/docs/openapi/function/post-function-by-name-invoke

> Runs a function and records a REAL invocation.

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

> [Function →](https://docs.hanzo.ai/docs/openapi/function) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|               |                                                  |
| ------------- | ------------------------------------------------ |
| **Address**   | `https://api.hanzo.ai/v1/function/{name}/invoke` |
| **Method**    | `POST`                                           |
| **Operation** | `post_function_by_name_invoke`                   |
| **Auth**      | `Authorization: Bearer $HANZO_API_KEY`           |

Runs a function and records a REAL invocation.

The answer is the invocation record whatever happened to it: 200 when the org's
code ran clean, 502 when it ran and failed, 503 when this deployment has no
sandbox to run code in. The record IS the evidence, so it rides the failure
rather than being replaced by an error envelope.

Billing is two-part and both parts are prepaid-then-metered on the one shared
meter: a flat per-invocation request fee, gated BEFORE any sandbox compute runs
so an unfunded org gets 402 and nothing executes, and a usage-native
GB-seconds compute debit taken after the run. Either is independently free when
its fee is zero, so an operator can bill by request alone, by compute alone, or
by both — and a zero request fee removes the balance gate with it.

A TRANSPORT failure is not charged: the sandbox being unreachable ran no
billable compute. Code that ran and exited non-zero IS charged — that is a
successful invocation of a failing program, not a billing failure.

When the sandbox is not configured on this deployment, a non-fleet function
fails closed before anything is recorded — no execution and no fabricated
output. Scoped to the caller's org; requires a validated principal.

## Request

2 fields, body `application/json` (required).

| Field   | In   | Type   | Required | Description                                   |
| ------- | ---- | ------ | -------- | --------------------------------------------- |
| `name`  | path | string | yes      |                                               |
| `input` | body | string | —        | Input is what the function is given on stdin. |

## Response

| Status    | Body                    | Meaning             |
| --------- | ----------------------- | ------------------- |
| `200`     | function.invocationView | ok                  |
| `502`     | function.invocationView | bad gateway         |
| `503`     | function.invocationView | service unavailable |
| `default` | problem-details         | refused             |

`200` body — 6 fields.

| Field        | In   | Type            | Always | Description                                                                                                                                          |
| ------------ | ---- | --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `durationMs` | body | integer (int64) | —      | how long it took                                                                                                                                     |
| `id`         | body | string          | —      | the invocation's handle                                                                                                                              |
| `method`     | body | string          | —      | the HTTP method that triggered it                                                                                                                    |
| `status`     | body | string          | —      | how the run ended: ok, error or timeout                                                                                                              |
| `statusCode` | body | integer (int64) | —      | Code is the status the function's OWN code answered with, which is not the status of the reply — a program can answer 500 through a healthy sandbox. |
| `time`       | body | string          | —      | when it ran, RFC3339                                                                                                                                 |

Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors).

## Examples

**CLI**

```bash
hanzo function invoke <name>
```

**SDK**

**.ts**

```ts
import { Configuration, FunctionApi } from 'hanzoai';

const api = new FunctionApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postFunctionByNameInvoke({ name: 'name', input: "<input>" });
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import FunctionApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = FunctionApi(client).post_function_by_name_invoke(name='name', input="<input>")
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.FunctionAPI.PostFunctionByNameInvoke(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, function_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = function_api::post_function_by_name_invoke(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.FunctionApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new FunctionApi(client).postFunctionByNameInvoke();
```

**HTTP**

```bash
curl -X POST https://api.hanzo.ai/v1/function/<name>/invoke \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "input": "<input>"
     }'
```

**MCP**

MCP reaches **function** through the `function` tool, which names its 10 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_functions"
         }
       }
     }'
```

---

[Function API](https://docs.hanzo.ai/docs/openapi/function) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)