godo.Droplets.ListByTag()

Generated on 5 Nov 2026 from godo version v1.236.0

Copy page as Markdown View page as Markdown

Usage 

client.Droplets.ListByTag(ctx context.Context, tag string, opt *godo.ListOptions) ([]godo.Droplet, *godo.Response, error)

Description

ListByTag lists all Droplets matched by a Tag.

This method sends a GET request to /v2/droplets.

Parameters

tag string required
opt *godo.ListOptions

Fields of godo.ListOptions

ListOptions specifies the optional parameters to various List methods that support pagination.

Page int

For paginated result sets, page of results to retrieve.

PerPage int

For paginated result sets, the number of results to include per page.

WithProjects bool

Whether App responses should include project_id fields. The field will be empty if false or if omitted. (ListApps)

Deployed bool

This parameter is used to only list agents that are deployed in the response.

PublicOnly bool

This parameter is used to include models that are publicly available.

Usecases []string

This parameter is used to include models according to the use cases.

Returns

[]godo.Droplet
*godo.Response

The HTTP response, with pagination Links, Meta, and Rate limit information.

error

Non-nil when the request fails. API errors are returned as *godo.ErrorResponse.

Fields of godo.Droplet

Droplet represents a DigitalOcean Droplet

ID int

Omitted from JSON when empty. JSON key: id

Name string

Omitted from JSON when empty. JSON key: name

Memory int

Omitted from JSON when empty. JSON key: memory

Vcpus int

Omitted from JSON when empty. JSON key: vcpus

Disk int

Omitted from JSON when empty. JSON key: disk

Region *godo.Region

Omitted from JSON when empty. JSON key: region

Image *godo.Image

Omitted from JSON when empty. JSON key: image

Size *godo.Size

Omitted from JSON when empty. JSON key: size

SizeSlug string

Omitted from JSON when empty. JSON key: size_slug

BackupIDs []int

Omitted from JSON when empty. JSON key: backup_ids

NextBackupWindow *godo.BackupWindow

Omitted from JSON when empty. JSON key: next_backup_window

SnapshotIDs []int

Omitted from JSON when empty. JSON key: snapshot_ids

Features []string

Omitted from JSON when empty. JSON key: features

Locked bool

Omitted from JSON when empty. JSON key: locked

Status string

Omitted from JSON when empty. JSON key: status

Networks *godo.Networks

Omitted from JSON when empty. JSON key: networks

Created string

Omitted from JSON when empty. JSON key: created_at

Kernel *godo.Kernel

Omitted from JSON when empty. JSON key: kernel

Tags []string

Omitted from JSON when empty. JSON key: tags

VolumeIDs []string

JSON key: volume_ids

VPCUUID string

Omitted from JSON when empty. JSON key: vpc_uuid

SubnetUUID string

Omitted from JSON when empty. JSON key: subnet_uuid

GPUPartitionMode string

GPUPartitionMode is echoed back on create when the Droplet was created
with a partitioned GPU. Note: read-back on droplet GET is not delivered in
v1, so this is only reliably populated on the create response.

Omitted from JSON when empty. JSON key: gpu_partition_mode

Request Sample

Show Request Sample
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/digitalocean/godo"
)

func main() {
	client := godo.NewFromToken(os.Getenv("DIGITALOCEAN_TOKEN"))
	ctx := context.TODO()

	result, _, err := client.Droplets.ListByTag(ctx, "<your-tag>", &godo.ListOptions{Page: 1, PerPage: 50})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", result)
}

Pagination

This method returns one page of results. Response.Links carries the pagination state; loop until IsLastPage reports true.

Show Pagination Sample
opt := &godo.ListOptions{Page: 1, PerPage: 50}
for {
	items, resp, err := client.Droplets.ListByTag(ctx, "<your-tag>", opt)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", items)

	if resp.Links == nil || resp.Links.IsLastPage() {
		break
	}
	page, err := resp.Links.CurrentPage()
	if err != nil {
		log.Fatal(err)
	}
	opt.Page = page + 1
}

Response Example

Show Response Example
{
  "droplets": [
    {
      "id": 3164444,
      "name": "example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "disk_info": [
        {
          "type": "local",
          "size": {
            "amount": 25,
            "unit": "gib"
          }
        }
      ],
      "locked": false,
      "status": "active",
      "kernel": null,
      "created_at": "2020-07-21T18:37:44Z",
      "features": [
        "backups",
        "private_networking",
        "ipv6"
      ],
      "backup_ids": [
        53893572
      ],
      "next_backup_window": {
        "start": "2020-07-30T00:00:00Z",
        "end": "2020-07-30T23:00:00Z"
      },
      "snapshot_ids": [
        67512819
      ],
      "image": {
        "id": 63663980,
        "name": "20.04 (LTS) x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-20-04-x64",
        "public": true,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "created_at": "2020-05-15T05:47:50Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.36,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      "volume_ids": [],
      "size": {
        "slug": "s-1vcpu-1gb",
        "memory": 1024,
        "vcpus": 1,
        "disk": 25,
        "transfer": 1,
        "price_monthly": 5,
        "price_hourly": 0.00743999984115362,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "available": true,
        "description": "Basic"
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
        "v4": [
          {
            "ip_address": "10.128.192.124",
            "netmask": "255.255.0.0",
            "gateway": "nil",
            "type": "private"
          },
          {
            "ip_address": "192.241.165.154",
            "netmask": "255.255.255.0",
            "gateway": "192.241.165.1",
            "type": "public"
          }
        ],
        "v6": [
          {
            "ip_address": "2604:a880:0:1010::18a:a001",
            "netmask": 64,
            "gateway": "2604:a880:0:1010::1",
            "type": "public"
          }
        ]
      },
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "available": true,
        "sizes": [
          "s-1vcpu-1gb",
          "s-1vcpu-2gb",
          "s-1vcpu-3gb",
          "s-2vcpu-2gb",
          "s-3vcpu-1gb",
          "s-2vcpu-4gb",
          "s-4vcpu-8gb",
          "s-6vcpu-16gb",
          "s-8vcpu-32gb",
          "s-12vcpu-48gb",
          "s-16vcpu-64gb",
          "s-20vcpu-96gb",
          "s-24vcpu-128gb",
          "s-32vcpu-192g"
        ]
      },
      "tags": [
        "web",
        "env:prod"
      ],
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
      "subnet_uuid": "9c7a0d63-3c4e-4d3d-9f56-3b0fb0e5e4a1"
    },
    {
      "id": 3164459,
      "name": "assets.example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "disk_info": [
        {
          "type": "local",
          "size": {
            "amount": 25,
            "unit": "gib"
          }
        }
      ],
      "locked": false,
      "status": "active",
      "kernel": null,
      "created_at": "2020-07-21T18:42:27Z",
      "features": [
        "private_networking"
      ],
      "backup_ids": [],
      "next_backup_window": {
        "start": "2020-07-30T00:00:00Z",
        "end": "2020-07-30T23:00:00Z"
      },
      "snapshot_ids": [],
      "image": {
        "id": 63663980,
        "name": "20.04 (LTS) x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-20-04-x64",
        "public": true,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "created_at": "2020-05-15T05:47:50Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.36,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      "volume_ids": [
        "506f78a4-e098-11e5-ad9f-000f53306ae1"
      ],
      "size": {
        "slug": "s-1vcpu-1gb",
        "memory": 1024,
        "vcpus": 1,
        "disk": 25,
        "transfer": 1,
        "price_monthly": 5,
        "price_hourly": 0.00743999984115362,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "available": true,
        "description": "Basic"
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
        "v4": [
          {
            "ip_address": "10.128.192.138",
            "netmask": "255.255.0.0",
            "gateway": "nil",
            "type": "private"
          },
          {
            "ip_address": "162.243.0.4",
            "netmask": "255.255.255.0",
            "gateway": "162.243.0.1",
            "type": "public"
          }
        ],
        "v6": []
      },
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "available": true,
        "sizes": [
          "s-1vcpu-1gb",
          "s-1vcpu-2gb",
          "s-1vcpu-3gb",
          "s-2vcpu-2gb",
          "s-3vcpu-1gb",
          "s-2vcpu-4gb",
          "s-4vcpu-8gb",
          "s-6vcpu-16gb",
          "s-8vcpu-32gb",
          "s-12vcpu-48gb",
          "s-16vcpu-64gb",
          "s-20vcpu-96gb",
          "s-24vcpu-128gb",
          "s-32vcpu-192g"
        ]
      },
      "tags": [
        "storage",
        "env:prod"
      ],
      "vpc_uuid": "760e09ef-dc84-11e8-981e-3cfdfeaae000",
      "subnet_uuid": "9c7a0d63-3c4e-4d3d-9f56-3b0fb0e5e4a1"
    },
    {
      "id": 3164412,
      "name": "stage.example.com",
      "memory": 1024,
      "vcpus": 1,
      "disk": 25,
      "disk_info": [
        {
          "type": "local",
          "size": {
            "amount": 25,
            "unit": "gib"
          }
        }
      ],
      "locked": false,
      "status": "active",
      "kernel": null,
      "created_at": "2020-07-21T18:32:55Z",
      "features": [
        "private_networking"
      ],
      "backup_ids": [],
      "next_backup_window": {
        "start": "2020-07-30T00:00:00Z",
        "end": "2020-07-30T23:00:00Z"
      },
      "snapshot_ids": [],
      "image": {
        "id": 63663980,
        "name": "20.04 (LTS) x64",
        "distribution": "Ubuntu",
        "slug": "ubuntu-20-04-x64",
        "public": true,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "created_at": "2020-05-15T05:47:50Z",
        "type": "snapshot",
        "min_disk_size": 20,
        "size_gigabytes": 2.36,
        "description": "",
        "tags": [],
        "status": "available",
        "error_message": ""
      },
      "volume_ids": [
        "7724db7c-e098-11e5-b522-000f53304e51"
      ],
      "size": {
        "slug": "s-1vcpu-1gb",
        "memory": 1024,
        "vcpus": 1,
        "disk": 25,
        "transfer": 1,
        "price_monthly": 5,
        "price_hourly": 0.00743999984115362,
        "regions": [
          "ams2",
          "ams3",
          "blr1",
          "fra1",
          "lon1",
          "nyc1",
          "nyc2",
          "nyc3",
          "sfo1",
          "sfo2",
          "sfo3",
          "sgp1",
          "tor1"
        ],
        "available": true,
        "description": "Basic"
      },
      "size_slug": "s-1vcpu-1gb",
      "networks": {
        "v4": [
          {
            "ip_address": "10.128.192.125",
            "netmask": "255.255.0.0",
            "gateway": "nil",
            "type": "private"
          },
          {
            "ip_address": "192.241.247.248",
            "netmask": "255.255.255.0",
            "gateway": "192.241.247.1",
            "type": "public"
          }
        ],
        "v6": []
      },
      "region": {
        "name": "New York 3",
        "slug": "nyc3",
        "features": [
          "private_networking",
          "backups",
          "ipv6",
          "metadata",
          "install_agent",
          "storage",
          "image_transfer"
        ],
        "available": true,
        "sizes": [
          "s-1vcpu-1gb",
          "s-1vcpu-2gb",
          "s-1vcpu-3gb",
          "s-2vcpu-2gb",
          "s-3vcpu-1gb",
          "s-2vcpu-4gb",
          "s-4vcpu-8gb",
          "s-6vcpu-16gb",
          "s-8vcpu-32gb",
          "s-12vcpu-48gb",
          "s-16vcpu-64gb",
          "s-20vcpu-96gb",
          "s-24vcpu-128gb",
          "s-32vcpu-192g"
        ]
      },
      "tags": [
        "env:stage"
      ],
      "vpc_uuid": "5a4981aa-9653-4bd1-bef5-d6bff52042e4",
      "subnet_uuid": "0f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8"
    }
  ],
  "links": {
    "pages": {}
  },
  "meta": {
    "total": 3
  }
}

More Information

See GET /v2/droplets in the API reference for additional detail on responses, headers, parameters, and more.

See the Go package documentation for the source of this method.

We can't find any results for your search.

Try using different keywords or simplifying your search terms.