A newer version of this documentation is available.

View Latest

Get Information on Tasks

      +
      The Backup Service REST API allows information to be retrieved on the task history of an active, imported, or archived repository.

      HTTP Methods and URIs

      GET /cluster/self/repository/< "active" | "imported" | "archived" >/<repository-name>/taskHistory
      
      GET /cluster/self/repository/< "active" | "imported" | "archived" >/<repository-name>/taskHistory?<task-subset-specification>

      Description

      The GET /cluster/self/repository/active/<repository-name>/taskHistory http method and URI return an array containing the entire task history for the repository specified by the repository-name path-parameter.

      The GET /cluster/self/repository/active/<repository-name>/taskHistory?<task-subset-specification> http method and URI return an array containing the task history for a subset of the tasks performed for the repository specified by the repository-name path-parameter.

      In each case, the repository-name can be that of an active, imported, or archived repository.

      Curl Syntax

      curl -X GET http://<backup-node-ip-address-or-domain-name>:8097/cluster/self\
      /repository/< "active" | "imported" | "archived" >/<repository-name>\
      /taskHistory
      -u <username>:<password>
      
      curl -X GET http://<backup-node-ip-address-or-domain-name>:8097/cluster/self\
      /repository/< "active" | "imported" | "archived" >/<repository-name>\
      /taskHistory?<task-subset-specification>
      -u <username>:<password>

      A subset of tasks to be returned is optionally determined by the task-subset-specification, whose syntax is as follows:

      first=<date>&limit=<integer>&taskName=<task-name>

      The date specified as the value of the query parameter first is the earliest date for which tasks are included. The integer specified as the value of the query parameter limit is the maximum number of tasks to be returned. The string provided as the value of the optional query parameter taskName is the name of the single task to be returned.

      The username and password must identify an administrator with the Full Admin role.

      Responses

      Successful execution returns 200 OK, and an array each of whose members is an object containing information on a task discharged for the repository. If an invalid parameter is specified, 400 is returned. If the specified repository cannot be found, 404 Object Not Found is returned. If an internal error prevents successful execution, 500 Internal Server Error is returned. Failure to authenticate returns 401 Unauthorized. An incorrectly specified URI returns 404 Object Not Found.

      Example

      The following call returns the entire task history for the active repository quarterHourBackups:

      curl -v -X GET http://127.0.0.1:8097/api/v1/cluster/self/\
      repository/active/quarterHourBackups/taskHistory \
      -u Administrator:password

      If the call is successful, the first part of the potentially extensive output may appear as follows:

      [
        {
          "task_name": "fifteenMinuteBackup",
          "status": "done",
          "start": "2020-09-29T13:10:58.100371+01:00",
          "end": "2020-09-29T13:10:58.52634+01:00",
          "node_runs": [
            {
              "node_id": "1208b19a4d30e0b4c6af96b6448b4969",
              "status": "done",
              "start": "2020-09-29T13:10:58.124693+01:00",
              "end": "2020-09-29T13:10:58.507413+01:00",
              "progress": 100,
              "stats": {
                "id": "e1d0199c-3d00-4afc-8275-b65e4e8fead4",
                "current_transfer": 1,
                "total_transfers": 1,
                "transfers": [
                  {
                    "description": "Backing up to 2020-09-29T13_10_58.191631+01_00",
                    "stats": {
                      "buckets": {
                        "travel-sample": {
                          "estimated_total_items": 124,
                          "total_items": 31592,
                          "total_vbuckets": 64,
                          "vbuckets_complete": 64,
                          "bytes_received": 6312,
                          "snapshot_markers_received": 62,
                          "snapshot_ends_received": 64,
                          "failover_logs_received": 64,
                          "complete": true,
                          "errored": false
                        }
                      },
                      "complete": true
                    },
                    "progress": 100,
                    "eta": "2020-09-29T13:10:58.495359+01:00"
                  }
                ],
                "progress": 100,
                "eta": "2020-09-29T13:10:58.495359+01:00"
              },
              "error_code": 0
            }
          ],
          "error_code": 0,
          "type": "BACKUP"
        },
        {
          "task_name": "fifteenMinuteBackup",
          "status": "done",
          "start": "2020-09-29T12:55:57.793738+01:00",
          "end": "2020-09-29T12:55:58.905212+01:00",
                      .
                      .
                      .

      The array thus includes objects for specific runs of the task fifteenMinuteBackup. Each object incudes the start and end time of the task; and lists specific node_runs, with details on buckets whose data was backed up.

      See Also

      An overview of the Backup Service is provided in Backup Service. A step-by-step guide to using Couchbase Web Console to configure and use the Backup Service is provided in Manage Backup and Restore. Information on using the Backup Service REST API to create a plan (and in so doing, define one or more tasks) is provided in Create and Edit Plans.