# Docker API: Search container images

> Finds public Docker Hub container images matching a software name, in Docker Hub search order, with publisher, badge, stars, last update and exact total pulls when Docker Hub publishes them. Can keep only Docker Official Images and Verified Publisher images.

Unofficial. Not affiliated with or endorsed by Docker.

- Page: https://fous.com/methods/hub.docker.com/search-container-images
- Method: `hub.docker.com/search_container_images`, version 1
- Website: hub.docker.com
- Returns: image name, publisher, description, total pulls, stars, badge, last updated date, link
- Effect: read (it gets data and changes nothing)
- Sign-in: none needed
- Cost: 1 credit per completed run (1¢ with pay as you go); failed runs are free
- Verified: Nov 2, 2026

## Inputs

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

## Output

From a run on Oct 31, 2026, shortened. Its input:

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

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

## Run it

From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output:

```bash
curl https://api.fous.com/v1/runs \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"hub.docker.com/search_container_images","input":{"query":"postgres"}}'
```

From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`.

## Ask your agent

- Find me public container images for redis, only official or verified publisher ones, and show pull counts and stars
- Which nginx images on Docker Hub have the most pulls? Give me the top 10 with publisher and last updated date
- I need a trusted image for running Grafana — list up to 5 official or verified options with their badges
- Search Docker for elasticsearch images and return 30 results with descriptions, stars, and links
- what container images exist for mosquitto mqtt broker? include community ones, show when each was last updated

## Input schema

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

## Output schema

```json
{
  "type": "object",
  "required": [
    "images"
  ],
  "properties": {
    "images": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "image_name",
          "publisher",
          "description",
          "total_pulls",
          "stars",
          "badge",
          "last_updated",
          "link"
        ],
        "properties": {
          "link": {
            "type": "string",
            "description": "Docker Hub image page."
          },
          "badge": {
            "enum": [
              "official",
              "verified publisher",
              "sponsored open source",
              "none"
            ],
            "type": "string",
            "description": "Docker Hub badge."
          },
          "stars": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Number of stars."
          },
          "publisher": {
            "type": [
              "string",
              "null"
            ],
            "description": "Publisher shown on Docker Hub."
          },
          "image_name": {
            "type": "string",
            "description": "Container image name."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Short image description."
          },
          "total_pulls": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Exact total pulls, when publicly available."
          },
          "last_updated": {
            "type": [
              "string",
              "null"
            ],
            "format": "date",
            "description": "Last updated date."
          }
        },
        "additionalProperties": false
      },
      "description": "Matching images in Docker Hub search order."
    }
  },
  "additionalProperties": false
}
```

## See more

- [Docker API: Get container image details](https://fous.com/methods/hub.docker.com/get-container-image.md): Gets public Docker Hub image details and the newest tags from an image name or Docker Hub page link. Signature and metadata artifact tags are omitted; size is the reported compressed tag size.
- [npm API: Search packages](https://fous.com/methods/npmjs.com/search-packages.md): Searches the npm registry for JavaScript packages by description or keywords, in npm's search order, and returns each package's latest version, weekly downloads and publish date.
- [crates.io API: Search crates](https://fous.com/methods/crates.io/search-crates.md): Finds Rust crates on crates.io by keywords, sorted by relevance, total downloads, recent downloads, or newest creation.
- [GitHub API: Search repositories](https://fous.com/methods/github.com/search-repositories.md): Finds public GitHub repositories by keywords, with an optional language filter and sort order. Returns up to 100 matches.
- [Wikimedia Commons API: Search free images](https://fous.com/methods/commons.wikimedia.org/search-free-images.md): Finds free-to-use Wikimedia Commons images for a topic in Commons relevance order. Each image comes with its links, creator and licence details.
- [Stack Overflow API: Search questions](https://fous.com/methods/stackoverflow.com/search-questions.md): Finds Stack Overflow programming questions matching plain-language search words, optionally filtered by tag and answer status, with a chosen sort order.
- [Google API: Search Chrome extensions](https://fous.com/methods/chromewebstore.google.com/search-extensions.md): Finds Chrome Web Store extensions by keywords in store order, with each listing's developer, users, rating, rating count, short description and store link. Some listings omit developer, users or ratings.
- [DoorDash API: Search restaurants](https://fous.com/methods/doordash.com/search-restaurants.md): Finds DoorDash restaurants delivering to a street address or ZIP code, optionally for a cuisine or dish, in DoorDash's search order. Fees and times reflect guest offers; the numeric fee is null when DoorDash shows no amount.
- [All Docker methods](https://fous.com/methods/docker.com.md)