Admin REST API

Overview

The Admin REST API is a secondary API provided by the Query service. This API enables you to retrieve statistics about the clusters and nodes running the Query service; view or specify service-level settings; and view or delete requests.

The API schemes and host URLs are as follows:

  • http://node:8093/

  • https://node:18093/ (for secure access)

where node is the host name or IP address of a computer running the N1QL query engine.

Version information

Version : 6.0

Consumes

  • application/x-www-form-urlencoded

  • application/json

Produces

  • application/json

Paths

GET /admin/clusters

Description

Returns information about all clusters.

Responses

HTTP Code Description Schema

200

An array of objects, each of which gives information about one cluster.

< Clusters > array

Security

Type Name

basic

GET /admin/clusters/{cluster}

Description

Returns information about the specified cluster.

Parameters

Type Name Description Schema

Path

cluster
required

The name of a cluster.

string

Responses

HTTP Code Description Schema

200

An object giving information about the specified cluster.

Security

Type Name

basic

GET /admin/clusters/{cluster}/nodes

Description

Returns information about all nodes in the specified cluster.

Parameters

Type Name Description Schema

Path

cluster
required

The name of a cluster.

string

Responses

HTTP Code Description Schema

200

An array of objects, each of which gives information about one node.

< Nodes > array

Security

Type Name

basic

GET /admin/clusters/{cluster}/nodes/{node}

Description

Returns information about the specified node in the specified cluster.

Parameters

Type Name Description Schema

Path

cluster
required

The name of a cluster.

string

Path

node
required

The name of a node.

string

Responses

HTTP Code Description Schema

200

An object giving information about the specified node.

Security

Type Name

basic

GET /admin/config

Description

Returns the configuration of the query service on the cluster.

Responses

HTTP Code Description Schema

200

An object giving information about the specified node.

Security

Type Name

basic

GET /admin/prepareds

Description

Returns all prepared statements.

Refer to Get Prepared Statements for examples.

Responses

HTTP Code Description Schema

200

An array of objects, each of which contains information about one prepared statement.

< Statements > array

Security

Type Name

basic

GET /admin/prepareds/{name}

Description

Returns the specified prepared statement.

Refer to Get Prepared Statements for examples.

Parameters

Type Name Description Schema

Path

name
required

The name of a prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created.

string

Responses

HTTP Code Description Schema

200

An object containing information about the specified prepared statement.

Security

Type Name

basic

DELETE /admin/prepareds/{name}

Description

Deletes the specified prepared statement.

Refer to Delete Prepared Statements for examples.

Parameters

Type Name Description Schema

Path

name
required

The name of a prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created.

string

Responses

HTTP Code Description Schema

200

True if the prepared statement was successfully deleted.

boolean

500

Returns an error message if the prepared statement could not be found.

object

Security

Type Name

basic

GET /admin/active_requests

Description

Returns all active query requests.

Refer to Get Active Requests for examples.

Responses

HTTP Code Description Schema

200

An array of objects, each of which contains information about one active request.

< Requests > array

Security

Type Name

basic

GET /admin/active_requests/{request}

Description

Returns the specified active query request.

Refer to Get Active Requests for examples.

Parameters

Type Name Description Schema

Path

request
required

The name of a request. This is the requestID that was assigned automatically when the statement was created.

string

Responses

HTTP Code Description Schema

200

An object containing information about the specified active request.

Security

Type Name

basic

DELETE /admin/active_requests/{request}

Description

Terminates the specified active query request.

Refer to Terminate an Active Request for examples.

Parameters

Type Name Description Schema

Path

request
required

The name of a request. This is the requestID that was assigned automatically when the statement was created.

string

Responses

HTTP Code Description Schema

200

True if the active request was successfully terminated.

boolean

500

Returns an error message if the active request could not be found.

object

Security

Type Name

basic

GET /admin/completed_requests

Description

Returns all completed requests.

Refer to Get Completed Requests for examples.

Responses

HTTP Code Description Schema

200

An array of objects, each of which contains information about one completed request.

< Requests > array

Security

Type Name

basic

GET /admin/completed_requests/{request}

Description

Returns the specified completed request.

Refer to Get Completed Requests for examples.

Parameters

Type Name Description Schema

Path

request
required

The name of a request. This is the requestID that was assigned automatically when the statement was created.

string

Responses

HTTP Code Description Schema

200

An object containing information about the specified active request.

Security

Type Name

basic

DELETE /admin/completed_requests/{request}

Description

Purges the specified completed request.

Refer to Purge the Completed Requests for examples.

Parameters

Type Name Description Schema

Path

request
required

The name of a request. This is the requestID that was assigned automatically when the statement was created.

string

Responses

HTTP Code Description Schema

200

True if the completed request was successfully purged.

boolean

500

Returns an error message if the completed request could not be found.

object

Security

Type Name

basic

GET /admin/indexes/prepareds

Description

Returns all prepared index statements.

Responses

HTTP Code Description Schema

200

An array of strings, each of which is the name of a prepared index statement.

< string > array

Security

Type Name

basic

GET /admin/indexes/active_requests

Description

Returns all active index requests.

Responses

HTTP Code Description Schema

200

An array of strings, each of which is the requestID of an active index request.

< string (uuid) > array

Security

Type Name

basic

GET /admin/indexes/completed_requests

Description

Returns all completed index requests.

Responses

HTTP Code Description Schema

200

An array of strings, each of which is the requestID of a completed index request.

< string (uuid) > array

Security

Type Name

basic

GET /admin/ping

Description

Returns a minimal response, indicating that the service is running and reachable.

Responses

HTTP Code Description Schema

200

An empty object.

object

Security

Type Name

basic

Example HTTP response

Response 200
{
  "application:json" : { }
}

GET /admin/vitals

Description

Returns data about the running state and health of the query engine. This information can be very useful to assess the current workload and performance characteristics of a query engine, and hence load-balance the requests being sent to various query engines.

Refer to Get System Vitals for examples.

Responses

HTTP Code Description Schema

200

An object containing all vital statistics.

Security

Type Name

basic

GET /admin/stats

Description

Returns all statistics.

Responses

HTTP Code Description Schema

200

An object containing all statistics. Each statistic consist of a top-level statistic name and a metric name. Each statistic has a different set of metrics.

Security

Type Name

basic

GET /admin/stats/{stat}

Description

Returns the specified statistic.

Parameters

Type Name Description Schema

Path

stat
required

The name of a statistic. Only top-level statistic names can be used. You cannot specify a metric.

enum (active_requests, at_plus, cancelled, deletes, errors, inserts, invalid_requests, mutations, prepared, queued_requests, request_rate, request_time, request_timer, requests, requests_1000ms, requests_250ms, requests_5000ms, requests_500ms, result_count, result_size, scan_plus, selects, service_time, unbounded, updates, warnings)

Responses

HTTP Code Description Schema

200

An object containing all metrics for the specified statistic. Each statistic has a different set of metrics.

Security

Type Name

basic

GET /debug/vars

Description

Currently unused.

Responses

HTTP Code Description Schema

302

Redirects to the GET /admin/stats endpoint.

text/html

Security

Type Name

basic

Example HTTP response

Response 302
{
  "text/html" : "<a href=\"/admin/stats\">Found</a>"
}

GET /admin/settings

Description

Returns service-level query settings.

Refer to Query Settings for more information and examples.

Responses

HTTP Code Description Schema

200

An object giving service-level query settings.

Security

Type Name

basic

POST /admin/settings

Description

Updates service-level query settings.

Refer to Query Settings for more information and examples.

Parameters

Type Name Description Schema

Body

Settings
optional

An object specifying service-level query settings.

Responses

HTTP Code Description Schema

200

An object giving service-level query settings, including the latest changes.

Security

Type Name

basic

Definitions

Clusters

Name Description Schema

accountstore
optional

The URL of the accountstore.

string

configstore
optional

The URL of the configstore.

string

datastore
optional

The URL of the datastore.

string

name
optional

The name of the cluster.

string

version
optional

string

Nodes

Name Description Schema

adminEndpoint
optional

The HTTP URL of the admin endpoint.

string

adminSecure
optional

The HTTPS URL of the admin endpoint.

string

cluster
optional

The name of the cluster.

string

name
optional

The URL of the node, including port number.

string

options
optional

string

queryEndpoint
optional

The HTTP URL of the query endpoint.

string

querySecure
optional

The HTTPS URL of the query endpoint.

string

Requests

Name Description Schema

clientContextID
optional

The opaque ID or context provided by the client.

string (uuid)

elapsedTime
optional

The time taken from when the request was acknowledged by the service to when the request was completed. It includes the time taken by the service to schedule the request.

string (duration)

errorCount
optional

Total number of errors encountered while executing the query.

integer

phaseCounts
optional

Count of documents processed at selective phases involved in the query execution. Refer to Attribute Profile in Query Response for more details and examples.

object

phaseOperators
optional

Indicates the number of each kind of query operators involved in different phases of the query processing. Refer to Attribute Profile in Query Response for more details and examples.

object

remoteAddr
optional

IP address and port number of the client application, from where the query is received.

string

requestId
optional

Unique request ID internally generated for the query.

string (uuid)

requestTime
optional

Timestamp when the query is received.

string (date-time)

resultCount
optional

Total number of documents returned in the query result.

integer

resultSize
optional

Total number of bytes returned in the query result.

integer

scanConsistency
optional

The value of the query setting Scan Consistency used for the query.

string

serviceTime
optional

Total amount of calendar time taken to complete the query.

string (duration)

state
optional

The state of the query execution, such as completed, running, cancelled.

string

statement
optional

The N1QL query statement being executed.

string

userAgent
optional

Name of the client application or program that issued the query.

string

users
optional

Username with whose privileges the query is run.

string

Statements

Name Description Schema

encoded_plan
optional

The full prepared statement in encoded format.

string

featureControls
optional

integer

indexApiVersion
optional

integer

name
optional

The name of the prepared statement. This may be a UUID that was assigned automatically, or a name that was user-specified when the statement was created.

string

statement
optional

The text of the N1QL query.

string

uses
optional

The count of times the prepared statement has been executed.

integer

Vitals

Name Description Schema

cores
optional

Number of logical cores.

integer

cpu.sys.percent
optional

CPU usage.

integer

cpu.user.percent
optional

CPU usage.

integer

gc.num
optional

Garbage collection.

integer

gc.pause.percent
optional

Garbage collection.

integer

gc.pause.time
optional

Garbage collection.

string (duration)

local.time
optional

The local time of the query engine.

string (date-time)

memory.system
optional

Memory usage.

integer

memory.total
optional

Memory usage.

integer

memory.usage
optional

Memory usage.

integer

request.active.count
optional

Total number of active requests.

integer

request.completed.count
optional

Total number of completed requests.

integer

request.per.sec.15min
optional

Number of N1QL requests processed per second. 15-minute exponentially weighted moving average.

number

request.per.sec.1min
optional

Number of N1QL requests processed per second. 1-minute exponentially weighted moving average.

number

request.per.sec.5min
optional

Number of N1QL requests processed per second. 5-minute exponentially weighted moving average.

number

request.prepared.percent
optional

Percentage of requests that are prepared statements.

integer

request_time.80percentile
optional

End-to-end time to process a query. The 80th percentile.

string (duration)

request_time.95percentile
optional

End-to-end time to process a query. The 95th percentile.

string (duration)

request_time.99percentile
optional

End-to-end time to process a query. The 99th percentile.

string (duration)

request_time.mean
optional

End-to-end time to process a query. The mean value.

string (duration)

request_time.median
optional

End-to-end time to process a query. The median value.

string (duration)

total.threads
optional

Active threads.

integer

uptime
optional

The uptime of the query engine.

string (duration)

version
optional

The version of the query engine.

string

Statistics

Name Description Schema

active_requests.count
optional

Total number of active requests.

integer

at_plus.count
optional

Total number of N1QL requests with at_plus index consistency.

integer

cancelled.count
optional

Total number of cancelled requests.

integer

deletes.count
optional

Total number of DELETE operations.

integer

errors.count
optional

The total number of N1QL errors returned so far.

integer

inserts.count
optional

Total number of INSERT operations.

integer

invalid_requests.count
optional

Total number of requests for unsupported endpoints.

integer

mutations.count
optional

Total number of document mutations.

integer

prepared.15m.rate
optional

Prepared statements executed per second. 15-minute exponentially weighted moving average.

number

prepared.1m.rate
optional

Prepared statements executed per second. 1-minute exponentially weighted moving average.

number

prepared.5m.rate
optional

Prepared statements executed per second. 5-minute exponentially weighted moving average.

number

prepared.count
optional

Total number of prepared statements executed.

integer

prepared.mean.rate
optional

Prepared statements executed per second. Mean rate since the query service started.

number

queued_requests.count
optional

Total number of queued requests.

integer

request_rate.15m.rate
optional

Number of N1QL requests processed per second. 15-minute exponentially weighted moving average.

integer

request_rate.1m.rate
optional

Number of N1QL requests processed per second. 1-minute exponentially weighted moving average.

integer

request_rate.5m.rate
optional

Number of N1QL requests processed per second. 5-minute exponentially weighted moving average.

integer

request_rate.count
optional

Total number of N1QL requests.

integer

request_rate.mean.rate
optional

Number of N1QL requests processed per second. Mean rate since the query service started.

number

request_time.count
optional

Total end-to-end time to process all queries (ns).

integer

request_timer.15m.rate
optional

Number of N1QL requests processed per second. 15-minute exponentially weighted moving average.

number

request_timer.1m.rate
optional

Number of N1QL requests processed per second. 1-minute exponentially weighted moving average.

number

request_timer.5m.rate
optional

Number of N1QL requests processed per second. 5-minute exponentially weighted moving average.

number

request_timer.75%
optional

End-to-end time to process a query (ns). The 75th percentile.

number

request_timer.95%
optional

End-to-end time to process a query (ns). The 95th percentile.

number

request_timer.99%
optional

End-to-end time to process a query (ns). The 99th percentile.

number

request_timer.99.9%
optional

End-to-end time to process a query (ns). The 99.9th percentile.

number

request_timer.count
optional

Total number of N1QL requests.

integer

request_timer.max
optional

End-to-end time to process a query (ns). The maximum value.

integer

request_timer.mean
optional

End-to-end time to process a query (ns). The mean value.

number

request_timer.mean.rate
optional

Number of N1QL requests processed per second. Mean rate since the query service started.

number

request_timer.median
optional

End-to-end time to process a query (ns). The median value.

number

request_timer.min
optional

End-to-end time to process a query (ns). The minimum value.

integer

request_timer.stddev
optional

End-to-end time to process a query (ns). The standard deviation.

number

requests.count
optional

Total number of N1QL requests.

integer

requests_1000ms.count
optional

Number of queries that take longer than 1000ms.

integer

requests_250ms.count
optional

Number of queries that take longer than 250ms.

integer

requests_5000ms.count
optional

Number of queries that take longer than 5000ms.

integer

requests_500ms.count
optional

Number of queries that take longer than 500ms.

integer

result_count.count
optional

Total number of results (documents) returned by the query engine.

integer

result_size.count
optional

Total size of data returned by the query engine (bytes).

integer

scan_plus.count
optional

Total number of N1QL requests with request_plus index consistency.

integer

selects.count
optional

Total number of SELECT requests.

integer

service_time.count
optional

Time to execute all queries (ns).

integer

unbounded.count
optional

Total number of N1QL requests with not_bounded index consistency.

integer

updates.count
optional

Total number of UPDATE requests.

integer

warnings.count
optional

The total number of N1QL warnings returned so far.

integer

Metrics

Name Description Schema

15m.rate
optional

15-minute exponentially weighted moving average.

number

1m.rate
optional

1-minute exponentially weighted moving average.

number

5m.rate
optional

5-minute exponentially weighted moving average.

number

75%
optional

The 75th percentile.

number

95%
optional

The 95th percentile.

number

99%
optional

The 99th percentile.

number

99.9%
optional

The 99.9th percentile.

number

count
optional

A single value that represents the current state.

integer

max
optional

The maximum value.

integer

mean
optional

The mean value.

number

mean.rate
optional

Mean rate since the query service started.

number

median
optional

The median value.

number

min
optional

The minimum value.

integer

stddev
optional

The standard deviation.

number

Settings

Name Description Schema

completed-limit
optional

Maximum number of completed requests. As new completed requests are added, old ones are removed. Refer to Configure the Completed Requests for more information and examples.
Default : 4000
Example : 7000

integer (int32)

completed-threshold
optional

A duration in milliseconds. All completed queries lasting longer than this threshold are logged in the completed requests catalog. Refer to Configure the Completed Requests for more information and examples.
Default : 1000
Example : 7000

integer (int32)

controls
optional

Specifies if there should be a controls section returned with the request results.
Default : false
Example : true

boolean

cpuprofile
optional

The absolute path and filename to write the CPU profile to a local file.
Default : ""
Example : "/tmp/info.txt"

string

debug
optional

Use debug mode.
Default : false
Example : true

boolean

keep-alive-length
optional

Maximum size of buffered result.
Default : 16384
Example : 7000

integer (int32)

loglevel
optional

Log level used in the logger.
Default : "INFO"
Example : "DEBUG"

enum (DEBUG, TRACE, INFO, WARN, ERROR, SEVERE, NONE)

max-index-api
optional

Max index API. This setting is provided for technical support only.

integer (int32)

max-parallelism
optional

Maximum number of index partitions, for computing aggregation in parallel. Refer to Max Parallelism for more information.
Default : 1
Example : 0

integer (int32)

memprofile
optional

Filename to write the diagnostic memory usage log.
Default : ""
Example : "/tmp/memory-usage.log"

string

n1ql-feat-ctrl
optional

N1QL feature control. This setting is provided for technical support only.

integer (int32)

pipeline-batch
optional

Controls the number of items execution operators can batch for Fetch from the KV.
Default : 16
Example : 64

integer (int32)

pipeline-cap
optional

Maximum number of items each execution operator can buffer between various operators.
Default : 512
Example : 1024

integer (int32)

prepared-limit
optional

Maximum number of prepared statements in the cache.
Default : 16384
Example : 65536

integer (int32)

pretty
optional

Specifies whether query results are returned in pretty format.
Default : false
Example : true

boolean

profile
optional

Specifies if there should be a profile section returned with the request results. Refer to Monitoring and Profiling Details for more information and examples.
Default : "off"
Example : "phases"

enum (off, phases, timings)

request-size-cap
optional

Maximum size of a request.
Default : 67108864
Example : 70000

integer (int32)

scan-cap
optional

Maximum buffered channel size between the indexer client and the query service for index scans. This parameter controls when to use scan backfill.
Default : 512
Example : 1024

integer (int32)

servicers
optional

The number of service threads for the query.
Default : 32
Example : 8

integer (int32)

timeout
optional

Maximum time to spend on the request before timing out.
Default : "0s"
Example : "30m"

string (duration)

Security

Default

The Admin API supports admin credentials. Credentials can be passed via HTTP headers (HTTP basic authentication).

Type : basic

None

No authentication is required for the GET /admin/ping or GET /debug/vars endpoints.

Type : basic