---
layout: docs
page_title: Consul-Terraform-Sync Status API
description: >-
  Consul-Terraform-Sync Status API
---
# Status

The `/status` endpoints return status-related information for tasks. This endpoint returns a count of successful and failed task events that are recorded whenever tasks execute an automation. Currently, only the five most recent events are stored in Consul-Terraform-Sync (CTS). For more information on the hierarchy of status information and how it is collected, refer to [Status Information](/docs/nia/tasks#status-information).

If you [run CTS with high availability enabled](/docs/nia/usage/run-ha), you can send requests to the `/status` endpoint on CTS leader or follower instances. Requests to a follower instance, however, return a 400 Bad Request and error message. The error message depends on what information the follower instance is able to obtain about the leader. Refer to [Error Messages](/docs/nia/usage/errors-ref) for more information.

## Status for all tasks

This endpoint returns the overall status information for all tasks.

| Method | Path                | Produces           |
| ------ | ------------------- | ------------------ |
| `GET`  | `/status` | `application/json` |

### Request parameters
Currently no request parameters are offered for the overall status API.

### Response statuses

| Status | Reason           |
| ------ | ---------------- |
| 200    | Successfully retrieved the status |

### Response fields

| Name	| Type	 | Description        |
| ----- | ------ | ------------------ |
|`status` | object |  The summary count of how many tasks have a given health status value
|`status.successful` | integer | The number of tasks that have a `successful` health status.
|`status.errored` | integer | The number of tasks that have an `errored` health status.
|`status.critical` | integer | The number of tasks that have a `critical` health status.
|`status.unknown` | integer | The number of tasks that have an `unknown` health status.
|`enabled` | object |  The summary count of how many tasks are enabled or disabled.
|`enabled.true` | integer | The number of tasks that are enabled.
|`enabled.false` | integer | The number of tasks that are disabled.

### Example

Request:
```shell-session
$ curl localhost:8558/v1/status
```

Response:
```json
{
  "task_summary": {
    "status": {
      "successful": 28,
      "errored": 5,
      "critical": 1,
      "unknown": 0
    },
    "enabled": {
      "true": 32,
      "false": 2
    }
  }
}
```

## Task status

This endpoint returns the individual task status information for a single specified task or for all tasks.

Task health status value is determined by the success or failure of all stored [event data](/docs/nia/tasks#event) on the process of updating network infrastructure for a task. Currently only the 5 most recent events are stored per task.
 - Successful: The most recent stored event is successful.
 - Errored: The most recent stored event is not successful but all previous stored events are successful.
 - Critical: The most recent stored event is not successful and one or more previous stored events are also not successful.
 - Unknown: No event data is stored for the task.

| Method | Path                | Produces           |
| ------ | ------------------- | ------------------ |
| `GET`  | `/status/tasks/:task_name` | `application/json` |

### Request parameters

| Name	   | Required | Type	 | Description        | Default |
| -------- | -------- | ------ | ------------------ | ------- |
|`:task_name` | Optional | string | Option to specify the name of the task to return in the response. If not specified, all tasks are returned in the response.| none
|`include` | Optional | string | Only accepts the value `"events"`. Use to include stored event information in response. | none
|`status`  | Optional | string | Only accepts health status values `"successful"`, `"errored"`, `"critical"`, or `"unknown"`. Use to filter response by tasks that have the specified health status value. Recommend setting this parameter when requesting all tasks i.e. no `task` parameter is set. | none

### Response statuses

| Status | Reason           |
| ------ | ---------------- |
| 200  | Successfully retrieved the task status |
| 404  | Task with the given name not found |

### Response fields

The response is a JSON map of task name to a status information structure with the following fields.

| Name	      | Type	  | Description       |
| ----------- | ------ | ------------------ |
|`task_name`  | string | Name of the task as configured in CTS.
|`status`     | string | Values are `"successful"`, `"errored"`, `"critical"`, or `"unknown"`. This is determined by the success or failure of all stored events on the network infrastructure update process for the task, as described earlier.
|`enabled`    | boolean | Whether the task is enabled or not.
|`services`   | list[string] | **Deprecated in CTS 0.5.0 and will be removed in a future major release.** List of the services configured for the task.
|`providers`  | list[string] | **Deprecated in CTS 0.5.0 and will be removed in v0.8.0.** List of the providers configured for the task.
|`events_url` | string | Relative URL to retrieve the event data stored for the task.
|`events`     | list[[Event](/docs/nia/api/status#event)] | List of stored events that inform the task's status. See [section below](/docs/nia/api/status#event) for information on event data. This field is only included in the response upon request by setting the `?include=events` parameter. The relative URL for the request to include events can be retrieved from the `events_url` field.

#### Event

Event represents the process of updating network infrastructure of a task. The data is captured in a JSON structure. For more details on the scope of an event, see [Event](/docs/nia/tasks#event).

| Name	      | Type	 | Description       |
| ----------- | ------ | ------------------ |
|`id`         | string | UUID to uniquely identify the event.
|`success`    | boolean | Indication of whether the event was successful or not.
|`start_time` | time | Time when the event started.
|`end_time`   | time | Time when the event ended.
|`task_name`  | string | Name that task is configured with in CTS.
|`error`         | object | Information when the event fails. Null when successful.
|`error.message` | string | Error message that is returned on failure.
|`config`           | object | **Deprecated in CTS 0.5.0 and will be removed in v0.8.0.** Configuration values for the task when it was run.
|`config.services`  | list[string] | **Deprecated in CTS 0.5.0 and will be removed in v0.8.0.** List of the services configured for the task.
|`config.source`    | string | **Deprecated in CTS 0.5.0 and will be removed in v0.8.0.** Module configured for the task.
|`config.providers` | list[string] | **Deprecated in CTS 0.5.0 and will be removed in v0.8.0.** List of the providers configured for the task.

### Examples 

The following examples call `status` endpoints to retrieve information about tasks. 

#### All task statuses

Request:
```shell-session
$ curl localhost:8558/v1/status/tasks
```

Response:
```json
{
  "task_a": {
    "task_name": "task_a",
    "status": "successful",
    "enabled": true,
    "providers": [
      "local"
    ],
    "services": [
      "api"
    ],
    "events_url": "/v1/status/tasks/task_a?include=events"
  },
  "task_b": {
    "task_name": "task_b",
    "status": "errored",
    "enabled": false,
    "providers": [
      "null"
    ],
    "services": [
      "web"
    ],
    "events_url": "/v1/status/tasks/task_b?include=events"
  }
}
```

#### Individual task status with events

Request:
```shell-session
$ curl localhost:8558/v1/status/tasks/task_b?include=events
```

Response:
```json
{
  "task_b": {
    "task_name": "task_b",
    "status": "errored",
    "enabled": false,
    "providers": [
      "null"
    ],
    "services": [
      "web",
    ],
    "events_url": "/v1/status/tasks/task_b?include=events",
    "events": [
      {
        "id": "44137ba2-8fc9-6cbe-0e0e-e9305ee4f7f9",
        "success": false,
        "start_time": "2020-11-24T12:06:51.858292-05:00",
        "end_time": "2020-11-24T12:06:52.770165-05:00",
        "task_name": "task_b",
        "error": {
          "message": "example error: terraform-apply error"
        },
        "config": {
          "providers": [
            "null"
          ],
          "services": [
            "web"
          ],
          "module": "../modules/test_task"
        }
      },
      {
        "id": "ef202675-502f-431f-b133-ed64d15b0e0e",
        "success": true,
        "start_time": "2020-11-24T12:04:18.651231-05:00",
        "end_time": "2020-11-24T12:04:20.900115-05:00",
        "task_name": "task_b",
        "error": null,
        "config": {
          "providers": [
            "null"
          ],
          "services": [
            "web",
          ],
          "module": "../modules/test_task"
        }
      }
    ]
  }
}
```

## Cluster status

The `/v1/status/cluster` API endpoint returns information about the cluster and member instances, such as health status and leadership. This endpoint is only supported when using CTS in [high availability mode](/docs/usage/run-ha). If you call the endpoint without configuring CTS for high availability, then CTS prints an error to the console. Refer to [Error Messages](/docs/nia/usage/errors-ref) for information about CTS error messages. 

| Method | Path              | Response format    |
| ------ | ----------------- | ------------------ |
| `GET`  | `/status/cluster` | `application/json` |

### Request parameters

Currently no request parameters are offered for the overall status API.

### Request statuses

- `200`: Successfully retrieved the cluster status

### Response fields

| Field | Type | Description |
| --- | ---- | --- |
| `cluster_name` | string | Identifies the name of the cluster. |
| `members` | list | Contains the CTS instance objects. |
| `members.address` | string | Indicates the location of the instance. The address is only included in the response if the `high_availability.instance.address` option is configured. Refer to the [high availability instance configuration](/docs/nia/configuration#high-availability-instance) reference for additional information. |
| `members.healthy` | Boolean | Indicates the health of the instance. |
| `members.id` | string | Indicates the instance ID. |
| `members.leader` | Boolean | Identifies the cluster leader. |
| `members.service_name` | string | Identifies the name of the service that the instance represents. The value should always be `consul-terraform-sync`. |
| `request_id` | string | Unique identifier for the request. |

### Example

The following command calls the `/status/cluster` endpoint:

```shell-session
$ curl –request GET http://localhost:8553/v1/status/cluster
```

The following example response shows that there are three CTS instances. The cluster is located at `cts-02.example.com`. The leader instance, `cts-02`, is the only healthy instance: 

```json
{
  "cluster_name": "cluster-a",
  "members": [
    {
      "address": "cts-02.example.com",
      "healthy": true,
      "id": "cts-02",
      "leader": true,
      "service_name": "consul-terraform-sync"
    },
    {
      "healthy": false,
      "id": "cts-03",
      "leader": false,
      "service_name": "consul-terraform-sync"
    },
    {
      "healthy": false,
      "id": "cts-01",
      "leader": false,
      "service_name": "consul-terraform-sync"
    }
  ],
  "request_id": "e1bc2236-3d0e-5f5e-dc51-164a1cf6da88"
}