# Function instances

A function instance runs an existing [function](/en/documentation/platform/functions/) for an application, with the arguments the instance sets. These `azion/applications` functions create, list, read, update, and delete the function instances of an application.

---

## createFunctionInstance

Creates a function instance in an application. An instance runs an existing [function](/en/documentation/platform/functions/) for that application, with the arguments the instance sets.

Two things must exist first. The application must have functions turned on, which [patchApplication](/en/documentation/devtools/azion-lib/application/application/#patchapplication) does with `data: { edge_functions: true }`. The function must exist too: the instance names it by its ID in `edge_function_id`, and the `azion` package has no module that creates functions.

```typescript
function createFunctionInstance(params: {
  applicationId: number;
  data: ApiCreateFunctionInstancePayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionFunctionInstance>>;
```

| Parameter       | Type                                                                                                                           | Required | Description                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------- |
| `applicationId` | `number`                                                                                                                       | Yes      | The ID of the application.                                                            |
| `data`          | [`ApiCreateFunctionInstancePayload`](/en/documentation/devtools/azion-lib/application/types/#apicreatefunctioninstancepayload) | Yes      | `name`, the `edge_function_id` of the function, and the `args` the function receives. |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions)                             | No       | Request options.                                                                      |

Returns `data` as the created [AzionFunctionInstance](/en/documentation/devtools/azion-lib/application/types/#azionfunctioninstance), with its `id`.

```typescript
import { createFunctionInstance } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID

// Define the data for the new function instance
const functionInstanceData = {
  name: 'my-function-instance',
  edge_function_id: 23456, // Replace with the ID of an existing function
  args: { greeting: 'hello' },
};

// Create a new function instance
const { data: newFunctionInstance, error } = await createFunctionInstance({ applicationId, data: functionInstanceData });

if (error) {
  console.error('Error creating function instance:', error);
} else {
  console.log('Function instance created successfully:', newFunctionInstance);
}
```

Output:

```text
Function instance created successfully: {
  edge_function_id: 23456,
  name: 'my-function-instance',
  args: { greeting: 'hello' },
  id: 12345
}
```

---

## getFunctionInstances

Lists the function instances of an application, one page at a time.

```typescript
function getFunctionInstances(params: {
  applicationId: number;
  params?: ApiListFunctionInstancesParams;
  options?: AzionClientOptions;
}): Promise<AzionApplicationCollectionResponse<AzionFunctionInstance>>;
```

| Parameter       | Type                                                                                                        | Required | Description                         |
| --------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------- |
| `applicationId` | `number`                                                                                                    | Yes      | The ID of the application.          |
| `params`        | [`ApiListFunctionInstancesParams`](/en/documentation/devtools/azion-lib/application/types/#list-parameters) | No       | Pagination: `page` and `page_size`. |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions)          | No       | Request options.                    |

Returns an [AzionApplicationCollectionResponse](/en/documentation/devtools/azion-lib/application/types/#azionapplicationcollectionresponse) whose `data.results` holds [AzionFunctionInstance](/en/documentation/devtools/azion-lib/application/types/#azionfunctioninstance) objects.

```typescript
import { getFunctionInstances } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID

const { data: functionInstances, error } = await getFunctionInstances({
  applicationId,
  params: { page: 1, page_size: 10 },
});

if (error) {
  console.error('Error listing function instances:', error);
} else {
  console.log(`Found ${functionInstances?.count} function instances:`, functionInstances?.results);
}
```

Output:

```text
Found 1 function instances: [
  {
    id: 12345,
    edge_function_id: 23456,
    name: 'my-function-instance',
    args: { greeting: 'hello' }
  }
]
```

---

## getFunctionInstance

Returns one function instance of an application by its ID.

```typescript
function getFunctionInstance(params: {
  applicationId: number;
  functionInstanceId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionFunctionInstance>>;
```

| Parameter            | Type                                                                                               | Required | Description                      |
| -------------------- | -------------------------------------------------------------------------------------------------- | -------- | -------------------------------- |
| `applicationId`      | `number`                                                                                           | Yes      | The ID of the application.       |
| `functionInstanceId` | `number`                                                                                           | Yes      | The ID of the function instance. |
| `options`            | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions) | No       | Request options.                 |

Returns `data` as an [AzionFunctionInstance](/en/documentation/devtools/azion-lib/application/types/#azionfunctioninstance).

```typescript
import { getFunctionInstance } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const functionInstanceId = 12345; // Replace with the actual function instance ID

const { data: functionInstance, error } = await getFunctionInstance({ applicationId, functionInstanceId });

if (error) {
  console.error('Error retrieving function instance:', error);
} else {
  console.log('Function instance details:', functionInstance);
}
```

Output:

```text
Function instance details: {
  id: 12345,
  edge_function_id: 23456,
  name: 'my-function-instance',
  args: { greeting: 'hello' }
}
```

---

## updateFunctionInstance

Sends the function instance fields you pass in a `PATCH` request.

```typescript
function updateFunctionInstance(params: {
  applicationId: number;
  functionInstanceId: number;
  data: ApiUpdateFunctionInstancePayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionFunctionInstance>>;
```

| Parameter            | Type                                                                                                                | Required | Description                                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ |
| `applicationId`      | `number`                                                                                                            | Yes      | The ID of the application.                       |
| `functionInstanceId` | `number`                                                                                                            | Yes      | The ID of the function instance to update.       |
| `data`               | [`ApiUpdateFunctionInstancePayload`](/en/documentation/devtools/azion-lib/application/types/#azionfunctioninstance) | Yes      | The fields to change. The sample changes `name`. |
| `options`            | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions)                  | No       | Request options.                                 |

Returns `data` as the updated [AzionFunctionInstance](/en/documentation/devtools/azion-lib/application/types/#azionfunctioninstance).

```typescript
import { updateFunctionInstance } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const functionInstanceId = 12345; // Replace with the actual function instance ID

const { data: updatedFunctionInstance, error } = await updateFunctionInstance({
  applicationId,
  functionInstanceId,
  data: { name: 'my-function-instance-updated' },
});

if (error) {
  console.error('Error updating function instance:', error);
} else {
  console.log('Function instance updated:', updatedFunctionInstance);
}
```

Output:

```text
Function instance updated: {
  id: 12345,
  edge_function_id: 23456,
  name: 'my-function-instance-updated',
  args: { greeting: 'hello' }
}
```

---

## deleteFunctionInstance

Deletes a function instance of an application by its ID.

```typescript
function deleteFunctionInstance(params: {
  applicationId: number;
  functionInstanceId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<void>>;
```

| Parameter            | Type                                                                                               | Required | Description                                |
| -------------------- | -------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ |
| `applicationId`      | `number`                                                                                           | Yes      | The ID of the application.                 |
| `functionInstanceId` | `number`                                                                                           | Yes      | The ID of the function instance to delete. |
| `options`            | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions) | No       | Request options.                           |

A successful delete returns `error` with the message `Expected JSON response, but got: `, so the sample reads the instance back with [getFunctionInstance](#getfunctioninstance). A `404` error confirms the delete.

```typescript
import { deleteFunctionInstance, getFunctionInstance } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const functionInstanceId = 12345; // Replace with the actual function instance ID

const { error: deleteError } = await deleteFunctionInstance({ applicationId, functionInstanceId });

// On success (HTTP 204) the envelope still carries an error, so confirm by reading it back
const { error } = await getFunctionInstance({ applicationId, functionInstanceId });
if (error) {
  console.log(`Function instance ${functionInstanceId} deleted (read back: ${error.message})`);
} else {
  console.error('Error deleting function instance:', deleteError);
}
```

Output:

```text
Function instance 12345 deleted (read back: HTTP error! Status: 404 - NOT FOUND)
```

---

## Related resources

- [Azion Lib](/en/documentation/devtools/azion-lib.md): The Azion Lib modules and the npm package each one ships in.
- [Applications](/en/documentation/devtools/azion-lib/application.md): The module's authentication, its response envelope, and the errors its functions report.
- [Application types](/en/documentation/devtools/azion-lib/application/types.md): The payload and response types these functions take and return.
- [Functions instances](/en/documentation/platform/applications/functions-instances.md): The function instance an application runs, with its arguments.