Search or ask Docker

Get the history of an image

GET /images/{name}/history — Docker Engine API 1.57.

View Markdown
GET/images/{name}/history
Return parent layers of an image.

Connection and access

API connection and authentication guidance

/v1.57

No HTTP authentication requirement is declared for this operation. Transport access controls can still apply.

Parameters

name path Required

Image name or ID

Type: string

All schema constraints and annotations
{
  "type": "string"
}

platform query

JSON-encoded OCI platform to select the platform-variant. If omitted, it defaults to any locally available platform, prioritizing the daemon's host platform.

If the daemon provides a multi-platform image store, this selects the platform-variant to show the history for. If the image is a single-platform image, or if the multi-platform image does not provide a variant matching the given platform, an error is returned.

Example: {"os": "linux", "architecture": "arm", "variant": "v5"}

Type: string

All schema constraints and annotations
{
  "type": "string"
}

Request and responses

Response 200

List of image layers

application/json

Type: array

Array item

Schema: ImageHistoryResponseItem

All schema constraints and annotations
{
  "items": {
    "$ref": "#/components/schemas/ImageHistoryResponseItem"
  },
  "type": "array"
}

Example

[
  {
    "Comment": "",
    "Created": 1398108230,
    "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
    "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
    "Size": 182964289,
    "Tags": [
      "ubuntu:lucid",
      "ubuntu:10.04"
    ]
  },
  {
    "Comment": "",
    "Created": 1398108222,
    "CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi \u003cadmwiggin@gmail.com\u003e - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
    "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
    "Size": 0,
    "Tags": []
  },
  {
    "Comment": "Imported from -",
    "Created": 1371157430,
    "CreatedBy": "",
    "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
    "Size": 0,
    "Tags": [
      "scratch12:latest",
      "scratch:latest"
    ]
  }
]

Response 404

No such image

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Response 500

Server error

application/json

Schema: ErrorResponse

Schema example

{
  "message": "Something went wrong."
}

Referenced schemas

#/components/schemas/ErrorResponse

#/components/schemas/ImageHistoryResponseItem

Complete operation contract
{
  "description": "Return parent layers of an image.",
  "operationId": "ImageHistory",
  "parameters": [
    {
      "description": "Image name or ID",
      "in": "path",
      "name": "name",
      "required": true,
      "schema": {
        "type": "string"
      }
    },
    {
      "description": "JSON-encoded OCI platform to select the platform-variant.\nIf omitted, it defaults to any locally available platform,\nprioritizing the daemon's host platform.\n\nIf the daemon provides a multi-platform image store, this selects\nthe platform-variant to show the history for. If the image is\na single-platform image, or if the multi-platform image does not\nprovide a variant matching the given platform, an error is returned.\n\nExample: `{\"os\": \"linux\", \"architecture\": \"arm\", \"variant\": \"v5\"}`\n",
      "in": "query",
      "name": "platform",
      "schema": {
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "example": [
            {
              "Comment": "",
              "Created": 1398108230,
              "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /",
              "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710",
              "Size": 182964289,
              "Tags": [
                "ubuntu:lucid",
                "ubuntu:10.04"
              ]
            },
            {
              "Comment": "",
              "Created": 1398108222,
              "CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi \u003cadmwiggin@gmail.com\u003e - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/",
              "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8",
              "Size": 0,
              "Tags": []
            },
            {
              "Comment": "Imported from -",
              "Created": 1371157430,
              "CreatedBy": "",
              "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158",
              "Size": 0,
              "Tags": [
                "scratch12:latest",
                "scratch:latest"
              ]
            }
          ],
          "schema": {
            "items": {
              "$ref": "#/components/schemas/ImageHistoryResponseItem"
            },
            "type": "array"
          }
        }
      },
      "description": "List of image layers"
    },
    "404": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "No such image"
    },
    "500": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorResponse"
          }
        }
      },
      "description": "Server error"
    }
  },
  "summary": "Get the history of an image",
  "tags": [
    "Image"
  ]
}