Summary

The checkRemoteClusterConnection() GraphQL query is used to validate a remote cluster connection, to check that it's there, configured properly and more.

Hide Query Example

Show Cluster Nodes Query

API Stability Short-Term

Syntax

graphql
checkRemoteClusterConnection(
      input: CheckRemoteClusterConnectionInput!
    ): RemoteClusterConnectionStatus

For the input, you'll have to give the public URL of the remote cluster. There are a few other parameters you may need to provide. See the Input Parameters section.

For the results, primarily you'd request whether the connection is valid and maybe if there are any error messages. See the Returned Datatype for more choices.

Example

Raw
graphql
query {
	checkRemoteClusterConnection(
      input:
        { publicUrl: "https://logger.company.com",
          token: "abc123def" } ) 
  {id, remoteViewName, isValid}
}
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" : "query {
	checkRemoteClusterConnection(
      input:
        { publicUrl: \"https://logger.company.com\",
          token: \"abc123def\" } ) 
  {id, remoteViewName, isValid}
}"
}
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" : "query {
	checkRemoteClusterConnection(
      input:
        { publicUrl: \"https://logger.company.com\",
          token: \"abc123def\" } ) 
  {id, remoteViewName, isValid}
}"
}
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" : "query { ^
	checkRemoteClusterConnection( ^
      input: ^
        { publicUrl: \"https://logger.company.com\", ^
          token: \"abc123def\" } )  ^
  {id, remoteViewName, isValid} ^
}" ^
} '
Windows Powershell and curl
powershell
curl.exe -X POST 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    -d '{"query" : "query {
	checkRemoteClusterConnection(
      input:
        { publicUrl: \"https://logger.company.com\",
          token: \"abc123def\" } ) 
  {id, remoteViewName, isValid}
}"
}'
    "$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 = "query {
	checkRemoteClusterConnection(
      input:
        { publicUrl: \"https://logger.company.com\",
          token: \"abc123def\" } ) 
  {id, remoteViewName, isValid}
}";
$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" : "query {
	checkRemoteClusterConnection(
      input:
        { publicUrl: \"https://logger.company.com\",
          token: \"abc123def\" } ) 
  {id, remoteViewName, isValid}
}"
}'''

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" : "query {
	checkRemoteClusterConnection(
      input:
        { publicUrl: \"https://logger.company.com\",
          token: \"abc123def\" } ) 
  {id, remoteViewName, isValid}
}"
}
);


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": {
    "checkRemoteClusterConnection": {
      "id": null,
      "remoteViewName": "humio",
      "isValid": true
    }
  }
}

Input Parameters

For the input, you'll have to give the public URL of the remote cluster, and possibly the token needed to access the cluster. Below is a list of all of parameters allowed along with descriptions of them:

Table: CheckRemoteClusterConnectionInput Input Datatype

ParameterTypeRequiredDefaultStabilityDescription
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: Apr 28, 2026
connectionIdstring  Short-TermThe unique identifier of the connection to check. Must be supplied if the token is not supplied.
multiClusterViewNamestring  Short-TermThe name of the multi-cluster view to which the connection belongs. Must be supplied if the token is not supplied.
publicUrlstringyes Short-TermThe public URL of the remote cluster to connect.
queryPrefixstring  Short-TermFilter query that restricts the data visible through this connection.
tags[ClusterConnectionInputTag]yes Short-TermAdditional tags that can be used to filter queries. See ClusterConnectionInputTag.
tokenstringyes Short-TermThe access token for the remote view to connect with. Can be omitted if checking an existing connection with no token change.

Returned Values

For the results, you can get the status of the cluster connection. At a minimum, you'll probably want to know that the connection is valid, and maybe the version that the cluster is running. There are several choices available. They're listed below:

Table: RemoteClusterConnectionStatus Datatype

ParameterTypeRequiredDefaultStabilityDescription
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: Jul 1, 2025
errorMessages[ConnectionAspectErrorType]yes Short-TermErrors if the connection is invalid. See ConnectionAspectErrorType.
idstring  Short-TermThe unique identifier of the connection.
isValidbooleanyes Short-TermWhether the connection is valid.
remoteServerCompatVersionstring  DeprecatedOldest server version that is protocol compatible with the remote server. This field is no longer used in deciding protocol compatibility. It will be removed in version 1.207.
remoteServerVersionstring  Short-TermSoftware version of the remote view.
remoteViewNamestring  Short-TermThe name of the remote view.