Neon integration on Vercel: Create a branch for every Preview DeploymentLearn More
Manage

Operations

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

OperationDescription
apply_configApplies a new configuration to a Neon object or resource. For example, creating, deleting, or updating PostgreSQL users and databases initiates this operation.
check_availabilityChecks the availability of data in a branch and that a compute endpoint can start on a branch. Branches without a compute endpoint are not checked. This operation, performed by the availability checker, is a periodic load generated by the Control Plane.
create_branchCreates a branch in a Neon project. For related information, see Manage branches.
create_timelineCreates a project with its primary branch.
delete_tenantDeletes stored data when a Neon project is deleted.
start_computeStarts a compute endpoint when there is an event or action that requires compute resources. For example, connecting to a suspended compute endpoint initiates this operation.
suspend_computeSuspends a compute endpoint after a period of inactivity. For information about how Neon manages compute resources, see Compute lifecycle.

View operations

You can view operations in the Operations widget on the Neon Dashboard or on the Operations page.

Operations

Operation details include:

  • Action: The action performed by the operation.
  • Branch: The branch on which the operation was performed.
  • Status: The status of the operation.
  • Duration: The duration of the operation.
  • Date: The date and time the operation occurred.

View operations with the Neon API

The following topics are covered in this section:

  • List operations: Describes how to list all operations for a Neon project.
  • List operations with pagination: Describes how to list all operations for a Neon project and paginate the response.
  • Get operation: Describes how to retrieve the details for a specific operation by the operation ID.
  • 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.

List operations

Lists operations for the specified project. This method supports response pagination. For more information, see List operations with pagination.

/projects/{project_id}/operations

cURL command:

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

Response:

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

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

Response:

{
  "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 initial or previous request and a limit value for the next page.

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'

Response:

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

/projects/{project_id}/operations/{operation_id}

cURL command:

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'

Response:

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

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

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'

Response:

{
  "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 running, finished, failed, scheduling. Initially, the status of an operation might be scheduling. Before issuing the next API request, you would poll the operation until the status changes to finished. You could also add logic to handle a failed status.

Need help?

Send a request to support@neon.tech, or join the Neon community forum.

PreviousIntegrations
NextAWS Lambda
Edit this page
Was this page helpful?