# Getting started

The Load Balancer sits in front of your configured providers and exposes **one stable endpoint**.\
It automatically routes traffic only to **healthy endpoints** and switches strategies when needed.

Key capabilities:

* Health-aware routing
* Round-robin load distribution
* Automatic failover
* API access via query keys
* Optional security restrictions per key

### Access & Plans

The Load Balancer is a **paid feature**.

1. Navigate to **Load Balancer** in the [project you've created](https://chain-love.gitbook.io/chain.loves-performance/readme).
2. For a new project you will see an upgrade prompt.
3. After upgrading, the configurator becomes available.

<figure><img src="https://3120590109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzHukEzyKtop3oVU5Uj2y%2Fuploads%2FvIpq3LbokOSN1I3XJuwa%2FZrzut%20ekranu%20z%202026-01-06%2021-22-01.png?alt=media&#x26;token=f422a2eb-3240-4b44-8987-3fe57786c10d" alt=""><figcaption></figcaption></figure>

### Load Balancer Configurator

<figure><img src="https://3120590109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzHukEzyKtop3oVU5Uj2y%2Fuploads%2FCdjB3R241X8xljVl6m5n%2Fimage.png?alt=media&#x26;token=4b827770-8e76-42e2-acbd-f076a817188f" alt=""><figcaption></figcaption></figure>

After activation, you will see **three columns**:

#### 1. Unassigned

All providers you configured earlier (from the Providers step) appear here by default.

#### 2. Round-Robin

Providers placed here:

* Receive traffic **equally**
* Are used as the **primary routing group**
* Only **healthy** endpoints are considered

#### 3. Failover

Providers placed here:

* Are used **only if no Round-Robin providers are healthy**
* Traffic is balanced equally between healthy failover endpoints

### Configuration via Drag & Drop

Setup is done entirely via drag-and-drop:

1. Drag providers from **Unassigned** to **Round-Robin** and/or **Failover**
2. Changes are applied after you click save. No redeploys or restarts required

{% hint style="info" %}
You may place the same provider in only one strategy at a time.
{% endhint %}

{% hint style="warning" %}
Load Balancer only knows about health status of the endpoints which has [Monitoring enabled](https://chain-love.gitbook.io/chain.loves-performance/monitoring/getting-started). Providers that reside in failover may have Monitoring disabled, as they will receive traffic no matter what if no healthy providers in Round-Robin group discovered.
{% endhint %}

<details>

<summary>Detailed routing logic</summary>

The Load Balancer operates with the following logic:

1. Continuously [monitors endpoint health](https://chain-love.gitbook.io/chain.loves-performance/monitoring/getting-started)
2. Routes requests only to **healthy endpoints**
3. If **Round-Robin has ≥1 healthy endpoint**\
   → traffic is balanced equally between them
4. If **all Round-Robin endpoints are unhealthy**\
   → traffic switches to **Failover**
5. If only Failover endpoints exist or no healthy endpoints exist\
   → traffic is balanced equally between endpoints in failover mode.

This guarantees maximum availability with predictable behavior.

***

</details>

### Query Keys (API Access)

To use the Load Balancer, you must create a **Query Key**.

#### Creating a Query Key

<figure><img src="https://3120590109-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzHukEzyKtop3oVU5Uj2y%2Fuploads%2F7xidfGoJ4z9I8DbTn8dt%2FZrzut%20ekranu%20z%202026-01-06%2021-26-40.png?alt=media&#x26;token=e0029a66-b548-41da-9436-ee12b9de3bb6" alt=""><figcaption></figcaption></figure>

1. Click **Query Keys** (top-right)
2. Click **Create new key**
3. Configure:
   * **Name** (required)
   * **Description** (optional)
   * **Rate limits** (requests per minute)
   * **Security options** (optional): Allowed IP addresses and Allowed domains that limit where and how Load Balancer keys may be used.

These restrictions are enforced at the Load Balancer level.

To get an example on how to send queries to the load balancer - click "**Usage Example**" near "Query keys" button.