> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check the operational status of a Virtual Machine

export const MethodSection = ({children}) => children ?? null;

export const MethodSwitch = ({children}) => {
  const tabs = React.Children.toArray(children).map(c => {
    if (!c || !c.props) return null;
    if (c.props.id) return c;
    const inner = c.props.children;
    if (inner && inner.props && inner.props.id) return inner;
    return null;
  }).filter(Boolean);
  const firstId = tabs.length > 0 ? tabs[0].props.id : "";
  const [active, setActive] = React.useState(firstId);
  React.useEffect(() => {
    try {
      const saved = localStorage.getItem("gcore_docs_method");
      if (saved && tabs.find(t => t.props.id === saved)) {
        setActive(saved);
      }
    } catch (_) {}
  }, []);
  React.useEffect(() => {
    try {
      document.querySelectorAll("h2[id], h3[id]").forEach(heading => {
        const visible = heading.offsetParent !== null;
        document.querySelectorAll(`a[href="#${heading.id}"]`).forEach(link => {
          if (link.closest("h1,h2,h3,h4,h5,h6")) return;
          const li = link.closest("li");
          if (li) li.style.display = visible ? "" : "none";
        });
      });
    } catch (_) {}
    window.dispatchEvent(new Event("scroll"));
  }, [active]);
  const handleClick = id => {
    setActive(id);
    try {
      localStorage.setItem("gcore_docs_method", id);
    } catch (_) {}
  };
  return <div>
      <div className="not-prose flex gap-0 border-b border-zinc-200 dark:border-zinc-800 mb-8 mt-2" role="tablist">
        {tabs.map(tab => {
    const isActive = active === tab.props.id;
    return <button key={tab.props.id} role="tab" aria-selected={isActive} onClick={() => handleClick(tab.props.id)} className={["px-4 py-2 text-sm font-medium border-b-2 -mb-px transition-colors cursor-pointer", isActive ? "border-primary text-primary" : "border-transparent text-zinc-500 hover:text-zinc-800 dark:hover:text-zinc-200"].join(" ")}>
              {tab.props.label}
            </button>;
  })}
      </div>

      {tabs.map(tab => <div key={tab.props.id} style={{
    display: active === tab.props.id ? "" : "none"
  }}>
          {tab.props.children}
        </div>)}
    </div>;
};

<MethodSwitch>
  <MethodSection id="portal" label="Customer Portal">
    <p>Virtual Machine statuses are visible on the **Virtual Instances** page inside a project. Check the **Status** column:</p>

    <Frame>
      <img src="https://mintcdn.com/gcore/yrEa6OGy4Q_zWlXb/images/docs/cloud/virtual-instances/check-the-operational-status-of-your-instance/vm-list-status-column.png?fit=max&auto=format&n=yrEa6OGy4Q_zWlXb&q=85&s=20a71aad43cd5b805cdc0a6814998d55" alt="Virtual Instances list showing the Status column with a Power on badge" width="1400" height="367" data-path="images/docs/cloud/virtual-instances/check-the-operational-status-of-your-instance/vm-list-status-column.png" />
    </Frame>

    <Tip>
      If a Virtual Machine enters the `Error` state, contact [Gcore support](mailto:support@gcore.com) for assistance.
    </Tip>
  </MethodSection>

  <MethodSection id="api" label="REST API">
    <p>Two endpoints expose instance status. The list endpoint returns the `status` field for every VM in a project; the detail endpoint adds `vm_state` and `task_state` for a single VM. Read `task_state` to detect background operations that have not yet changed `status`.</p>

    <Info>An [API token](/account-settings/api-tokens) is required, along with a [project ID](/api-reference/cloud/projects/list-projects) and [region ID](/api-reference/cloud/regions/list-regions).</Info>

    <p>Set these variables before running the examples:</p>

    ```bash theme={null}
    export GCORE_API_KEY="{YOUR_API_KEY}"
    export GCORE_CLOUD_PROJECT_ID="{YOUR_PROJECT_ID}"
    export GCORE_CLOUD_REGION_ID="{YOUR_REGION_ID}"
    export INSTANCE_ID="{YOUR_INSTANCE_ID}"
    ```

    <Info>
      `INSTANCE_ID` is the UUID of the Virtual Machine — retrieve it from the `id` field in the list endpoint response below.
    </Info>

    ## List instances

    <p>Returns all Virtual Machines in the project and region with their current `status`.</p>

    <Tabs>
      <Tab title="Python SDK">
        ```python theme={null}
        import os
        from gcore import Gcore

        client = Gcore()

        for instance in client.cloud.instances.list():
            print(f"{instance.name}: {instance.status}")
        ```
      </Tab>

      <Tab title="Go SDK">
        ```go theme={null}
        import (
            "context"
            "fmt"
            "log"

            gcore "github.com/G-Core/gcore-go"
            "github.com/G-Core/gcore-go/cloud"
        )

        client := gcore.NewClient()
        ctx := context.Background()

        page, err := client.Cloud.Instances.List(ctx, cloud.InstanceListParams{})
        if err != nil {
            log.Fatalf("list instances: %v", err)
        }
        for _, inst := range page.Results {
            fmt.Printf("%s: %s\n", inst.Name, inst.Status)
        }
        ```
      </Tab>

      <Tab title="curl">
        ```bash theme={null}
        curl -X GET "https://api.gcore.com/cloud/v1/instances/${GCORE_CLOUD_PROJECT_ID}/${GCORE_CLOUD_REGION_ID}" \
          -H "Authorization: APIKey ${GCORE_API_KEY}"
        ```

        Response:

        ```json theme={null}
        {
          "count": 1,
          "results": [
            {
              "id": "4f89fc5a-3f68-4ae5-8b32-6e5304987872",
              "name": "my-instance",
              "status": "ACTIVE"
            }
          ]
        }
        ```
      </Tab>
    </Tabs>

    ## Get instance details

    <p>Returns full details for a single VM including `status`, `vm_state`, and `task_state`. When `task_state` is non-null, the VM is mid-operation — a reboot or resize may still show `status: ACTIVE` while `task_state: "rebooting"` indicates the operation is in progress.</p>

    <Tabs>
      <Tab title="Python SDK">
        ```python theme={null}
        instance = client.cloud.instances.get(instance_id=os.environ["INSTANCE_ID"])
        print(f"status={instance.status}  task_state={instance.task_state}")
        ```
      </Tab>

      <Tab title="Go SDK">
        ```go theme={null}
        instance, err := client.Cloud.Instances.Get(ctx, os.Getenv("INSTANCE_ID"), cloud.InstanceGetParams{})
        if err != nil {
            log.Fatalf("get instance: %v", err)
        }
        fmt.Printf("status=%s  task_state=%v\n", instance.Status, instance.TaskState)
        ```
      </Tab>

      <Tab title="curl">
        ```bash theme={null}
        curl -X GET "https://api.gcore.com/cloud/v1/instances/${GCORE_CLOUD_PROJECT_ID}/${GCORE_CLOUD_REGION_ID}/${INSTANCE_ID}" \
          -H "Authorization: APIKey ${GCORE_API_KEY}"
        ```

        Response:

        ```json theme={null}
        {
          "id": "4f89fc5a-3f68-4ae5-8b32-6e5304987872",
          "name": "my-instance",
          "status": "ACTIVE",
          "vm_state": "active",
          "task_state": null
        }
        ```
      </Tab>
    </Tabs>
  </MethodSection>

  <MethodSection id="terraform" label="Terraform">
    <p>Read a Virtual Machine's current `status` and `vm_state` without managing it. The [`gcore_cloud_instance`](https://registry.terraform.io/providers/G-Core/gcore/latest/docs/data-sources/cloud_instance) data source fetches live state from the API and exposes it as Terraform outputs.</p>

    ## Get instance status

    <p>Reads a single instance by ID and surfaces its `status`, `vm_state`, and `task_state`. Use when the live state of an existing VM must be known before provisioning dependent resources.</p>

    ```hcl theme={null}
    data "gcore_cloud_instance" "status" {
      project_id  = var.project_id
      region_id   = var.region_id
      instance_id = "{INSTANCE_ID}"
    }

    output "instance_status" {
      value = data.gcore_cloud_instance.status.status
    }

    output "instance_task_state" {
      value = data.gcore_cloud_instance.status.task_state
    }
    ```

    <p>Run `terraform apply` — Terraform queries the API and prints:</p>

    ```bash theme={null}
    instance_status     = "ACTIVE"
    instance_task_state = tostring(null)
    ```

    <p>The `status` and `vm_state` constants are listed in [Status values](#status-values) below.</p>

    ## Check state of a managed instance

    <p>For instances declared as `gcore_cloud_instance` resources, `terraform show` reads from the state file — it reflects the state at the last `apply` or `refresh`, not the current API value:</p>

    ```bash theme={null}
    terraform show
    ```

    <p>To query the live API and update the state file:</p>

    ```bash theme={null}
    terraform apply -refresh-only
    ```
  </MethodSection>
</MethodSwitch>

## Status values

The `status` field uses uppercase string constants. The `vm_state` field provides stable state context and is returned by the single-instance detail endpoint and the `data "gcore_cloud_instance"` Terraform data source.

`task_state` is non-null only during a background operation. A VM can show `status: ACTIVE` while `task_state: "rebooting"` — check both fields to determine whether the VM has fully settled.

| `status`       | `vm_state`     | Portal label | Meaning                                                           |
| -------------- | -------------- | ------------ | ----------------------------------------------------------------- |
| `ACTIVE`       | `active`       | Power on     | The VM is running.                                                |
| `SHUTOFF`      | `stopped`      | Power off    | The VM is powered off.                                            |
| `BUILD`        | `building`     | Building     | The VM is being allocated.                                        |
| `ERROR`        | `error`        | Error        | Resource allocation failed.                                       |
| `DELETED`      | `deleted`      | Deleted      | The VM was deleted.                                               |
| `PAUSED`       | `paused`       | —            | The VM is paused in memory.                                       |
| `REBOOT`       | `active`       | —            | Soft reboot in progress; `task_state` carries the operation name. |
| `HARD_REBOOT`  | `active`       | —            | Hard reboot in progress; `task_state` carries the operation name. |
| `REBUILD`      | `active`       | —            | VM is being rebuilt from an image.                                |
| `RESIZE`       | `resized`      | —            | VM flavor is being changed.                                       |
| `MIGRATING`    | `active`       | —            | VM is being migrated to another host.                             |
| `SUSPENDED`    | `suspended`    | —            | VM is suspended.                                                  |
| `SOFT_DELETED` | `soft-deleted` | —            | VM is pending permanent deletion.                                 |