Summary

The checkRemoteClusterConnection() GraphQL query validates a remote cluster connection to confirm it is configured correctly and reachable.

Hide Query Example

Show Cluster Nodes Query

API Stability Short-Term

Syntax

graphql
checkRemoteClusterConnection(
      input: CheckRemoteClusterConnectionInput!
   ): RemoteClusterConnectionStatus!

For the input, publicUrl (required) is the public URL of the remote cluster. When checking an existing connection, supply connectionId or multiClusterViewName. token is needed for new connections but can be omitted when rechecking an existing connection with no token change. tags and queryPrefix restrict query visibility through the connection. See Input Parameters for details.

For the results, primarily request isValid and errorMessages. See Returned Values for all options.

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, publicUrl is required. When checking an existing connection, supply connectionId or multiClusterViewName. Supply token for new connections; it can be omitted when rechecking an existing connection with no token change. Optional tags and queryPrefix restrict the data visible through the connection. The parameters are listed here:

Table: CheckRemoteClusterConnectionInput Input 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 
connectionIdString  Short-Term The unique identifier of the connection to check. Must be supplied if the token is not supplied.
multiClusterViewNameString  Short-Term The name of the multi-cluster view to which the connection belongs. Must be supplied if the token is not supplied.
proxySettingsFederatedProxySettingsInput    Proxy settings for this connection.
publicUrlStringyes Short-Term The public URL of the remote cluster to connect.
queryPrefixString  Short-Term Filter query that restricts the data visible through this connection.
tagsClusterConnectionInputTagyes Short-Term Additional tags that can be used to filter queries. See ClusterConnectionInputTag.
tokenString  Short-Term The 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, isValid indicates whether the connection is valid, and errorMessages lists any errors when it is not. You can also get the id of the connection, the remoteViewName, and the remoteServerVersion of the remote cluster. The available fields are listed here:

Table: RemoteClusterConnectionStatus 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: Jul 1, 2025 
errorMessages[ConnectionAspectErrorType]yes Short-Term Errors if the connection is invalid. See ConnectionAspectErrorType.
idstring  Short-Term The unique identifier of the connection.
isValidbooleanyes Short-Term Whether the connection is valid.
remoteServerVersionstring  Short-Term Software version of the remote view.
remoteViewNamestring  Short-Term The name of the remote view.