# Docker Image Update Scraper (`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:** [naoki anzai](https://apify.com/taroyamada) (community)
- **Categories:** Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 to proactively secure your infrastructure and automate your container supply chain. This Docker Image Update Monitor provides deep image tracking by directly querying the stable Docker Hub v2 API, completely eliminating the sluggishness of headless browser scraping. Security teams and system administrators depend on this fast, reliable monitor to schedule daily or weekly recurring checks on essential base images like nginx or redis. By maintaining a watchlist of critical URLs or search queries, you ensure your team is instantly aware of tag drift, new container versions, or potential vulnerability windows. You no longer have to manually check web pages to see if an important base image has been patched. The monitor automatically extracts and logs crucial data fields such as exact tag timestamps, storage sizes, full repository descriptions, pull signals, and star counts. Running this extraction on a strict schedule allows infrastructure and DevSecOps teams to pipe container update alerts straight into Slack, Jira, or native CI/CD pipelines. Track exactly what changes across your targeted repositories over time, keep your base layers secure, and streamline your entire dependency management workflow with precision.

### 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`

### Input Examples

#### Example: Single-target audit

```json
{
  "targets": [
    "example-target-1"
  ],
  "maxResultsPerTarget": 30
}
```

#### Example: Bulk portfolio

```json
{
  "targets": [
    "target-1",
    "target-2",
    "target-3"
  ],
  "maxResultsPerTarget": 50,
  "snapshotKey": "dockerhub-image-intelligence-state"
}
```

#### Example: Recurring delta watch

```json
{
  "targets": [
    "target-1"
  ],
  "snapshotKey": "dockerhub-image-intelligence-state",
  "emitChangedOnly": true
}
```

### 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(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,taroyamada/dockerhub-image-intelligence"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/OniNuUD5n8XqqiQ93/builds/D43WzfApiVeMcVENv/openapi.json