--- title: "Get data usage information" method: GET path: "/system/df" tags: ["System"] --- # Get data usage information `GET /system/df` ## Query parameters - `type` string[] ## Response `200` no error - object - `LayersSize` integer - `Images` ImageSummary[] - `Id` string, required — ID is the content-addressable ID of an image. This identifier is a content-addressable digest calculated from the image's configuration (which includes the digests of layers used by the image). Note that this digest differs from the `RepoDigests` below, which holds digests of image manifests that reference the image. - `ParentId` string, required — ID of the parent image. Depending on how the image was created, this field may be empty and is only set for images that were built/created locally. This field is empty if the image was pulled from an image registry. - `RepoTags` string[], required — List of image names/tags in the local image cache that reference this image. Multiple image tags can refer to the same image, and this list may be empty if no tags reference the image, in which case the image is "untagged", in which case it can still be referenced by its ID. - `RepoDigests` string[], required — List of content-addressable digests of locally available image manifests that the image is referenced from. Multiple manifests can refer to the same image. These digests are usually only available if the image was either pulled from a registry, or if the image was pushed to a registry, which is when the manifest is generated and its digest calculated. - `Created` integer, required — Date and time at which the image was created as a Unix timestamp (number of seconds since EPOCH). - `Size` integer, required — Total size of the image including all layers it is composed of. - `SharedSize` integer, required — Total size of image layers that are shared between this image and other images. This size is not calculated by default. `-1` indicates that the value has not been set / calculated. - `VirtualSize` integer — Total size of the image including all layers it is composed of. Deprecated: this field is omitted in API v1.44, but kept for backward compatibility. Use Size instead. - `Labels` object, required — User-defined key/value metadata. - `Containers` integer, required — Number of containers using this image. Includes both stopped and running containers. `-1` indicates that the value has not been set / calculated. - `Manifests` ImageManifestSummary[] — Manifests is a list of manifests available in this image. It provides a more detailed view of the platform-specific image manifests or other image-attached data like build attestations. WARNING: This is experimental and may change at any time without any backward compatibility. - `ID` string, required — ID is the content-addressable ID of an image and is the same as the digest of the image manifest. - `Descriptor` OCIDescriptor, required — A descriptor struct containing digest, media type, and size, as defined in the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md). - `mediaType` string — The media type of the object this schema refers to. - `digest` string — The digest of the targeted content. - `size` integer — The size in bytes of the blob. - `urls` string[], nullable — List of URLs from which this object MAY be downloaded. - `annotations` object, nullable — Arbitrary metadata relating to the targeted content. - `data` string, nullable — Data is an embedding of the targeted content. This is encoded as a base64 string when marshalled to JSON (automatically, by encoding/json). If present, Data can be used directly to avoid fetching the targeted content. - `platform` OCIPlatform, nullable — Describes the platform which the image in the manifest runs on, as defined in the [OCI Image Index Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md). - `architecture` string — The CPU architecture, for example `amd64` or `ppc64`. - `os` string — The operating system, for example `linux` or `windows`. - `os.version` string — Optional field specifying the operating system version, for example on Windows `10.0.19041.1165`. - `os.features` string[] — Optional field specifying an array of strings, each listing a required OS feature (for example on Windows `win32k`). - `variant` string — Optional field specifying a variant of the CPU, for example `v7` to specify ARMv7 when architecture is `arm`. - `artifactType` string, nullable — ArtifactType is the IANA media type of this artifact. - `Available` boolean, required — Indicates whether all the child content (image config, layers) is fully available locally. - `Size` object, required - `Total` integer, required — Total is the total size (in bytes) of all the locally present data (both distributable and non-distributable) that's related to this manifest and its children. This equal to the sum of [Content] size AND all the sizes in the [Size] struct present in the Kind-specific data struct. For example, for an image kind (Kind == "image") this would include the size of the image content and unpacked image snapshots ([Size.Content] + [ImageData.Size.Unpacked]). - `Content` integer, required — Content is the size (in bytes) of all the locally present content in the content store (e.g. image config, layers) referenced by this manifest and its children. This only includes blobs in the content store. - `Kind` 'image' | 'attestation' | 'unknown', required — The kind of the manifest. kind | description -------------|----------------------------------------------------------- image | Image manifest that can be used to start a container. attestation | Attestation manifest produced by the Buildkit builder for a specific image manifest. - `ImageData` object, nullable — The image data for the image manifest. This field is only populated when Kind is "image". - `Platform` OCIPlatform, nullable, required — Describes the platform which the image in the manifest runs on, as defined in the [OCI Image Index Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md). - `architecture` string — The CPU architecture, for example `amd64` or `ppc64`. - `os` string — The operating system, for example `linux` or `windows`. - `os.version` string — Optional field specifying the operating system version, for example on Windows `10.0.19041.1165`. - `os.features` string[] — Optional field specifying an array of strings, each listing a required OS feature (for example on Windows `win32k`). - `variant` string — Optional field specifying a variant of the CPU, for example `v7` to specify ARMv7 when architecture is `arm`. - `Containers` string[], required — The IDs of the containers that are using this image. - `Size` object, required - `Unpacked` integer, required — Unpacked is the size (in bytes) of the locally unpacked (uncompressed) image content that's directly usable by the containers running this image. It's independent of the distributable content - e.g. the image might still have an unpacked data that's still used by some container even when the distributable/compressed content is already gone. - `AttestationData` object, nullable — The image data for the attestation manifest. This field is only populated when Kind is "attestation". - `For` string, required — The digest of the image manifest that this attestation is for. - `Descriptor` OCIDescriptor — A descriptor struct containing digest, media type, and size, as defined in the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md). - `mediaType` string — The media type of the object this schema refers to. - `digest` string — The digest of the targeted content. - `size` integer — The size in bytes of the blob. - `urls` string[], nullable — List of URLs from which this object MAY be downloaded. - `annotations` object, nullable — Arbitrary metadata relating to the targeted content. - `data` string, nullable — Data is an embedding of the targeted content. This is encoded as a base64 string when marshalled to JSON (automatically, by encoding/json). If present, Data can be used directly to avoid fetching the targeted content. - `platform` OCIPlatform, nullable — Describes the platform which the image in the manifest runs on, as defined in the [OCI Image Index Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md). - `architecture` string — The CPU architecture, for example `amd64` or `ppc64`. - `os` string — The operating system, for example `linux` or `windows`. - `os.version` string — Optional field specifying the operating system version, for example on Windows `10.0.19041.1165`. - `os.features` string[] — Optional field specifying an array of strings, each listing a required OS feature (for example on Windows `win32k`). - `variant` string — Optional field specifying a variant of the CPU, for example `v7` to specify ARMv7 when architecture is `arm`. - `artifactType` string, nullable — ArtifactType is the IANA media type of this artifact. - `Containers` ContainerSummary[] - `Id` string — The ID of this container as a 128-bit (64-character) hexadecimal string (32 bytes). - `Names` string[] — The names associated with this container. Most containers have a single name, but when using legacy "links", the container can have multiple names. For historic reasons, names are prefixed with a forward-slash (`/`). - `Image` string — The name or ID of the image used to create the container. This field shows the image reference as was specified when creating the container, which can be in its canonical form (e.g., `docker.io/library/ubuntu:latest` or `docker.io/library/ubuntu@sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782`), short form (e.g., `ubuntu:latest`)), or the ID(-prefix) of the image (e.g., `72297848456d`). The content of this field can be updated at runtime if the image used to create the container is untagged, in which case the field is updated to contain the the image ID (digest) it was resolved to in its canonical, non-truncated form (e.g., `sha256:72297848456d5d37d1262630108ab308d3e9ec7ed1c3286a32fe09856619a782`). - `ImageID` string — The ID (digest) of the image that this container was created from. - `ImageManifestDescriptor` OCIDescriptor — A descriptor struct containing digest, media type, and size, as defined in the [OCI Content Descriptors Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/descriptor.md). - `mediaType` string — The media type of the object this schema refers to. - `digest` string — The digest of the targeted content. - `size` integer — The size in bytes of the blob. - `urls` string[], nullable — List of URLs from which this object MAY be downloaded. - `annotations` object, nullable — Arbitrary metadata relating to the targeted content. - `data` string, nullable — Data is an embedding of the targeted content. This is encoded as a base64 string when marshalled to JSON (automatically, by encoding/json). If present, Data can be used directly to avoid fetching the targeted content. - `platform` OCIPlatform, nullable — Describes the platform which the image in the manifest runs on, as defined in the [OCI Image Index Specification](https://github.com/opencontainers/image-spec/blob/v1.0.1/image-index.md). - `architecture` string — The CPU architecture, for example `amd64` or `ppc64`. - `os` string — The operating system, for example `linux` or `windows`. - `os.version` string — Optional field specifying the operating system version, for example on Windows `10.0.19041.1165`. - `os.features` string[] — Optional field specifying an array of strings, each listing a required OS feature (for example on Windows `win32k`). - `variant` string — Optional field specifying a variant of the CPU, for example `v7` to specify ARMv7 when architecture is `arm`. - `artifactType` string, nullable — ArtifactType is the IANA media type of this artifact. - `Command` string — Command to run when starting the container - `Created` integer — Date and time at which the container was created as a Unix timestamp (number of seconds since EPOCH). - `Ports` Port[] — Port-mappings for the container. - `IP` string, ip-address — Host IP address that the container's port is mapped to - `PrivatePort` integer, required — Port on the container - `PublicPort` integer — Port exposed on the host - `Type` 'tcp' | 'udp' | 'sctp', required - `SizeRw` integer, nullable — The size of files that have been created or changed by this container. This field is omitted by default, and only set when size is requested in the API request. - `SizeRootFs` integer, nullable — The total size of all files in the read-only layers from the image that the container uses. These layers can be shared between containers. This field is omitted by default, and only set when size is requested in the API request. - `Labels` object — User-defined key/value metadata. - `State` 'created' | 'running' | 'paused' | 'restarting' | 'exited' | 'removing' | 'dead' — The state of this container. - `Status` string — Additional human-readable status of this container (e.g. `Exit 0`) - `HostConfig` object — Summary of host-specific runtime information of the container. This is a reduced set of information in the container's "HostConfig" as available in the container "inspect" response. - `NetworkMode` string — Networking mode (`host`, `none`, `container:`) or name of the primary network the container is using. This field is primarily for backward compatibility. The container can be connected to multiple networks for which information can be found in the `NetworkSettings.Networks` field, which enumerates settings per network. - `Annotations` object, nullable — Arbitrary key-value metadata attached to the container. - `NetworkSettings` object — Summary of the container's network settings - `Networks` object — Summary of network-settings for each network the container is attached to. - `Mounts` MountPoint[] — List of mounts used by the container. - `Type` 'bind' | 'volume' | 'image' | 'tmpfs' | 'npipe' | 'cluster' — The mount type: - `bind` a mount of a file or directory from the host into the container. - `volume` a docker volume with the given `Name`. - `image` a docker image - `tmpfs` a `tmpfs`. - `npipe` a named pipe from the host into the container. - `cluster` a Swarm cluster volume - `Name` string — Name is the name reference to the underlying data defined by `Source` e.g., the volume name. - `Source` string — Source location of the mount. For volumes, this contains the storage location of the volume (within `/var/lib/docker/volumes/`). For bind-mounts, and `npipe`, this contains the source (host) part of the bind-mount. For `tmpfs` mount points, this field is empty. - `Destination` string — Destination is the path relative to the container root (`/`) where the `Source` is mounted inside the container. - `Driver` string — Driver is the volume driver used to create the volume (if it is a volume). - `Mode` string — Mode is a comma separated list of options supplied by the user when creating the bind/volume mount. The default is platform-specific (`"z"` on Linux, empty on Windows). - `RW` boolean — Whether the mount is mounted writable (read-write). - `Propagation` string — Propagation describes how mounts are propagated from the host into the mount point, and vice-versa. Refer to the [Linux kernel documentation](https://www.kernel.org/doc/Documentation/filesystems/sharedsubtree.txt) for details. This field is not used on Windows. - `Volumes` Volume[] - `Name` string, required — Name of the volume. - `Driver` string, required — Name of the volume driver used by the volume. - `Mountpoint` string, required — Mount path of the volume on the host. - `CreatedAt` string, dateTime — Date/Time the volume was created. - `Status` object — Low-level details about the volume, provided by the volume driver. Details are returned as a map with key/value pairs: `{"key":"value","key2":"value2"}`. The `Status` field is optional, and is omitted if the volume driver does not support this feature. - `Labels` object, required — User-defined key/value metadata. - `Scope` 'local' | 'global', required — The level at which the volume exists. Either `global` for cluster-wide, or `local` for machine level. - `ClusterVolume` ClusterVolume — Options and information specific to, and only present on, Swarm CSI cluster volumes. - `ID` string — The Swarm ID of this volume. Because cluster volumes are Swarm objects, they have an ID, unlike non-cluster volumes. This ID can be used to refer to the Volume instead of the name. - `Version` ObjectVersion — The version number of the object such as node, service, etc. This is needed to avoid conflicting writes. The client must send the version number along with the modified specification when updating these objects. This approach ensures safe concurrency and determinism in that the change on the object may not be applied if the version number has changed from the last read. In other words, if two update requests specify the same base version, only one of the requests can succeed. As a result, two separate update requests that happen at the same time will not unintentionally overwrite each other. - `Index` integer - `CreatedAt` string, dateTime - `UpdatedAt` string, dateTime - `Spec` ClusterVolumeSpec — Cluster-specific options used to create the volume. - `Group` string — Group defines the volume group of this volume. Volumes belonging to the same group can be referred to by group name when creating Services. Referring to a volume by group instructs Swarm to treat volumes in that group interchangeably for the purpose of scheduling. Volumes with an empty string for a group technically all belong to the same, emptystring group. - `AccessMode` object — Defines how the volume is used by tasks. - `Scope` 'single' | 'multi' — The set of nodes this volume can be used on at one time. - `single` The volume may only be scheduled to one node at a time. - `multi` the volume may be scheduled to any supported number of nodes at a time. - `Sharing` 'none' | 'readonly' | 'onewriter' | 'all' — The number and way that different tasks can use this volume at one time. - `none` The volume may only be used by one task at a time. - `readonly` The volume may be used by any number of tasks, but they all must mount the volume as readonly - `onewriter` The volume may be used by any number of tasks, but only one may mount it as read/write. - `all` The volume may have any number of readers and writers. - `MountVolume` object — Options for using this volume as a Mount-type volume. Either MountVolume or BlockVolume, but not both, must be present. properties: FsType: type: "string" description: | Specifies the filesystem type for the mount volume. Optional. MountFlags: type: "array" description: | Flags to pass when mounting the volume. Optional. items: type: "string" BlockVolume: type: "object" description: | Options for using this volume as a Block-type volume. Intentionally empty. - `Secrets` object[] — Swarm Secrets that are passed to the CSI storage plugin when operating on this volume. - `Key` string — Key is the name of the key of the key-value pair passed to the plugin. - `Secret` string — Secret is the swarm Secret object from which to read data. This can be a Secret name or ID. The Secret data is retrieved by swarm and used as the value of the key-value pair passed to the plugin. - `AccessibilityRequirements` object — Requirements for the accessible topology of the volume. These fields are optional. For an in-depth description of what these fields mean, see the CSI specification. - `Requisite` Topology[] — A list of required topologies, at least one of which the volume must be accessible from. - … - `Preferred` Topology[] — A list of topologies that the volume should attempt to be provisioned in. - … - `CapacityRange` object — The desired capacity that the volume should be created with. If empty, the plugin will decide the capacity. - `RequiredBytes` integer — The volume must be at least this big. The value of 0 indicates an unspecified minimum - `LimitBytes` integer — The volume must not be bigger than this. The value of 0 indicates an unspecified maximum. - `Availability` 'active' | 'pause' | 'drain' — The availability of the volume for use in tasks. - `active` The volume is fully available for scheduling on the cluster - `pause` No new workloads should use the volume, but existing workloads are not stopped. - `drain` All workloads using this volume should be stopped and rescheduled, and no new ones should be started. - `Info` object — Information about the global status of the volume. - `CapacityBytes` integer — The capacity of the volume in bytes. A value of 0 indicates that the capacity is unknown. - `VolumeContext` object — A map of strings to strings returned from the storage plugin when the volume is created. - `VolumeID` string — The ID of the volume as returned by the CSI storage plugin. This is distinct from the volume's ID as provided by Docker. This ID is never used by the user when communicating with Docker to refer to this volume. If the ID is blank, then the Volume has not been successfully created in the plugin yet. - `AccessibleTopology` Topology[] — The topology this volume is actually accessible from. - `PublishStatus` object[] — The status of the volume as it pertains to its publishing and use on specific nodes - `NodeID` string — The ID of the Swarm node the volume is published on. - `State` 'pending-publish' | 'published' | 'pending-node-unpublish' | 'pending-controller-unpublish' — The published state of the volume. * `pending-publish` The volume should be published to this node, but the call to the controller plugin to do so has not yet been successfully completed. * `published` The volume is published successfully to the node. * `pending-node-unpublish` The volume should be unpublished from the node, and the manager is awaiting confirmation from the worker that it has done so. * `pending-controller-unpublish` The volume is successfully unpublished from the node, but has not yet been successfully unpublished on the controller. - `PublishContext` object — A map of strings to strings returned by the CSI controller plugin when a volume is published. - `Options` object, required — The driver specific options used when creating the volume. - `UsageData` object, nullable — Usage details about the volume. This information is used by the `GET /system/df` endpoint, and omitted in other endpoints. - `Size` integer, required — Amount of disk space used by the volume (in bytes). This information is only available for volumes created with the `"local"` volume driver. For volumes created with other volume drivers, this field is set to `-1` ("not available") - `RefCount` integer, required — The number of containers referencing this volume. This field is set to `-1` if the reference-count is not available. - `BuildCache` BuildCache[] - `ID` string — Unique ID of the build cache record. - `Parent` string, nullable — ID of the parent build cache record. > **Deprecated**: This field is deprecated, and omitted if empty. - `Parents` string[], nullable — List of parent build cache record IDs. - `Type` 'internal' | 'frontend' | 'source.local' | 'source.git.checkout' | 'exec.cachemount' | 'regular' — Cache record type. - `Description` string — Description of the build-step that produced the build cache. - `InUse` boolean — Indicates if the build cache is in use. - `Shared` boolean — Indicates if the build cache is shared. - `Size` integer — Amount of disk space used by the build cache (in bytes). - `CreatedAt` string, dateTime — Date and time at which the build cache was created in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. - `LastUsedAt` string, dateTime, nullable — Date and time at which the build cache was last used in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format with nano-seconds. - `UsageCount` integer ## Other responses - `500` — server error --- [API](https://skmtc.net/nhost/apis/docker-engine-api.md) · [All operations](https://skmtc.net/nhost/apis/docker-engine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nhost/docker-engine-api/versions/2b8dc7a7cc52/schema)