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](/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.

## Overall Status

This endpoint currently 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.

### Example: 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"
  }
}
```

### Example: 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"
        }
      }
    ]
  }
}
```