# 🛡️ Docker Image Update Monitor (`taroyamada/dockerhub-image-intelligence`) Actor

Track public container repositories on a strict schedule to instantly detect tag drift, newly published versions, and storage size changes.

- **URL**: https://apify.com/taroyamada/dockerhub-image-intelligence.md
- **Developed by:** [太郎 山田](https://apify.com/taroyamada) (community)
- **Categories:** Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $9.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Docker Hub Image Intelligence API | Tags, Pulls & Search

Monitor public Docker Hub repositories and extract critical container updates automatically without the overhead of a headless browser. This tool provides deep image intelligence by leveraging the stable v2 API to scrape pull signals, star counts, and detailed repository metadata directly from the source. Security teams and system administrators rely on this fast, reliable monitor to schedule recurring checks on essential base images like nginx or redis, ensuring they are instantly aware of tag drift or newly published vulnerabilities.

Instead of manually refreshing web pages to check if a new container version is out, you can run this tool on a daily or weekly schedule to track exactly what changes across your targeted repositories. Set up a watchlist of URLs or search queries, and let the scraper extract the latest details seamlessly. The monitor reliably captures crucial data fields including full descriptions, recent tag timestamps, storage sizes, and category assignments.

By pulling this data regularly, infrastructure teams can integrate these tracking results straight into alerting tools or CI/CD pipelines. Whenever you run the task, it captures a precise snapshot of the repository state. This makes it incredibly easy to spot unexpected changes in image tags, monitor repository health, or catch sudden spikes in pull counts that might indicate wider adoption or an urgent patch release.

### Store Quickstart

- Start with 2–5 repositories such as `library/nginx` or `redis`.
- Keep `maxTagsPerRepo` around 20–50 on the first run so tag enrichment stays cheap and fast.
- Use `searchTerms` only when you want discovery; skip them when you already know the repositories you care about.
- After the first useful run, move to the recurring watchlist template for repeat base-image checks, then use the webhook handoff template for tag-drift alerts.

### V1 behavior

- Direct repository inputs such as `library/nginx` or bare names such as `nginx` (normalized to `library/nginx`)
- Optional `searchTerms` via the public Docker Hub search endpoint
- Live repository metadata: description, `full_description`, pulls, stars, repository type, visibility, timestamps, categories when Docker Hub exposes them, and repository-level storage size when Docker Hub exposes it
- Live tag pagination capped by `maxTagsPerRepo`, with up to 100 tags fetched per API page
- Per-tag OS / architecture platform normalization
- Honest repository and search statuses: `ok`, `not_found`, `rate_limited`, `error`

### Out of scope

- Docker Scout
- CVEs / vulnerability scanning
- Private repository intelligence beyond explicit public-access warnings

### Use Cases

| Who | Why |
|---|---|
| **DevOps teams** | Review base image freshness, pull signals, and tag sprawl before standardizing images |
| **Platform engineers** | Compare competing public repositories with one normalized schema |
| **Security teams** | Inventory public repos and tags before deeper image scanning |
| **Analysts** | Track vendor or ecosystem container footprints from public metadata |

### Input

Provide at least one of:

- `repositories`: exact repository slugs to fetch
- `searchTerms`: public Docker Hub search queries

Key options:

- `includeTags` (default `true`)
- `maxTagsPerRepo` (default `100`, max `500`)
- `maxSearchResults` (default `25`, max `250`)
- `delivery`: `dataset` or `webhook`
- `dryRun`

### Output

- `meta`: run summary, scope note, and explicit warnings
- `searches`: normalized search responses and status per query
- `repositories`: normalized repository records with `tags` and `tagSummary`

When Docker Hub omits fields such as categories or repository storage size, the actor returns `null` / `[]` and records an explicit warning instead of silently inventing values.

#### Output Example

```json
{
  "repository": "library/nginx",
  "status": "ok",
  "description": "Official build of Nginx.",
  "pullCount": 456,
  "starCount": 123,
  "tagSummary": { "total": 2, "truncated": true },
  "tags": [
    {
      "name": "1.27",
      "lastPulledAt": "2025-01-04T00:00:00.000Z",
      "platforms": [{ "os": "linux", "architecture": "amd64" }]
    }
  ],
  "warnings": []
}
````

### Local run

```bash
npm test
npm start
```

`npm start` reads `input.json` locally and writes `output/result.json`.

### Related Actors

Pair this actor with other flagship intelligence APIs in the same portfolio:

- [NPM Package Intelligence API](https://apify.com/taroyamada/npm-package-intelligence) — audit JavaScript packages that feed the applications inside your images.
- [PyPI Package Intelligence API](https://apify.com/taroyamada/pypi-package-intelligence) — profile Python dependencies alongside public container repositories.
- [Shopify Store Intelligence API](https://apify.com/taroyamada/shopify-store-intelligence) — combine storefront research with infrastructure-facing image intelligence.

### Pricing & Cost Control

Apify Store pricing is usage-based, so cost mainly follows how many repositories and tags you inspect. Check the Store pricing card for the current per-event rates.

- Keep `maxTagsPerRepo` and `maxSearchResults` low for exploratory runs.
- Set `includeTags` to `false` when repository-level metadata is enough.
- Use `dryRun: true` before larger repo watchlists or webhook delivery.
- Prefer dataset delivery while you validate which tag fields matter downstream.

### ⭐ Was this helpful?

If this actor saved you time, please [**leave a ★ rating**](https://apify.com/taroyamada/dockerhub-image-intelligence/reviews) on Apify Store. It takes 10 seconds, helps other developers discover it, and keeps updates free.

Bug report or feature request? Open an issue on the [Issues tab](https://apify.com/taroyamada/dockerhub-image-intelligence/issues) of this actor.

# Actor input Schema

## `repositories` (type: `array`):

Docker Hub repository slugs to fetch directly (e.g. 'library/nginx', 'ubuntu', 'myorg/myimage'). Bare names such as 'nginx' are normalized to 'library/nginx'.

## `searchTerms` (type: `array`):

Optional search terms for the public Docker Hub repository search API. Matched repositories are normalized and merged with direct repository inputs.

## `includeTags` (type: `boolean`):

When true, fetches the tag list for each repository (up to maxTagsPerRepo tags).

## `maxTagsPerRepo` (type: `integer`):

Maximum number of tags to return per repository. Docker Hub returns up to 100 tags per page; the actor paginates until this limit is reached.

## `maxSearchResults` (type: `integer`):

Maximum number of repositories to return per search term. Search pagination continues until this cap is reached.

## `delivery` (type: `string`):

Where to send results: dataset or webhook.

## `webhookUrl` (type: `string`):

Webhook URL to POST results to when delivery=webhook.

## `dryRun` (type: `boolean`):

Run without saving results to the dataset.

## Actor input object example

```json
{
  "repositories": [
    "library/nginx"
  ],
  "searchTerms": [],
  "includeTags": true,
  "maxTagsPerRepo": 100,
  "maxSearchResults": 25,
  "delivery": "dataset",
  "dryRun": false
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "repositories": [
        "library/nginx"
    ],
    "searchTerms": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("taroyamada/dockerhub-image-intelligence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "repositories": ["library/nginx"],
    "searchTerms": [],
}

# Run the Actor and wait for it to finish
run = client.actor("taroyamada/dockerhub-image-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "repositories": [
    "library/nginx"
  ],
  "searchTerms": []
}' |
apify call taroyamada/dockerhub-image-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=taroyamada/dockerhub-image-intelligence",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "🛡️ Docker Image Update Monitor",
        "description": "Track public container repositories on a strict schedule to instantly detect tag drift, newly published versions, and storage size changes.",
        "version": "0.1",
        "x-build-id": "KYN7HnqBjSFQzvvEm"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/taroyamada~dockerhub-image-intelligence/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-taroyamada-dockerhub-image-intelligence",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/taroyamada~dockerhub-image-intelligence/runs": {
            "post": {
                "operationId": "runs-sync-taroyamada-dockerhub-image-intelligence",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/taroyamada~dockerhub-image-intelligence/run-sync": {
            "post": {
                "operationId": "run-sync-taroyamada-dockerhub-image-intelligence",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "repositories": {
                        "title": "Repositories",
                        "type": "array",
                        "description": "Docker Hub repository slugs to fetch directly (e.g. 'library/nginx', 'ubuntu', 'myorg/myimage'). Bare names such as 'nginx' are normalized to 'library/nginx'.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "searchTerms": {
                        "title": "Search Terms",
                        "type": "array",
                        "description": "Optional search terms for the public Docker Hub repository search API. Matched repositories are normalized and merged with direct repository inputs.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "includeTags": {
                        "title": "Include Tags",
                        "type": "boolean",
                        "description": "When true, fetches the tag list for each repository (up to maxTagsPerRepo tags).",
                        "default": true
                    },
                    "maxTagsPerRepo": {
                        "title": "Max Tags per Repository",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Maximum number of tags to return per repository. Docker Hub returns up to 100 tags per page; the actor paginates until this limit is reached.",
                        "default": 100
                    },
                    "maxSearchResults": {
                        "title": "Max Search Results per Term",
                        "minimum": 1,
                        "maximum": 250,
                        "type": "integer",
                        "description": "Maximum number of repositories to return per search term. Search pagination continues until this cap is reached.",
                        "default": 25
                    },
                    "delivery": {
                        "title": "Delivery",
                        "enum": [
                            "dataset",
                            "webhook"
                        ],
                        "type": "string",
                        "description": "Where to send results: dataset or webhook.",
                        "default": "dataset"
                    },
                    "webhookUrl": {
                        "title": "Webhook URL",
                        "type": "string",
                        "description": "Webhook URL to POST results to when delivery=webhook."
                    },
                    "dryRun": {
                        "title": "Dry Run",
                        "type": "boolean",
                        "description": "Run without saving results to the dataset.",
                        "default": false
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```