# Get the history of an image


[API catalog](/reference/api/) · [Docker Engine overview](/reference/api/engine/version/v1.57/) · [Product manual](https://docs.docker.com/engine/) · [OpenAPI specification](/reference/api/engine/version/v1.57.yaml)

API version: 1.57





`GET /images/{name}/history`

Return parent layers of an image.

## Connection and access

[API connection and authentication guidance](/reference/api/engine/version/v1.57/#connection)


Server: `/v1.57`

Effective security: alternatives are OR; schemes within an alternative are AND. An empty array declares no HTTP authentication requirement.

```json
null
```

## Example request

Replace placeholders and provide the required credentials or request body.

```console
curl \
  --request GET \
  --unix-socket "${DOCKER_SOCKET:-/var/run/docker.sock}" \
  --header 'Accept: application/json' \
  'http://localhost/v1.57/images/<NAME>/history'
```



## Parameters

### name

Location: path. Required: yes.

Image name or ID

```json
{
  "description": "Image name or ID",
  "in": "path",
  "name": "name",
  "pointer": "/paths/~1images~1{name}~1history/get/parameters/0",
  "required": true,
  "schema": {
    "type": "string"
  }
}
```

### platform

Location: query. Required: no.

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"}`


```json
{
  "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",
  "pointer": "/paths/~1images~1{name}~1history/get/parameters/1",
  "schema": {
    "type": "string"
  }
}
```

## Request and responses

### Response 200 application/json

List of image layers


Schema:

```json
{
  "items": {
    "$ref": "#/components/schemas/ImageHistoryResponseItem"
  },
  "type": "array"
}
```









Example:
```json
[
  {
    "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 application/json

No such image


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


### Response 500 application/json

Server error


Schema:

```json
{
  "$ref": "#/components/schemas/ErrorResponse"
}
```









Schema example:
```json
{
  "message": "Something went wrong."
}
```


## Complete operation contract

```json
{
  "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"
  ]
}
```

## Referenced schemas

- [#/components/schemas/ErrorResponse](/reference/api/engine/version/v1.57/schemas/ErrorResponse/)

- [#/components/schemas/ImageHistoryResponseItem](/reference/api/engine/version/v1.57/schemas/ImageHistoryResponseItem/)




