> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salad.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Removals

> How to request removal of a SaladCloud Node from your SGS server

*Last Updated: February 14, 2025*

## When to request a node removal

SaladCloud goes to extreme lengths to filter the nodes available on SGS to maximize speed, reliability, uptime, IP
quality, and other performance metrics. In addition, SGS constantly monitors node performance characteristics and
automatically removes underperforming SaladCloud nodes. However, in the event that a SaladCloud node becomes blocked by
a content provider, or for any other reason fails to meet your requirements, you can request that it be removed from the
list of available IPs and replaced with a fresh node. You can do this by **requesting a node removal**.

At the time that the node removal request is received, the node which is connected to the session ID in the request body
will be removed.

If a node becomes unavailable for any reason, the pool of nodes connected to the SGS server will automatically be
'topped up' with a fresh node on a best-effort basis. Any streaming sessions routed over the unavailable node will be
transferred to other nodes.

## How to request a node removal

Submit a node removal request by sending a POST request to the following endpoint:
`https://matrix-rest-api.salad.com/api/v2/sgs/$SGS_ID/removals`

The `SGS_ID` will be shared with you before the trial period begins.

Set the Authorization header as below: `Authorization: Bearer $SALAD_JWT`

The `SALAD_JWT` will be shared with you before the trial period begins.

## Cautionary notes regarding node removals

A node removal completely boots a node from your SGS server. If the node failed to connect to a single service, it may
still be viable for other services - or exhibited a transient error. Node removals should therefore be thought of as a
last resort. If you find that multiple nodes are failing to connect to a specific service it is preferable to reach out
to your Account Manager first to discuss implementing a
[Destination Health Check](/gateway-service/explanation/destination-health-checks). If, however, you find a node which
is consistently underperforming - either exhibiting high latency or poor connectivity to target services - then a node
removal might make sense. Keep in mind that, in countries with a limited number of available nodes, use of the node
removal feature may result in removed nodes not being replaced immediately. Overuse of the feature could temporarily
deplete your node pool to the point that throughput levels are impacted, resulting in buffering and other poor
experiences for your customers.

When you submit a node removal request, SaladCloud marks a node for removal based on which node is currently mapped to
the sessionID that you provide in your node removal request. If the sessionID has since been mapped to a new node - for
instance, if the unhealthy node was already removed by SGS or went offline for any reason - your node removal request
will cause the removal of the new, healthy node. For this reason, we recommend that you submit the node removal request
as soon as possible after detecting an underperforming node to avoid inadvertently removing a healthy node which may now
be assigned that sessionID.

## Response codes

<AccordionGroup>
  <Accordion title="202 Accepted">
    The removal request has been accepted.
  </Accordion>

  {' '}

  <Accordion title="400 Bad Request">
    The request is malformed or missing required fields. Please double-check your request.
  </Accordion>

  <Accordion title="409 Conflict">
    A removal has already been recently performed on this sessionID. This prevents multiple requests from inadvertently removing healthy nodes following a successful node removal.
  </Accordion>
</AccordionGroup>

<Note>
  Node removal requests should be in the format application/json. The `removalReason` and `service` fields help
  SaladCloud diagnose root causes of node underperformance and improve our filters.
</Note>

## Example request

```bash theme={null}
curl -v -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $SALAD_JWT" -d \
'{"sessionId": "$SESSION_ID","timeDetectedAt": $TIME,"removalReason": "$REMOVAL_REASON","service": "$SERVICE"}' \
https://matrix-rest-api.salad.com/api/v2/sgs/$SGS_ID/removals
```

```JSON node_removal.json theme={null}
{
// A required string representing the session identifier.
"sessionId": "eb40cca0-c17b-4de8-a850-ac510bc29c6c",
// An optional Unix timestamp (seconds) indicating when it was detected as bad.
"timeDetectedAt": 1657639946,
// A required string with the reason for removal.
"removalReason": "Reason for removal request",
// A required string describing the specific service that was failing.
"service": "Example_Service"
}
```