Operations

## Overview This document outlines the rules for managing and monitoring long-running operations in Neon, including branch creation and compute management. ## Operations An operation is an action performed by the Neon Control Plane (e.g., `create_branch`, `start_compute`). When using the API programmatically, it is crucial to monitor the status of long-running operations to ensure one has completed before starting another that depends on it. Operations older than 6 months may be deleted from Neon's systems. ### List operations 1. Action: Retrieves a list of operations for the specified Neon project. The number of operations can be large, so pagination is recommended. 2. Endpoint: `GET /projects/{project_id}/operations` 3. Path Parameters: - `project_id` (string, required): The unique identifier of the project whose operations you want to list. 4. Query Parameters: - `limit` (integer, optional): The number of operations to return in the response. Must be between 1 and 1000. - `cursor` (string, optional): The cursor value from a previous response to fetch the next page of operations. 5. Procedure: - Make an initial request with a `limit` to get the first page of results. - The response will contain a `pagination.cursor` value. - To get the next page, make a subsequent request including both the `limit` and the `cursor` from the previous response. Example request ```bash curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/operations' -H 'Accept: application/json' -H "Authorization: Bearer $NEON_API_KEY" ``` Example response ```json { "operations": [ { "id": "639f7f73-0b76-4749-a767-2d3c627ca5a6", "project_id": "hidden-river-50598307", "branch_id": "br-long-feather-adpbgzlx", "endpoint_id": "ep-round-morning-adtpn2oc", "action": "apply_config", "status": "finished", "failures_count": 0, "created_at": "2025-09-10T12:15:23Z", "updated_at": "2025-09-10T12:15:23Z", "total_duration_ms": 87 }, { "id": "b5a7882b-a5b3-4292-ad27-bffe733feae4", "project_id": "hidden-river-50598307", "branch_id": "br-super-wildflower-adniii9u", "endpoint_id": "ep-ancient-brook-ad5ea04d", "action": "apply_config", "status": "finished", "failures_count": 0, "created_at": "2025-09-10T12:15:23Z", "updated_at": "2025-09-10T12:15:23Z", "total_duration_ms": 49 }, { "id": "36a1cba0-97f1-476d-af53-d9e0d3a3606d", "project_id": "hidden-river-50598307", "branch_id": "br-super-wildflower-adniii9u", "endpoint_id": "ep-ancient-brook-ad5ea04d", "action": "start_compute", "status": "finished", "failures_count": 0, "created_at": "2025-09-10T12:15:04Z", "updated_at": "2025-09-10T12:15:05Z", "total_duration_ms": 913 }, { "id": "409c35ef-cbc3-4f1b-a4ca-f2de319f5360", "project_id": "hidden-river-50598307", "branch_id": "br-super-wildflower-adniii9u", "action": "create_branch", "status": "finished", "failures_count": 0, "created_at": "2025-09-10T12:15:04Z", "updated_at": "2025-09-10T12:15:04Z", "total_duration_ms": 136 }, { "id": "274e240f-e2fb-4719-b796-c1ab7c4ae91c", "project_id": "hidden-river-50598307", "branch_id": "br-long-feather-adpbgzlx", "endpoint_id": "ep-round-morning-adtpn2oc", "action": "start_compute", "status": "finished", "failures_count": 0, "created_at": "2025-09-10T12:14:58Z", "updated_at": "2025-09-10T12:15:03Z", "total_duration_ms": 4843 }, { "id": "22ef6fbd-21c5-4cdb-9825-b0f9afddbb0d", "project_id": "hidden-river-50598307", "branch_id": "br-long-feather-adpbgzlx", "action": "create_timeline", "status": "finished", "failures_count": 0, "created_at": "2025-09-10T12:14:58Z", "updated_at": "2025-09-10T12:15:01Z", "total_duration_ms": 3096 } ], "pagination": { "cursor": "2025-09-10T12:14:58.848485Z" } } ``` ### Retrieve operation details 1. Action: Retrieves the details and status of a single, specified operation. The `operation_id` is found in the response body of the initial API call that initiated it, or by listing operations. 2. Endpoint: `GET /projects/{project_id}/operations/{operation_id}` 3. Path Parameters: - `project_id` (string, required): The unique identifier of the project where the operation occurred. - `operation_id` (UUID, required): The unique identifier of the operation. This ID is returned in the response body of the API call that initiated the operation. Example request: ```bash curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/operations/274e240f-e2fb-4719-b796-c1ab7c4ae91c' -H 'Accept: application/json' -H "Authorization: Bearer $NEON_API_KEY" ``` Example response: ```json { "operation": { "id": "274e240f-e2fb-4719-b796-c1ab7c4ae91c", "project_id": "hidden-river-50598307", "branch_id": "br-long-feather-adpbgzlx", "endpoint_id": "ep-round-morning-adtpn2oc", "action": "start_compute", "status": "finished", "failures_count": 0, "created_at": "2025-09-10T12:14:58Z", "updated_at": "2025-09-10T12:15:03Z", "total_duration_ms": 4843 } } ```