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 share status-related information for tasks. This information is available for understanding the status of individual tasks and across tasks.

The health status value is determined by aggregating the success or failure of the event of a task detecting changes in Consul services and then updating network infrastructure. Currently, only the 5 most recent events are stored in Consul-Terraform-Sync. For more information on the hierarchy of status information and how it is collected, see [Status Information](/docs/nia/tasks#status-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 Fields

* `task_summary` - Summary of task information. See [Task Status API](/docs/nia/api#task-status) to learn more about how health status is determined.
  * `status` - Summary count of how many tasks have each health status value
    * `successful` - (int) The number of tasks that have a 'successful' health status
    * `errored` - (int) The number of tasks that have a 'errored' health status
    * `critical` - (int) The number of tasks that have a 'critical' health status
    * `unknown` - (int) The number of tasks that have an 'unknown' health status
  * `enabled` - Summary count of how many tasks are enabled or disabled
    * `true` - (int) The number of tasks that are enabled
    * `false` - (int) 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` | `application/json` |

#### Request Parameters

* `task` - (string) Option to specify the name of the task to return in the response. If not specified, all tasks are returned in the response.
* `include` - (string) Only accepts the value "events". Use to include stored event information in response.
* `status` - (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.

#### Response Fields

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

* `task_name` - (string) Name that task is configured with in Consul-Terraform-Sync.
* `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` - (bool) Whether the task is enabled or not.
* `services` - (list[string]) List of the services configured for the task.
* `providers` - (list[string]) 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#event) - List of stored events that inform the task's status. See section below 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).

* `id` - (string) UUID to uniquely identify the event.
* `success` - (bool) 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 Consul-Terraform-Sync.
* `error` Information when the event fails. Null when successful.
  * `message` - (string) Error message that is returned on failure.
* `config`
  * `services` - (list[string]) List of the services configured for the task.
  * `source` - (string) Source configured for the task.
  * `providers` - (list[string]) 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",
          ],
          "source": "../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",
          ],
          "source": "../modules/test_task"
        }
      }
    ]
  }
}
```