claude-skills/neon-postgres/references/neon-rest-api/operations.md

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

curl 'https://console.neon.tech/api/v2/projects/hidden-river-50598307/operations' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"

Example response

{
  "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:

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:

{
  "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
  }
}