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

      +

      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
      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
      curl -v -u Administrator:password http://localhost:8095/analytics/cluster

      Example HTTP response

      Response 200
      {
  "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
      curl -v -u Administrator:password -X POST http://localhost:8095/analytics/cluster/restart

      Example HTTP response

      Response 202
      {
  "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
      curl -v -u Administrator:password -X POST http://localhost:8095/analytics/node/restart

      Example HTTP response

      Response 202
      {"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
      curl -v -u Administrator:password http://localhost:8095/analytics/status/ingestion

      Example HTTP response

      Response 200
      {
  "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
      curl -v -u Administrator:password http://localhost:8095/analytics/node/agg/stats/remaining

      Example HTTP response

      Response 200
      {
  "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.