# Docker Hub API

> Docker Hub returns container image search results, image details and tags as a workflow and API.

Docker Hub searches public container images by software or image name, with optional result count and official or verified publisher filtering. Get container image returns image details and recently updated tags from an image name or Docker Hub page link.

- Page: https://fous.com/workflows/docker-hub
- Handle: `@docker-hub`
- Category: [Developer tools](https://fous.com/workflows/category/developer-tools)
- Source website: https://hub.docker.com
- Last verified: Sep 29, 2026
- Fous is not affiliated with Docker Hub.

## Methods

### Get container image

Operation `get_container_image`, version 1. 1 credit per call.

Get public Docker Hub image details and recently updated image tags from a name or Docker Hub link. Ancillary signature and metadata tags are omitted; size is the reported compressed tag size.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `image` | string | yes | `"postgres"` | Image name or Docker Hub page link, for example postgres or https://hub.docker.com/r/bitnami/redis. A bare name is official. |
| `max_tags` | integer | no | `5` | Number of newest tags to show, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "image"
  ],
  "properties": {
    "image": {
      "type": "string",
      "minLength": 1,
      "description": "Image name or Docker Hub page link, for example postgres or https://hub.docker.com/r/bitnami/redis. A bare name is official.",
      "examples": [
        "postgres",
        "https://hub.docker.com/r/bitnami/redis"
      ]
    },
    "max_tags": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Number of newest tags to show, for example 20.",
      "examples": [
        5
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "image": "postgres"
    },
    {
      "image": "https://hub.docker.com/r/bitnami/redis",
      "max_tags": 5
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `link` | string | `"https://hub.docker.com/_/postgres"` | Docker Hub image page. |
| `tags` | array |  | Newest image tags first, excluding publisher signature and metadata artifact tags. |
| `tags[].link` | string | `"https://hub.docker.com/_/postgres/tags?name=19beta4-trixie"` | Docker Hub tag page. |
| `tags[].name` | string | `"19beta4-trixie"` | Tag name. |
| `tags[].digest` | string or null | `"sha256:5b87ea8650be6db1308cf8e99b7e4bd909c40bdbeefe6e347772943f955f76d9"` | Tag manifest digest. |
| `tags[].architectures` | array |  | Available architectures; empty when not reported. |
| `tags[].last_pushed_date` | string or null | `"2026-09-25"` | Last pushed date, YYYY-MM-DD. |
| `tags[].compressed_size_mb` | number or null | `163.84` | Reported compressed tag size in decimal megabytes. |
| `stars` | integer or null | `15024` | Number of stars. |
| `publisher` | string or null | `"Docker Official Images"` | Publisher name. |
| `image_name` | string | `"postgres"` | Image name; official images omit the library namespace. |
| `description` | string or null | `"The PostgreSQL object-relational database system provides reliability and data integrity."` | Short description. |
| `total_pulls` | integer or null | `11657977851` | Lifetime pull count. |
| `last_updated_date` | string or null | `"2026-09-25"` | Last updated date, YYYY-MM-DD. |

**Example input**

```json
{
  "image": "postgres"
}
```

**Example output**

```json
{
  "link": "https://hub.docker.com/_/postgres",
  "tags": [
    {
      "link": "https://hub.docker.com/_/postgres/tags?name=19beta4-trixie",
      "name": "19beta4-trixie",
      "digest": "sha256:5b87ea8650be6db1308cf8e99b7e4bd909c40bdbeefe6e347772943f955f76d9",
      "architectures": [
        "386",
        "amd64",
        "arm"
      ],
      "last_pushed_date": "2026-09-25",
      "compressed_size_mb": 163.84
    },
    {
      "link": "https://hub.docker.com/_/postgres/tags?name=19beta4-bookworm",
      "name": "19beta4-bookworm",
      "digest": "sha256:288c9defbb13c05fed2bfb55f859f1cf65dbd600f45bc89c91efbdd8f2a1e7b9",
      "architectures": [
        "386",
        "amd64",
        "arm"
      ],
      "last_pushed_date": "2026-09-25",
      "compressed_size_mb": 158.63
    },
    {
      "link": "https://hub.docker.com/_/postgres/tags?name=19beta4-alpine3.24",
      "name": "19beta4-alpine3.24",
      "digest": "sha256:fc1f3e7a1b86bee408ccaea1666c263d1089cbbfd3f1dfb04dcdf85f46b8085a",
      "architectures": [
        "386",
        "amd64",
        "arm"
      ],
      "last_pushed_date": "2026-09-25",
      "compressed_size_mb": 121.09
    }
  ],
  "stars": 15024,
  "publisher": "Docker Official Images",
  "image_name": "postgres",
  "description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
  "total_pulls": 11657977851,
  "last_updated_date": "2026-09-25"
}
```

### Search container images

Operation `search_container_images`, version 1. 1 credit per call.

Find public Docker Hub container images matching a software name, in Docker Hub search order. Pull totals may lag live counts or be unavailable for some images.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `query` | string | yes | `"postgres"` | Software or container image to search for, for example postgres. |
| `max_results` | integer | no | `5` | Maximum number of images to return, for example 20 (up to 100). |
| `official_only` | boolean | no | `true` | For example true to include only Docker Official Images and Verified Publisher images. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Software or container image to search for, for example postgres.",
      "examples": [
        "postgres",
        "nginx",
        "zzzxqvnevermatches829374abc"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum number of images to return, for example 20 (up to 100).",
      "x-fous-developer": true,
      "examples": [
        5,
        3
      ]
    },
    "official_only": {
      "type": "boolean",
      "default": false,
      "description": "For example true to include only Docker Official Images and Verified Publisher images.",
      "examples": [
        true
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "query": "postgres"
    },
    {
      "query": "nginx",
      "max_results": 5,
      "official_only": true
    },
    {
      "query": "zzzxqvnevermatches829374abc",
      "max_results": 3
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `images` | array |  | Matching images in Docker Hub search order. |
| `images[].link` | string | `"https://hub.docker.com/_/postgres"` | Docker Hub image page. |
| `images[].badge` | string | `"official"` | Docker Hub badge. |
| `images[].stars` | integer or null | `15023` | Number of stars. |
| `images[].publisher` | string or null | `"library"` | Publisher shown on Docker Hub. |
| `images[].image_name` | string | `"postgres"` | Container image name. |
| `images[].description` | string or null | `"The PostgreSQL object-relational database system provides reliability and data integrity."` | Short image description. |
| `images[].total_pulls` | integer or null | `11635385361` | Exact total pulls, when publicly available. |
| `images[].last_updated` | string or null | `"2026-09-25"` | Last updated date. |

**Example input**

```json
{
  "query": "postgres"
}
```

**Example output**

```json
{
  "images": [
    {
      "link": "https://hub.docker.com/_/postgres",
      "badge": "official",
      "stars": 15023,
      "publisher": "library",
      "image_name": "postgres",
      "description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
      "total_pulls": 11635385361,
      "last_updated": "2026-09-25"
    },
    {
      "link": "https://hub.docker.com/r/cimg/postgres",
      "badge": "verified publisher",
      "stars": 9,
      "publisher": "CircleCI",
      "image_name": "cimg/postgres",
      "description": null,
      "total_pulls": 810616127,
      "last_updated": "2026-08-14"
    },
    {
      "link": "https://hub.docker.com/r/circleci/postgres",
      "badge": "verified publisher",
      "stars": 35,
      "publisher": "CircleCI",
      "image_name": "circleci/postgres",
      "description": "The PostgreSQL object-relational database system provides reliability and data integrity.",
      "total_pulls": 510187680,
      "last_updated": "2021-12-18"
    }
  ]
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@docker-hub",
  "visibility": "public",
  "operation": "get_container_image",
  "version": 1,
  "input": {
    "image": "postgres"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@docker-hub\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_container_image\",\n  \"version\": 1,\n  \"input\": {\n    \"image\": \"postgres\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@docker-hub",
  "visibility": "public",
  "operation": "get_container_image",
  "version": 1,
  "input": {
    "image": "postgres"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@docker-hub","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Find container images for a software project
- Compare image stars and publisher names
- Review image tags and supported architectures
- Check tag push dates and compressed sizes
- Track publicly available image pull counts

## FAQ

### Is Fous affiliated with Docker Hub?

No. Fous is not affiliated with Docker Hub. This workflow reads the public hub.docker.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a Docker Hub account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from hub.docker.com when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 29, 2026.

### Which images match a software name?

Search container images returns matching public images in Docker Hub search order.

### What tags are available for an image?

Get container image returns recently updated tags, including their names, architectures, push dates and reported compressed sizes.

### How many stars or pulls does an image have?

Search container images and Get container image return star counts and pull totals when available.

## Related

- [GitHub API](https://fous.com/workflows/github.md): GitHub returns public repository matches and details, up to 25 trending projects, issues, pull requests, and newest-first published releases; release or commit dates may be unavailable.
- [npm API](https://fous.com/workflows/npm.md): npm provides package details, search results and latest versions, plus weekly download and publish data; daily and historical download counts may lag by a day or more.
- [NuGet API](https://fous.com/workflows/nuget.md): The .NET package gallery for discovering and sharing packages.
- [RubyGems API](https://fous.com/workflows/rubygems.md): Discover and share Ruby gems.
- [Google Search API](https://fous.com/workflows/google-search.md): Google Search returns public web, image, job, event, related-question, and autocomplete results in Google’s order, with answers and details when available; results may be fewer, omit information, or be empty.
- [crates.io API](https://fous.com/workflows/crates-io.md): crates.io is the Rust community package registry, returning current crate details and recent releases or up to 100 keyword-matched crates with version, download, and update information.
- [Hugging Face API](https://fous.com/workflows/hugging-face.md): Hugging Face returns public model, dataset, and demo search results, model details, or weekly trending models; unpublished information may be missing, and demo availability can change.
- [PyPI API](https://fous.com/workflows/pypi.md): PyPI provides package metadata, links, and current/latest plus 10 recent versions; release dates reflect first file uploads, and keyword searches return up to 100 packages.
- [All Developer tools workflows](https://fous.com/workflows/category/developer-tools)