consul/website/content/docs/nia/api/status.mdx

---
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](/consul/docs/nia/tasks#status-information).

If CTS is configured [for high availability](/consul/docs/nia/usage/run-ha), you can send requests to the [`/status/cluster` endpoint path](#cluster-status) on any CTS cluster member instance to receive information about the entire cluster. Calling the `status` endpoint path (without `/cluster`), however, returns a 400 error if the request is sent to a follower instance. The error message depends on what information the follower instance is able to obtain about the leader. Refer to [Error Messages](/consul/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

No request parameters are available for this endpoint.

### Response statuses

- `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](/consul/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

- `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](/consul/docs/nia/api/status#event)] | List of stored events that inform the task's status. See [section below](/consul/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](/consul/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 high-availability clusters and its members, such as health status and leadership. This endpoint is only supported when using CTS in [high availability mode](/consul/docs/nia/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](/consul/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 cluster status API.

### Request statuses

- `200`: Successfully retrieved the cluster status

### Response fields

The following table describes the responses that the `status/cluster` endpoint can send. 

| Field | Type | Description |
| --- | ---- | --- |
| `cluster_name` | string | Identifies the name of the cluster. |
| `members` | list[[member](#member-objects)] | Contains a list of [member objects](#member-objects). Each object in the `members` list represents a CTS instance. |

#### Member objects

The following table describes the fields available for objects in the `members` array.  

| Field | Type | Description |
| --- | ---- | --- |
| `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 on the leader instance. Refer to the [high availability instance configuration](/consul/docs/nia/configuration#high-availability-instance) reference for additional information. |
| `healthy` | boolean | Indicates the health of the service instance health. Refer to [Service Registration](/consul/docs/nia/configuration#service-registration) for additional information. |
| `id` | string | Indicates the service registration ID. Refer to [Service Registration](/consul/docs/nia/configuration#service-registration) for additional information. |
| `leader` | boolean | Identifies the cluster leader. |
| `service_name` | string | Identifies the name of the service that the instance represents. The value is set by the `service_name` field in the [Service Registration](/consul/docs/nia/configuration#service-registration) configuration.  |

### 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 three CTS instances. The cluster leader is `cts-02` and is advertising that its address is `cts-02.example.com`: 

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