Summary

The clusterUnregisterNode() mutation permanently removes a node from the LogScale cluster registry. Use this mutation as the final step when decommissioning a node: evict the node from active cluster duty first to drain its segment ownership and replication responsibilities, then call this mutation to remove its entry from the registry. The force argument bypasses safety checks for situations where the node is unreachable or unresponsive and cannot complete a graceful eviction.

API Stability Long-Term

Syntax

graphql
clusterUnregisterNode(
      force: Boolean!, nodeID: Int!
   ): UnregisterNodeMutation!

Both force and nodeID are required. Provide the integer ID of the node to remove and set force to indicate whether to bypass safety checks. When force is false, LogScale verifies that the node is reachable and has completed eviction before proceeding. The mutation returns an UnregisterNodeMutation object, which reflects updated cluster state after the operation.

The returned UnregisterNodeMutation type is non-null. The Returned Values section lists the fields available on that type and the nested Cluster datatype it references.

Example

Raw
graphql
mutation {
  clusterUnregisterNode(
         nodeID: 2,
         force: false ) 
  { cluster { nodes { id, name } } }
}
Mac OS or Linux (curl)
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  clusterUnregisterNode(
         nodeID: 2,
         force: false ) 
  { cluster { nodes { id, name } } }
}"
}
EOF
Mac OS or Linux (curl) One-line
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d @- << EOF
{"query" : "mutation {
  clusterUnregisterNode(
         nodeID: 2,
         force: false ) 
  { cluster { nodes { id, name } } }
}"
}
EOF
Windows Cmd and curl
shell
curl -v -X POST $YOUR_LOGSCALE_URL/graphql ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json" ^
    -d @'{"query" : "mutation { ^
  clusterUnregisterNode( ^
         nodeID: 2, ^
         force: false )  ^
  { cluster { nodes { id, name } } } ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "mutation {
  clusterUnregisterNode(
         nodeID: 2,
         force: false ) 
  { cluster { nodes { id, name } } }
}"
}'
    "$YOUR_LOGSCALE_URL/graphql"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = '$YOUR_LOGSCALE_URL/graphql';

my $query = "mutation {
  clusterUnregisterNode(
         nodeID: 2,
         force: false ) 
  { cluster { nodes { id, name } } }
}";
$query =~ s/\n/ /g;
my $json = sprintf('{"query" : "%s"}',$query);
my $req = HTTP::Request->new("POST", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");

$req->content( $json );

my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = '$YOUR_LOGSCALE_URL/graphql'
mydata = r'''{"query" : "mutation {
  clusterUnregisterNode(
         nodeID: 2,
         force: false ) 
  { cluster { nodes { id, name } } }
}"
}'''

resp = requests.post(url,
                     data = mydata,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

const data = JSON.stringify(
    {"query" : "mutation {
  clusterUnregisterNode(
         nodeID: 2,
         force: false ) 
  { cluster { nodes { id, name } } }
}"
}
);


const options = {
  hostname: '$YOUR_LOGSCALE_URL',
  path: 'graphql',
  port: 443,
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': data.length,
    Authorization: 'BEARER ' + process.env.TOKEN,
    'User-Agent': 'Node',
  },
};

const req = https.request(options, (res) => {
  let data = '';
  console.log(`statusCode: ${res.statusCode}`);

  res.on('data', (d) => {
    data += d;
  });
  res.on('end', () => {
    console.log(JSON.parse(data).data);
  });
});

req.on('error', (error) => {
  console.error(error);
});

req.write(data);
req.end();
Example Responses
Success (HTTP Response Code 200 OK)
json
{
  "data": {
    "clusterUnregisterNode": {
      "cluster": {
        "nodes": [
          {
            "id": 1,
            "name": "humio-cluster-node1:8080"
          }
        ]
      }
    }
  }
}

Input Parameters

Provide the numeric ID of the node to unregister and specify whether to bypass safety checks. Retrieve the node ID from the cluster() query shown in the Related section.

Table: Input Parameters & Datatypes

Parameter Type Required Default Description
This table contains all input parameters for this mutation.
force Boolean yes   Forces removal of the node, bypassing safety checks. When set to false, LogScale verifies that the node is reachable and has no outstanding segment ownership or replication duties before completing the removal. Set to true only when the node is unreachable or unresponsive and you have confirmed that the cluster can safely absorb the forced removal without data loss.
nodeID Int yes   The integer ID of the cluster node to unregister. Retrieve this value from the cluster() query using the nodes { id } field.

Returned Values

The mutation returns an UnregisterNodeMutation object. This type exposes the updated Cluster state after node removal, including node IDs and names for the remaining nodes. Use the returned cluster data to confirm the node is no longer present in the registry and to obtain current node identifiers for subsequent cluster operations.

Table: UnregisterNodeMutation Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
Some input parameters may be required, as indicated in the Required column. For return values, this indicates that you are assured a value if the field is requested for the results. 
Table last updated: Oct 14, 2026 
clusterClusteryes Long-Term The node to unregister from the cluster. See Cluster.

The UnregisterNodeMutation type references the Cluster datatype. That datatype is included here for reference:

Table: Cluster Datatype

ParameterTypeRequiredDefaultStabilityAvailabilityDescription
Some input parameters may be required, as indicated in the Required column. For return values, this indicates that you are assured a value if the field is requested for the results. 
Table last updated: Oct 14, 2026 
clusterInfoAgeSecondsFloatyes Long-Term The age of the cluster information in seconds.
clusterManagementSettingsClusterManagementSettingsyes Long-Term The settings for the LogScale cluster (see See ClusterManagementSettings.
defaultCachePolicyCachePolicy  Short-Term The default cache policy. See CachePolicy. Cache policies are a limited preview feature and subject to change.
digestReplicationFactorInt  Short-Term The digest replication factor.
inBucketStorageSegmentSizeFloatyes Long-Term The in bucket storage segment size.
ingestPartitionsIngestPartitionyes Long-Term The ingest partitions. See IngestPartition.
missingSegmentSizeFloatyes Long-Term The missing segment size.
nodesClusterNodeyes Long-Term The nodes of the cluster. See ClusterNode.
overReplicatedSegmentSizeFloatyes Long-Term The over replicated segment size.
pendingBucketStorageRiskySegmentSizeFloatyes Long-Term The pending bucket storage risky segment size.
pendingBucketStorageSegmentSizeFloatyes Long-Term The pending bucket storage segment size.
properlyReplicatedSegmentSizeFloatyes Long-Term The properly replicated segment size.
statsClusterStatsyes Short-Term The cluster statistics. See ClusterStats.
storageReplicationFactorInt  Short-Term The storage replication factor.
targetMissingSegmentSizeFloatyes Long-Term The target missing segment size.
targetOverReplicatedSegmentSizeFloatyes Long-Term The target over replicated segment size.
targetProperlyReplicatedSegmentSizeFloatyes Long-Term The target properly replicated segment size.
targetUnderReplicatedSegmentSizeFloatyes Long-Term The target under replicated segment size.
underReplicatedSegmentSizeFloatyes Long-Term The under replicated segment size.