Tags

List Tagged Objects

get
https://api.linode.com/v4/tags/{label}

Returns a paginated list of all objects you've tagged with the requested Tag. This is a mixed collection of all object types.

Authorizations

Personal Access Token
OAuth: ( account:read_only)

Path Parameters

label
Required
string

Query Parameters

page
integer > = 1
Default: 1

The page of a collection to return.

page_size
integer [25 .. 100]
Default: 100

The number of items to return per page.

Request Samples

    Response Samples

    {
      "data": [
        {
          "type": "linode",
          "data": {
            "label": "balancer12345",
            "region": "us-east",
            "image": "",
            "type": "master",
            "group": "",
            "tags": [
              "example tag",
              "another example"
            ],
            "id": 12345,
            "status": "active",
            "hypervisor": "kvm",
            "created": "2018-01-01T00:01:01.000Z",
            "updated": "2018-03-01T00:01:01.000Z",
            "ipv4": "",
            "ipv6": "",
            "specs": {
              "disk": 81920,
              "memory": 4096,
              "vcpus": 2,
              "transfer": 4000
            },
            "alerts": {
              "cpu": 180,
              "network_in": 10,
              "network_out": 10,
              "transfer_quota": 80,
              "io": 10000
            },
            "backups": {
              "enabled": true,
              "schedule": ""
            },
            "watchdog_enabled": true,
            "domain": "example.org",
            "description": "",
            "soa_email": "admin@example.org",
            "retry_sec": 300,
            "master_ips": "",
            "axfr_ips": "",
            "expire_sec": 300,
            "refresh_sec": 300,
            "ttl_sec": 300,
            "filesystem_path": "/dev/disk/by-id/scsi-0Linode_Volume_my-volume",
            "size": 30,
            "linode_id": 12346,
            "hostname": "nb-207-192-68-16.newark.nodebalancer.linode.com",
            "client_conn_throttle": "",
            "transfer": {
              "total": 32.46078109741211,
              "out": 3.5487728118896484,
              "in": 28.91200828552246
            }
          }
        }
      ],
      "page": 1,
      "pages": 1,
      "results": 1
    }

    Responses

    200: A paginated list of objects, organized by type, that have been tagged with the requested Tag.

    data
    array of objects
    type
    string
    data
    label
    Filterable

    The Linode's label is for display purposes only. If no label is provided for a Linode, a default will be assigned. Linode labels have the following constraints:

    • Must start with an alpha character.
    • May only consist of alphanumeric characters, dashes (-), underscores (_) or periods (.).
    • Cannot have two dashes (--), underscores (__) or periods (..) in a row.
    region
    Filterable

    This is the location where the Linode was deployed. A Linode's region can only be changed by initiating a cross data center migration.

    image
    Filterable
    Nullable
    type

    This is the Linode Type that this Linode was deployed with. To change a Linode's Type, use POST /linode/instances/{linodeId}/resize.

    group
    Filterable
    string
    Deprecated

    A deprecated property denoting a group label for this Linode.

    tags
    Filterable
    array

    An array of tags applied to this object. Tags are for organizational purposes only.

    id
    Filterable
    integer

    This Linode's ID which must be provided for all operations impacting this Linode.

    status
    string
    Enum: "running""offline""booting""rebooting""shutting_down""provisioning""deleting""migrating""rebuilding""cloning""restoring"

    A brief description of this Linode's current state. This field may change without direct action from you. For instance, the status will change to "running" when the boot process completes.

    hypervisor
    string
    Enum: "kvm"

    The virtualization software powering this Linode.

    created
    string

    When this Linode was created.

    updated
    string

    When this Linode was last updated.

    ipv4
    array

    This Linode's IPv4 Addresses. Each Linode is assigned a single public IPv4 address upon creation, and may get a single private IPv4 address if needed. You may need to open a support ticket to get additional IPv4 addresses.

    IPv4 addresses may be reassigned between your Linodes, or shared with other Linodes. See the /networking endpoints for details.

    ipv6
    string

    This Linode's IPv6 SLAAC addresses. This address is specific to a Linode, and may not be shared. If the Linode has not been assigned an IPv6 address, the return value will be null.

    specs
    object

    Information about the resources available to this Linode.

    disk
    integer

    The amount of storage space, in MB, this Linode has access to. A typical Linode will divide this space between a primary disk with an image deployed to it, and a swap disk, usually 512 MB. This is the default configuration created when deploying a Linode with an image through POST /linode/instances. While this configuration is suitable for 99% of use cases, if you need finer control over your Linode's disks, see the /linode/instances/{linodeId}/disks endpoints.

    memory
    integer

    The amount of RAM, in MB, this Linode has access to. Typically a Linode will choose to boot with all of its available RAM, but this can be configured in a Config profile, see the /linode/instances/{linodeId}/configs endpoints and the LinodeConfig object for more information.

    vcpus
    integer

    The number of vcpus this Linode has access to. Typically a Linode will choose to boot with all of its available vcpus, but this can be configured in a Config Profile, see the /linode/instances/{linodeId}/configs endpoints and the LinodeConfig object for more information.

    transfer
    integer

    The amount of network transfer this Linode is allotted each month.

    alerts
    object
    cpu
    integer

    The percentage of CPU usage required to trigger an alert. If the average CPU usage over two hours exceeds this value, we'll send you an alert. Your Linode's total CPU capacity is represented as 100%, multiplied by its number of cores.

    For example, a two core Linode's CPU capacity is represented as 200%. If you want to be alerted at 90% of a two core Linode's CPU capacity, set the alert value to 180.

    If the value is set to 0 (zero), the alert is disabled.

    network_in
    integer

    The amount of incoming traffic, in Mbit/s, required to trigger an alert. If the average incoming traffic over two hours exceeds this value, we'll send you an alert. If this is set to 0 (zero), the alert is disabled.

    network_out
    integer

    The amount of outbound traffic, in Mbit/s, required to trigger an alert. If the average outbound traffic over two hours exceeds this value, we'll send you an alert. If this is set to 0 (zero), the alert is disabled.

    transfer_quota
    integer

    The percentage of network transfer that may be used before an alert is triggered. When this value is exceeded, we'll alert you. If this is set to 0 (zero), the alert is disabled.

    io
    integer

    The amount of disk IO operation per second required to trigger an alert. If the average disk IO over two hours exceeds this value, we'll send you an alert. If set to 0 (zero), this alert is disabled.

    backups
    object

    Information about this Linode's backups status. For information about available backups, see /linode/instances/{linodeId}/backups.

    enabled
    boolean

    If this Linode has the Backup service enabled. To enable backups, see POST /linode/instances/{linodeId}/backups/enable.

    schedule
    object
    watchdog_enabled
    boolean

    The watchdog, named Lassie, is a Shutdown Watchdog that monitors your Linode and will reboot it if it powers off unexpectedly. It works by issuing a boot job when your Linode powers off without a shutdown job being responsible. To prevent a loop, Lassie will give up if there have been more than 5 boot jobs issued within 15 minutes.

    type
    string
    Enum: "master""slave"

    If this Domain represents the authoritative source of information for the domain it describes, or if it is a read-only copy of a master (also called a slave).

    group
    Filterable
    string
    Deprecated

    The group this Domain belongs to. This is for display purposes only.

    tags
    Filterable
    array

    An array of tags applied to this object. Tags are for organizational purposes only.

    id
    integer

    This Domain's unique ID

    status
    string
    Enum: "disabled""active""edit_mode""has_errors"

    Used to control whether this Domain is currently being rendered.

    domain
    Filterable
    string ([a-zA-Z0-9-_]{1,63}\.)+([a-zA-Z]{2,3}\.)?([a-zA-Z]{2,16}|xn--[a-zA-Z0-9]+\.?)

    The domain this Domain represents. Domain labels cannot be longer than 63 characters and must conform to RFC1035. Domains must be unique on Linode's platform, including across different Linode accounts; there cannot be two Domains representing the same domain.

    description
    string

    A description for this Domain. This is for display purposes only.

    soa_email
    string

    Start of Authority email address. This is required for master Domains.

    retry_sec
    integer

    The interval, in seconds, at which a failed refresh should be retried. Valid values are 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200 - any other value will be rounded to the nearest valid value.

    master_ips
    array

    The IP addresses representing the master DNS for this Domain.

    axfr_ips
    array

    The list of IPs that may perform a zone transfer for this Domain. This is potentially dangerous, and should be set to an empty list unless you intend to use it.

    expire_sec
    integer

    The amount of time in seconds that may pass before this Domain is no longer authoritative. Valid values are 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200 - any other value will be rounded to the nearest valid value.

    refresh_sec
    integer

    The amount of time in seconds before this Domain should be refreshed. Valid values are 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200 - any other value will be rounded to the nearest valid value.

    ttl_sec
    integer

    "Time to Live" - the amount of time in seconds that this Domain's records may be cached by resolvers or other domain servers.

    • Valid values are 0, 300, 3600, 7200, 14400, 28800, 57600, 86400, 172800, 345600, 604800, 1209600, and 2419200 - any other value will be rounded to the nearest valid value.
    • ttl_sec will default to 0 if no value is provided.
    • A value of 0 is equivalent to a value of 86400.
    label
    Filterable
    string ^[a-zA-Z]((?!--|__)[a-zA-Z0-9-_])+$

    The Volume's label is for display purposes only.

    region
    string

    The unique ID of this Region.

    tags
    Filterable
    array

    An array of Tags applied to this object. Tags are for organizational purposes only.

    id
    integer

    The unique ID of this Volume.

    status
    string
    Enum: "creating""active""resizing""contact_support"

    The current status of the volume. Can be one of:

    • creating - the Volume is being created and is not yet available for use.
    • active - the Volume is online and available for use.
    • resizing - the Volume is in the process of upgrading its current capacity.
    • contact_support - there is a problem with your Volume. Please open a Support Ticket to resolve the issue.
    created
    string

    When this Volume was created.

    updated
    string

    When this Volume was last updated.

    filesystem_path
    string

    The full filesystem path for the Volume based on the Volume's label. Path is /dev/disk/by-id/scsi-0LinodeVolume + Volume label.

    size
    integer

    The Volume's size, in GiB.

    linode_id
    Nullable
    integer

    If a Volume is attached to a specific Linode, the ID of that Linode will be displayed here.

    label
    Filterable
    string [a-zA-Z0-9-_]{3,32}

    This NodeBalancer's label. These must be unique on your Account.

    region
    Filterable
    string

    The Region where this NodeBalancer is located. NodeBalancers only support backends in the same Region.

    tags
    Filterable
    array

    An array of Tags applied to this object. Tags are for organizational purposes only.

    id
    integer

    This NodeBalancer's unique ID.

    created
    string

    When this NodeBalancer was created.

    updated
    string

    When this NodeBalancer was last updated.

    ipv4
    string

    This NodeBalancer's public IPv4 address.

    ipv6
    Nullable
    string

    This NodeBalancer's public IPv6 address.

    hostname
    string

    This NodeBalancer's hostname, ending with .nodebalancer.linode.com

    client_conn_throttle
    integer

    Throttle connections per second. Set to 0 (zero) to disable throttling.

    transfer
    object

    Information about the amount of transfer this NodeBalancer has had so far this month.

    total
    Nullable
    number

    The total transfer, in MB, used by this NodeBalancer this month.

    out
    Nullable
    number

    The total inbound transfer, in MB, used for this NodeBalancer this month.

    in
    Nullable
    number

    The total outbound transfer, in MB, used for this NodeBalancer this month.

    page
    integer
    pages
    integer
    results
    integer

    default: Error

    errors
    array of objects
    reason
    string

    What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

    field
    string

    The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.

    Delete a Tag

    delete
    https://api.linode.com/v4/tags/{label}

    Remove a Tag from all objects and delete it.

    Important: You must be an unrestricted User in order to add or modify Tags.

    Authorizations

    Personal Access Token
    OAuth: ( account:read_write)

    Path Parameters

    label
    Required
    string

    Request Samples

      Response Samples

      {}

      Responses

      200: Tag deleted.

      default: Error

      errors
      array of objects
      reason
      string

      What happened to cause this error. In most cases, this can be fixed immediately by changing the data you sent in the request, but in some cases you will be instructed to open a Support Ticket or perform some other action before you can complete the request successfully.

      field
      string

      The field in the request that caused this error. This may be a path, separated by periods in the case of nested fields. In some cases this may come back as "null" if the error is not specific to any single element of the request.