API Stability Short-Term

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

Related to this query field is the checkLocalClusterConnection() query to validate a local cluster connection.

Syntax

graphql
checkRemoteClusterConnection(
      input: CheckRemoteClusterConnectionInput!
    ): RemoteClusterConnectionStatus

For the input, you'd enter parameters for checking a remote cluster connection, such as the public URL of the cluster. See the Given Datatype section for more. 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 parameters.

Example

Below is an example of how this query can be used:

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
    }
  }
}

Given Datatype

For given datatype, there are a few parameters you'll to provide, along with some optional ones. For instance, you'll have to specify 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

ParameterTypeRequiredDefaultStabilityDescription
Some arguments may be required, as indicated in the Required column. For return datatypes, this indicates that you must specify which fields you want returned in the results.
Table last updated: Sep 17, 2024
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 Datatype

The returned datatype is used to list the status information you want returned from the check. At a minimum, you'll probably wan to know that the connection is valid. You may want to know the version that the cluster is running. There are several choices available; They're listed below:

Table: RemoteClusterConnectionStatus

ParameterTypeRequiredDefaultStabilityDescription
Some arguments may be required, as indicated in the Required column. For return datatypes, this indicates that you must specify which fields you want returned in 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.