Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Analytics Administration REST APIs

    March 16, 2025
    + 12

    Overview

    The Analytics Administration REST APIs are provided by the Analytics service. These APIs enables you to manage and monitor the Analytics service.

    The API schemes and host URLs are as follows:

    where node is the host name or IP address of a node running the Analytics service.

    Version information

    Version : 7.1

    Consumes

    • application/x-www-form-urlencoded

    Produces

    • application/json

    Paths

    This section describes the operations available with these REST APIs.

    Request Cancellation

    DELETE /analytics/admin/active_requests

    Description

    Cancels an active request.

    Parameters

    Type Name Description Schema

    FormData

    client_context_id
    required

    Identifier passed by the client that is used to identify an active request to be cancelled.

    string

    Responses

    HTTP Code Description Schema

    200

    The operation was successful.

    No Content

    400

    Bad request. Incorrect parameter or missing value.

    No Content

    401

    Unauthorized. The user name or password may be incorrect.

    Returns an object containing an error message. Refer to Error Codes.

    object

    404

    Not found. The path may be incorrect, or there is no active request with the specified identifier.

    No Content

    Security

    Type Name

    basic

    Analytics Manage / Analytics Select

    Example HTTP request

    The example below uses the client_context_id used in the Query Service example to identify the request.

    Curl request
    sh
    Copy
    curl -v -u Administrator:password -X DELETE \
     http://localhost:8095/analytics/admin/active_requests \
     -d client_context_id=xyz

    Cluster Status

    GET /analytics/cluster

    Description

    Shows various details about the current status of the Analytics Service, such as the service state, the state of each node partition, and the replicas of each partition.

    Responses

    HTTP Code Description Schema

    200

    Success. Returns an object giving the current status of the Analytics Service.

    Status

    401

    Unauthorized. The user name or password may be incorrect.

    Returns an object containing an error message. Refer to Error Codes.

    object

    404

    Not found. The path may be incorrect.

    No Content

    Security

    Type Name

    basic

    Cluster Read / Pools Read

    Example HTTP request

    Curl request
    sh
    Copy
    curl -v -u Administrator:password http://localhost:8095/analytics/cluster

    Example HTTP response

    Response 200
    json
    Copy
    {
  "authorizedNodes": [
    "86586a966202b5aa4aed31633f330aba",
    "948fb3af810a9b7bc6c76e2a69ba35d9"
  ],
  "ccNodeId": "86586a966202b5aa4aed31633f330aba",
  "nodeConfigUri": "/analytics/config/node",
  "nodeDiagnosticsUri": "/analytics/node/diagnostics",
  "nodeRestartUri": "/analytics/node/restart",
  "nodeServiceUri": "/analytics/service",
  "nodes": [
    {
      "apiBase": "http://192.168.8.101:8095",
      "apiBaseHttps": "https://192.168.8.101:18095",
      "nodeId": "86586a966202b5aa4aed31633f330aba",
      "nodeName": "192.168.8.101:8091"
    },
    {
      "apiBase": "http://192.168.8.102:8095",
      "apiBaseHttps": "https://192.168.8.102:18095",
      "nodeId": "948fb3af810a9b7bc6c76e2a69ba35d9",
      "nodeName": "192.168.8.102:8091"
    }
  ],
  "partitions": [
    {
      "active": true,
      "activeNodeId": "86586a966202b5aa4aed31633f330aba",
      "iodeviceNum": 0,
      "nodeId": "86586a966202b5aa4aed31633f330aba",
      "partitionId": 0,
      "path": "/data/@analytics/v_iodevice_0",
      "pendingActivation": false
    },
    {
      "active": true,
      "activeNodeId": "948fb3af810a9b7bc6c76e2a69ba35d9",
      "iodeviceNum": 0,
      "nodeId": "948fb3af810a9b7bc6c76e2a69ba35d9",
      "partitionId": 1,
      "path": "/data/@analytics/v_iodevice_0",
      "pendingActivation": false
    }
  ],
  "partitionsTopology": {
    "balanced": true,
    "ccNodeId": "86586a966202b5aa4aed31633f330aba",
    "metadataPartition": -1,
    "numReplicas": 1,
    "partitions": [
      {
        "id": "0",
        "master": "86586a966202b5aa4aed31633f330aba",
        "origin": "86586a966202b5aa4aed31633f330aba",
        "replicas": [
          {
            "location": "192.168.8.102:9120",
            "nodeId": "948fb3af810a9b7bc6c76e2a69ba35d9",
            "status": "IN_SYNC",
            "syncProgress": "1"
          }
        ]
      },
      {
        "id": "1",
        "master": "948fb3af810a9b7bc6c76e2a69ba35d9",
        "origin": "948fb3af810a9b7bc6c76e2a69ba35d9",
        "replicas": [
          {
            "location": "192.168.8.101:9120",
            "nodeId": "86586a966202b5aa4aed31633f330aba",
            "status": "IN_SYNC",
            "syncProgress": "1"
          }
        ]
      },
      {
        "id": "-1",
        "master": "86586a966202b5aa4aed31633f330aba",
        "origin": "86586a966202b5aa4aed31633f330aba",
        "replicas": [
          {
            "location": "192.168.8.102:9120",
            "nodeId": "948fb3af810a9b7bc6c76e2a69ba35d9",
            "status": "IN_SYNC",
            "syncProgress": "1"
          }
        ]
      }
    ],
    "revision": 1,
    "version": 1
  },
  "serviceConfigUri": "/analytics/config/service",
  "serviceDiagnosticsUri": "http://localhost:8095/analytics/cluster/diagnostics",
  "serviceRestartUri": "http://localhost:8095/analytics/cluster/restart",
  "state": "ACTIVE"
}

    Cluster Restart

    POST /analytics/cluster/restart

    Description

    Restarts all Analytics Service nodes in the cluster.

    Responses

    HTTP Code Description Schema

    202

    Accepted. Returns an object showing the status of the cluster.

    object

    401

    Unauthorized. The user name or password may be incorrect.

    Returns an object containing an error message. Refer to Error Codes.

    object

    404

    Not found. The path may be incorrect.

    No Content

    Security

    Type Name

    basic

    Analytics Manage

    Example HTTP request

    Curl request
    sh
    Copy
    curl -v -u Administrator:password -X POST http://localhost:8095/analytics/cluster/restart

    Example HTTP response

    Response 202
    json
    Copy
    {
  "cluster" : {
    "metadata_node" : "edfb6de9c91d7fb36399fea3ce620c5c",
    "ncs" : [ {
      "node_id" : "edfb6de9c91d7fb36399fea3ce620c5c",
      "partitions" : [ {
        "active" : true,
        "partition_id" : "partition_0"
      } ],
      "pid" : 5763,
      "state" : "ACTIVE"
    } ],
    "state" : "ACTIVE"
  },
  "date" : "Wed Oct 10 15:35:56 BST 2018",
  "status" : "SHUTTING_DOWN"
}

    Node Restart

    POST /analytics/node/restart

    Description

    Restarts the specified Analytics Service node.

    Responses

    HTTP Code Description Schema

    202

    Accepted. Returns an object showing the status of the node.

    object

    401

    Unauthorized. The user name or password may be incorrect.

    Returns an object containing an error message. Refer to Error Codes.

    object

    404

    Not found. The path may be incorrect.

    No Content

    Security

    Type Name

    basic

    Analytics Manage

    Example HTTP request

    Curl request
    sh
    Copy
    curl -v -u Administrator:password -X POST http://localhost:8095/analytics/node/restart

    Example HTTP response

    Response 202
    json
    Copy
    {"status": "restarting node"}

    Ingestion Status

    GET /analytics/status/ingestion

    Description

    Shows the progress of ingestion by the Analytics service, for each Analytics collection.

    Responses

    HTTP Code Description Schema

    200

    Success. Returns an object giving the ingestion status of each Analytics collection.

    Ingestion

    401

    Unauthorized. The user name or password may be incorrect.

    Returns an object containing an error message. Refer to Error Codes.

    object

    404

    Not found. The path may be incorrect.

    No Content

    Security

    Type Name

    basic

    Analytics Manage / Analytics Select

    Example HTTP request

    Curl request
    sh
    Copy
    curl -v -u Administrator:password http://localhost:8095/analytics/status/ingestion

    Example HTTP response

    Response 200
    json
    Copy
    {
  "links": [
    {
      "name": "Local",
      "scope": "travel-sample/tenant_agent_02",
      "status": "healthy",
      "state": [
        {
          "timestamp": 1631107234921,
          "progress": 1,
          "scopes": [
            {
              "collections": [
                {
                  "name": "users"
                }
              ],
              "name": "travel-sample/tenant_agent_02"
            }
          ]
        }
      ]
    },
    {
      "name": "Local",
      "scope": "travel-sample/inventory",
      "status": "healthy",
      "state": [
        {
          "timestamp": 1631107234921,
          "progress": 1,
          "scopes": [
            {
              "collections": [
                {
                  "name": "airport"
                },
                {
                  "name": "landmark"
                }
              ],
              "name": "travel-sample/inventory"
            }
          ]
        },
        {
          "timestamp": 1631107234921,
          "progress": 0.9821428571428571,
          "timeLag": 4840,
          "itemsProcessed": 23595,
          "seqnoAdvances": 49129,
          "scopes": [
            {
              "collections": [
                {
                  "name": "route"
                }
              ],
              "name": "travel-sample/inventory"
            }
          ]
        }
      ]
    }
  ]
}

    Pending Mutations

    GET /analytics/node/agg/stats/remaining

    operation.deprecated

    Description

    Shows the number of mutations in the DCP queue that have not yet been ingested by the Analytics service, for each Analytics collection.

    This endpoint may not return meaningful results in Couchbase Server 7.0 and later. The reported number of mutations may be different to the actual number of mutations in the Analytics collection. For this reason, this endpoint has been deprecated, and you should use the Ingestion Status endpoint instead.

    Responses

    HTTP Code Description Schema

    200

    Success. Returns an object giving the number of pending mutations for each Analytics collection.

    Mutations

    401

    Unauthorized. The user name or password may be incorrect.

    Returns an object containing an error message. Refer to Error Codes.

    object

    404

    Not found. The path may be incorrect.

    No Content

    Security

    Type Name

    basic

    Analytics Manage / Analytics Select

    Example HTTP request

    Curl request
    sh
    Copy
    curl -v -u Administrator:password http://localhost:8095/analytics/node/agg/stats/remaining

    Example HTTP response

    Response 200
    json
    Copy
    {
  "Commerce": {
    "orders": 0,
    "customers": 0
  }
}

    Definitions

    This section describes the properties returned by these REST APIs.

    Status

    An object giving information about the status of the Analytics service.

    Name Description Schema

    authorizedNodes
    optional

    An array of strings, each of which is the ID of an authorized Analytics node.
    Example : [ "86586a966202b5aa4aed31633f330aba", "948fb3af810a9b7bc6c76e2a69ba35d9" ]

    < string > array

    ccNodeId
    optional

    The ID of the cluster controller node.
    Example : "86586a966202b5aa4aed31633f330aba"

    string

    nodeConfigUri
    optional

    The path of the Analytics Node Configuration REST API.
    Example : "/analytics/config/node"

    string

    nodeDiagnosticsUri
    optional

    The path of the Analytics Node Diagnostics REST API. For internal use only.
    Example : "/analytics/node/diagnostics"

    string

    nodeRestartUri
    optional

    The path of the Analytics Node Restart REST API.
    Example : "/analytics/node/restart"

    string

    nodeServiceUri
    optional

    The path of the Analytics Query Service REST API.
    Example : "/analytics/service"

    string

    serviceConfigUri
    optional

    The path of the Analytics Service Configuration REST API.
    Example : "/analytics/config/service"

    string

    serviceDiagnosticsUri
    optional

    The full URI of the Analytics Service Diagnostics REST API. For internal use only.
    Example : "http://localhost:8095/analytics/cluster/diagnostics"

    string

    serviceRestartUri
    optional

    The full URI of the Analytics Cluster Restart REST API.
    Example : "http://localhost:8095/analytics/cluster/restart"

    string

    state
    optional

    The state of the Analytics Service.
    Example : "ACTIVE"

    enum (ACTIVE, REBALANCE_REQUIRED, UNUSABLE, SHUTTING_DOWN)

    nodes
    optional

    An array of objects, each giving information about one Analytics node.

    < Nodes > array

    partitions
    optional

    An array of objects, each giving information about one Analytics partition.

    < Partitions > array

    partitionsTopology
    optional

    An object giving information about the partition topology.

    Partition Topology

    Nodes

    Name Description Schema

    apiBase
    optional

    The URI scheme, host, and port for HTTP access to Analytics REST APIs on this node.
    Example : "http://192.168.8.101:8095"

    string

    apiBaseHttps
    optional

    The URI scheme, host, and port for secure HTTPS access to Analytics REST APIs on this node.
    Example : "https://192.168.8.101:18095"

    string

    nodeId
    optional

    The ID of the node.
    Example : "86586a966202b5aa4aed31633f330aba"

    string

    nodeName
    optional

    The name or IP address of the node, including the cluster administration port.
    Example : "192.168.8.101:8091"

    string

    Partitions

    Name Description Schema

    active
    optional

    Indicates whether this partition is active.
    Example : true

    boolean

    activeNodeId
    optional

    The ID of the node where this partition is currently active.
    Example : "86586a966202b5aa4aed31633f330aba"

    string

    iodeviceNum
    optional

    The number of the IO Device where this partition is located.
    Example : 0

    integer

    nodeId
    optional

    The ID of the node where this partition originated.
    Example : "86586a966202b5aa4aed31633f330aba"

    string

    partitionId
    optional

    The ID of this partition.
    Example : 0

    integer

    path
    optional

    The path of the IO Device where this partition is located.
    Example : "/data/@analytics/v_iodevice_0"

    string

    pendingActivation
    optional

    Indicates whether this partition is waiting to become active.
    Example : false

    boolean

    Partition Topology

    Name Description Schema

    balanced
    optional

    Indicates whether the Analytics nodes are balanced.
    Example : true

    boolean

    ccNodeId
    optional

    The ID of the cluster controller node.
    Example : "86586a966202b5aa4aed31633f330aba"

    string

    metadataPartition
    optional

    The ID of the metadata partition.
    Example : -1

    integer

    numReplicas
    optional

    The number of Analytics replicas.
    Example : 1

    integer

    revision
    optional

    The revision number of the partition topology.
    Example : 1

    integer

    version
    optional

    The version number of the partition topology.
    Example : 1

    integer

    partitions
    optional

    An array of objects, each giving information about the state of one Analytics partition.

    < Partition States > array

    Partition States

    Name Description Schema

    id
    optional

    The partition ID.
    Example : 0

    integer

    master
    optional

    The ID of the node where the partition is currently active.
    Example : "86586a966202b5aa4aed31633f330aba"

    string

    origin
    optional

    The ID of the node where the partition originated.
    Example : "86586a966202b5aa4aed31633f330aba"

    string

    replicas
    optional

    An array of objects, each giving information about the state of one Analytics replica.

    < Replicas > array

    Replicas

    Name Description Schema

    location
    optional

    The name or IP address of the node where this replica is located, including the Analytics replication port.
    Example : "192.168.8.102:9120"

    string

    nodeId
    optional

    The ID of the node where this replica is located.
    Example : "948fb3af810a9b7bc6c76e2a69ba35d9"

    string

    status
    optional

    The synchronization status of the replica.
    Example : "IN_SYNC"

    enum (IN_SYNC, CATCHING_UP, DISCONNECTED)

    syncProgress
    optional

    The percentage (fraction from 0 to 1) of synchronization progress for this replica at the current time.
    Minimum value : 0
    Maximum value : 1
    Example : 1.0

    number (double)

    Ingestion

    An object containing a single links property.

    Name Description Schema

    links
    optional

    An array of objects, each giving information about a single linked Analytics scope.

    < Links > array

    Links

    Name Description Schema

    name
    optional

    The name of the link.
    Example : "Local"

    string

    scope
    optional

    The name of the Analytics scope.
    Example : "travel-sample/inventory"

    string

    status
    optional

    The status of the Analytics scope.
    Example : "healthy"

    enum (healthy, stopped, unhealthy, suspended)

    state
    optional

    An array of objects, each giving the ingestion state of one or more Analytics collections.

    Analytics collections which have the same ingestion state within this Analytics scope are aggregated together.

    < States > array

    States

    Name Description Schema

    timestamp
    required

    The time since epoch that this sample was calculated, in milliseconds.
    Example : 1631273689161

    integer

    progress
    required

    The percentage (fraction from 0 to 1) of ingestion progress at the current time.
    Minimum value : 0
    Maximum value : 1
    Example : 0.0

    number (double)

    timeLag
    optional

    The estimated time that the ingestion lags behind the Data service, in milliseconds. Only displayed for Analytics collections that are not fully ingested.
    Example : 9744

    integer

    itemsProcessed
    optional

    The number of items ingested since last connect; that is, the total number of mutations and deletions processed. Only displayed for Analytics collections that are not fully ingested.

    Note that this value is reset on connect, so it may appear to get smaller.
    Example : 12301

    integer

    seqnoAdvances
    optional

    The change in sequence number (seqno) since last connect. Only displayed for Analytics collections that are not fully ingested.
    Example : 61

    integer

    scopes
    required

    An array of objects, each one giving information about a single Analytics scope.

    < State Scopes > array

    State Scopes

    Name Description Schema

    name
    required

    The name of the Analytics scope.
    Example : "travel-sample/inventory"

    string

    collections
    required

    An array of objects, each one giving information about a single Analytics collection.

    < State Collections > array

    State Collections

    Name Description Schema

    name
    required

    The name of the Analytics collection.
    Example : "route"

    string

    Mutations

    An object containing one or more nested scope objects, one for each available Analytics scope.

    Name Description Schema

    scope
    optional

    An object containing one or more collection properties, one for each Analytics collection in the Analytics scope. The name of the object is the name of the Analytics scope, in display form.

    Collections

    Collections

    Name Description Schema

    collection
    optional

    The number of mutations in the DCP queue that have not yet been ingested. The name of the property is the name of the Analytics collection.

    integer

    Security

    The Analytics Administration REST APIs support HTTP basic authentication. Credentials can be passed via HTTP headers.

    Analytics Manage / Analytics Select

    For the Request Cancellation, Ingestion Status, and Pending Mutations operations, users must have one of the following access roles:

    • Full Admin

    • Cluster Admin

    • Analytics Manager

    • Analytics Reader

    • Analytics Select

    • Analytics Admin

    Type : basic

    Cluster Read / Pools Read

    For the Cluster Status operation, users must have one of the following access roles:

    • Full Admin

    • Cluster Admin

    • Read-Only Admin

    • Analytics Admin

    Type : basic

    Analytics Manage

    For the Cluster Restart and Node Restart operations, users must have one of the following RBAC roles:

    • Full Admin

    • Cluster Admin

    • Analytics Admin

    Type : basic

    Refer to Roles for more details.