# Network List API

The Azion Runtime Network List API checks whether an IP address is in one of the [network lists](/en/documentation/platform/firewall/network-shield/network-lists/) of your account. Functions that run on an Application or on a Firewall can call it. Pass it the client address of the request to allow, deny, or route that request by where it comes from.

> **Note**
>
> Under `azion dev`, every call to `Azion.networkList.contains()` throws `TypeError: Cannot read properties of undefined (reading 'find')`. Test network list checks on a deployed function.

---

## Access

The API is the `Azion.networkList.contains()` function, available to every function without an import. The client address of a request is the `remote_addr` value of the request metadata. With the `export default { fetch }` handler, read it from `request.metadata`:

```javascript
const ip = request.metadata["remote_addr"];
```

With `addEventListener("fetch", ...)`, read it from `event.request.metadata`:

```javascript
let ip = event.request.metadata["remote_addr"];
```

For every metadata value a function can read, refer to [Metadata API](/en/documentation/devtools/runtime/api-reference/metadata/).

---

## Syntax

`Azion.networkList.contains()` takes the network list ID and the address to check:

```javascript
Azion.networkList.contains(networkListId, ipAddress)
```

---

## Parameters

Both parameters are strings.

| Parameter       | Type   | Description                                                                                                                                           |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `networkListId` | string | ID of the network list, as a string of digits. A number is not accepted: convert it with `String()` first.                                            |
| `ipAddress`     | string | IP address to check. It matches an address item of the list, or any address inside a CIDR item, for example `198.51.100.42` inside `198.51.100.0/24`. |

---

## Return value

`Azion.networkList.contains()` returns a boolean: `true` when the address is in the network list, and `false` when it is not. When the call cannot run the check, it throws a `NetworkListError`, listed in Errors.

---

## Example

This function checks the client address of each request against a network list and returns the result as JSON. Replace `<network-list-id>` with the ID of one of your network lists:

```javascript
const NETWORK_LIST_ID = "<network-list-id>";

export default {
  async fetch(request, env, ctx) {
    const ip = request.metadata["remote_addr"];
    const ipFound = Azion.networkList.contains(NETWORK_LIST_ID, ip);
    return new Response(JSON.stringify({ ipFound }, null, 1), {
      headers: { "content-type": "application/json" },
    });
  },
};
```

A request from an address that is in the list returns:

```json
{
 "ipFound": true
}
```

---

## Errors

Every error `Azion.networkList.contains()` throws has the name `NetworkListError`. Catch it with `try...catch` and match on `err.name` to decide what the function does when the check cannot run.

| Error message                                                 | Cause                                                                                       | Fix                                                                          |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `Network List Not Found`                                      | The ID names no network list of the account, or the ID was passed as a number.              | Pass the ID of an existing network list as a string of digits.               |
| `Invalid Network List Id: Only numeric values are acceptable` | The ID string holds characters other than digits.                                           | Pass the numeric ID of the network list as a string.                         |
| `Invalid value: not-an-ip`                                    | The address is not an IP address. The message ends with the value passed, here `not-an-ip`. | Pass an IP address, such as the `remote_addr` metadata value of the request. |

---

## Related resources

- [Network Lists](/en/documentation/platform/firewall/network-shield/network-lists.md): The list types, the format of their items, and the interfaces that create and edit a list.
- [Metadata API](/en/documentation/devtools/runtime/api-reference/metadata.md): Read the `remote_addr` of a request and the other values the runtime gives a function.
- [Functions for Firewall](/en/documentation/platform/firewall/functions.md): End a firewall function with `event.continue()`, `event.deny()`, or `event.drop()` after a check.
- [Handlers](/en/documentation/devtools/runtime/api-reference/handlers.md): The `export default { fetch }` and `addEventListener` handler forms, and the request each one receives.