# Source: https://neon.com/llms/manage-operations.txt

# System operations

> The "System operations" document outlines procedures for managing and maintaining Neon database systems, detailing tasks such as monitoring, scaling, and troubleshooting to ensure optimal performance and reliability.

## Source

- [System operations HTML](https://neon.com/docs/manage/operations): The original HTML version of this documentation

An operation is an action performed by the Neon Control Plane on a Neon object or resource. Operations are typically initiated by user actions, such as creating a branch or deleting a database. Other operations may be initiated by the Neon Control Plane, such as suspending a [compute](https://neon.com/docs/reference/glossary#compute) after a period of inactivity or checking its availability. You can monitor operations to keep an eye on the overall health of your Neon project or to check the status of specific operations. When working with the Neon API, you can poll the status of operations to ensure that an API request is completed before issuing the next API request. For more information, see [Poll operation status](https://neon.com/docs/manage/operations#poll-operation-status).

| Operation              | Description                                                                                                                                                                                                                                                                                                                      |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Apply config`         | Applies a new configuration to a Neon object or resource. For example, changing compute settings or creating, deleting, or updating Postgres users and databases initiates this operation.                                                                                                                                       |
| `Apply storage config` | Applies a new configuration to a Neon storage object or resource. For example, updating the restore window for a project initiates this operation.                                                                                                                                                                               |
| `Check availability`   | Checks the availability of data in a branch and that a [compute](https://neon.com/docs/reference/glossary#compute) can start on a branch. Branches without a compute are not checked. This operation, performed by the [availability checker](https://neon.com/docs/reference/glossary#availability-checker), is a periodic load generated by the Control Plane. |
| `Create branch`        | Creates a [branch](https://neon.com/docs/reference/glossary#branch) in a Neon project. For related information, see [Manage branches](https://neon.com/docs/manage/branches).                                                                                                                                                                                    |
| `Create timelime`      | Sets up storage and creates the default branch when a Neon [project](https://neon.com/docs/reference/glossary#project) is created.                                                                                                                                                                                                               |
| `Delete tenant`        | Deletes stored data when a Neon project is deleted.                                                                                                                                                                                                                                                                              |
| `Start compute`        | Starts a compute when there is an event or action that requires compute resources. For example, connecting to a suspended compute initiates this operation.                                                                                                                                                                      |
| `Suspend compute`      | Suspends a compute after a period of inactivity. For information about how Neon manages compute resources, see [Compute lifecycle](https://neon.com/docs/introduction/compute-lifecycle/).                                                                                                                                                       |
| `Tenant attach`        | Attaches a Neon project to storage.                                                                                                                                                                                                                                                                                              |
| `Tenant detach`        | Detaches a Neon project from storage after the project as been idle for an extended period.                                                                                                                                                                                                                                      |
| `Tenant reattach`      | Reattaches a detached Neon project to storage when a detached project receives a request.                                                                                                                                                                                                                                        |
| `Timeline archive`     | The time when a branch archive operation was initiated.                                                                                                                                                                                                                                                                          |
| `Timeline unarchive`   | The time when the branch unarchive operation was initiated.                                                                                                                                                                                                                                                                      |

## View operations

You can view system operations via the Neon Console, [Neon CLI](https://neon.com/docs/reference/neon-cli), or [Neon API](https://api-docs.neon.tech/reference/getting-started-with-neon-api).

Tab: Neon Console

You can view system operations via the **Monitoring** page in the Neon Console.



Operation details include:

- **Operation**: The action performed by the operation.
- **Branch**: The branch on which the operation was performed.
- **Compute**: The compute on which the operation occurred.
- **Operation status**: The status of the operation.
- **Duration**: The duration of the operation.
- **Date**: The date and time the operation occurred.

Possible **Status** values are `OK`, `Scheduling`, `In progress`, and `Error`.

Tab: CLI

To view operation using the Neon CLI:

```bash
neon operations list --project-id <project_id>
```

See [Neon CLI commands — operations](https://neon.com/docs/reference/cli-operations).

Tab: API

To list operations with the Neon API:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

See [Get a list of operations](https://api-docs.neon.tech/reference/listprojectoperations).

## Operations and the Neon API

This section describes how to work with operations using the [Neon API](https://api-docs.neon.tech/reference/getting-started-with-neon-api). The following topics are covered:

- [List operations](https://neon.com/docs/manage/operations#list-operations): Describes how to list all operations for a Neon project.
- [List operations with pagination](https://neon.com/docs/manage/operations#list-operations-with-pagination): Describes how to list all operations for a Neon project and paginate the response.
- [Get operation](https://neon.com/docs/manage/operations#get-operation): Describes how to retrieve the details for a specific operation by the operation ID.
- [Poll operation status](https://neon.com/docs/manage/operations#poll-operation-status): Describes how to poll an operation for its status, which may be necessary to avoid failed requests due to in-progress operations when using the Neon API programmatically.

   **Note**: Operation names have underscores when view using the API; for example:

### List operations

Lists operations for the specified project. This method supports response pagination. For more information, see [List operations with pagination](https://neon.com/docs/manage/operations#list-operations-with-pagination).

```text
/projects/{project_id}/operations
```

cURL command:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Details: Response body
For attribute definitions, find the [List operations](https://api-docs.neon.tech/reference/listprojectoperations) endpoint in the [Neon API Reference](https://api-docs.neon.tech/reference/getting-started-with-neon-api). Definitions are provided in the **Responses** section.

```json
{
  "operations": [
    {
      "id": "97c7a650-e4ff-43d7-8c58-4c67f5050167",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T08:47:52Z",
      "updated_at": "2022-12-09T08:47:56Z"
    },
    {
      "id": "0f3daf10-2544-425c-86d3-9a9932ab25b9",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T04:47:39Z",
      "updated_at": "2022-12-09T04:47:44Z"
    },
    {
      "id": "fb8484df-51b4-4a40-b0fc-97b73998892b",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T02:47:05Z",
      "updated_at": "2022-12-09T02:47:09Z"
    }
  ],
  "pagination": {
    "cursor": "2022-12-07T00:45:05.262011Z"
  }
}
```

### List operations with pagination

Pagination allows you to limit the number of operations displayed, as the number of operations for a project can be large. To paginate responses, issue an initial request with a `limit` value. For brevity, the limit is set to 1 in the following example.

cURL command:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations?limit=1' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Details: Response body
For attribute definitions, find the [List operations](https://api-docs.neon.tech/reference/listprojectoperations) endpoint in the [Neon API Reference](https://api-docs.neon.tech/reference/getting-started-with-neon-api). Definitions are provided in the **Responses** section.

```json
{
  "operations": [
    {
      "id": "97c7a650-e4ff-43d7-8c58-4c67f5050167",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T08:47:52Z",
      "updated_at": "2022-12-09T08:47:56Z"
    }
  ],
  "pagination": {
    "cursor": "2022-12-09T08:47:52.20417Z"
  }
}
```

To list the next page of operations, add the `cursor` value returned in the response body of the previous request and a `limit` value for the next page.

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations?cursor=2022-12-09T08%3A47%3A52.20417Z&limit=1' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Details: Response body
For attribute definitions, find the [List operations](https://api-docs.neon.tech/reference/listprojectoperations) endpoint in the [Neon API Reference](https://api-docs.neon.tech/reference/getting-started-with-neon-api). Definitions are provided in the **Responses** section.

```json
{
  "operations": [
    {
      "id": "0f3daf10-2544-425c-86d3-9a9932ab25b9",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T04:47:39Z",
      "updated_at": "2022-12-09T04:47:44Z"
    }
  ],
  "pagination": {
    "cursor": "2022-12-09T04:47:39.797163Z"
  }
}
```

### Get operation

This method shows only the details for the specified operation ID.

```text
/projects/{project_id}/operations/{operation_id}
```

cURL command:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations/97c7a650-e4ff-43d7-8c58-4c67f5050167' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Details: Response body
For attribute definitions, find the [Retrieve operation details](https://api-docs.neon.tech/reference/getprojectoperation) endpoint in the [Neon API Reference](https://api-docs.neon.tech/reference/getting-started-with-neon-api). Definitions are provided in the **Responses** section.

```json
{
  "operation": {
    "id": "97c7a650-e4ff-43d7-8c58-4c67f5050167",
    "project_id": "autumn-disk-484331",
    "branch_id": "br-wispy-dew-591433",
    "endpoint_id": "ep-orange-art-714542",
    "action": "check_availability",
    "status": "finished",
    "failures_count": 0,
    "created_at": "2022-12-09T08:47:52Z",
    "updated_at": "2022-12-09T08:47:56Z"
  }
}
```

## Poll operation status

Some Neon API requests may take a few moments to complete. When using the Neon API programmatically, you can check the `status` of an operation before proceeding with the next API request. For example, you may want to check the operation status of a create branch request before issuing a create database request for that branch.

The response to a Neon API request includes information about the operations that were initiated. For example, a create branch request initiates `create_branch` and `start_compute` operations.

```json
"operations": [
    {
      "id": "22acbb37-209b-4b90-a39c-8460090e1329",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "action": "create_branch",
      "status": "running",
      "failures_count": 0,
      "created_at": "2022-12-08T19:55:43Z",
      "updated_at": "2022-12-08T19:55:43Z"
    },
    {
      "id": "055b17e6-ffe3-47ab-b545-cfd7db6fd8b8",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "endpoint_id": "ep-small-bush-675287",
      "action": "start_compute",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2022-12-08T19:55:43Z",
      "updated_at": "2022-12-08T19:55:43Z"
    }
  ]
```

You can use the [Get operation details](https://api-docs.neon.tech/reference/getprojectoperation) method to poll the status of an operation by the operation ID. You might do this at intervals of 5 seconds until the `status` of the operation changes to `finished` before issuing the next request. For example, this request polls the `start_compute` operation shown above:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations/055b17e6-ffe3-47ab-b545-cfd7db6fd8b8' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Details: Response body
For attribute definitions, find the [Get operation details](https://api-docs.neon.tech/reference/getprojectoperation) endpoint in the [Neon API Reference](https://api-docs.neon.tech/reference/getting-started-with-neon-api). Definitions are provided in the **Responses** section.

```json
{
  "operation": {
    "id": "055b17e6-ffe3-47ab-b545-cfd7db6fd8b8",
    "project_id": "autumn-disk-484331",
    "branch_id": "br-dawn-scene-747675",
    "endpoint_id": "ep-small-bush-675287",
    "action": "start_compute",
    "status": "finished",
    "failures_count": 0,
    "created_at": "2022-12-08T19:55:43Z",
    "updated_at": "2022-12-08T19:55:43Z"
  }
}
```

Possible operation `status` values include: `scheduling`, `running`, `finished`, `failed`, `cancelling`, `cancelled`, and `skipped`. Only `finished`, `skipped`, and `cancelled` are **terminal statuses**, meaning the operation will not proceed further from these states. Note that `failed` is **not** terminal, as an operation in a `failed` state can still be retried.