# CGC Comic Census Population Scraper (`automation-lab/cgc-comic-census-population`) Actor

Export official CGC comic census issue and variant population counts by publisher, series keyword, or group ID for recurring scarcity research.

- **URL**: https://apify.com/automation-lab/cgc-comic-census-population.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.50 / 1,000 item extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## CGC Comic Census Population Scraper

Refresh **CGC comic census** issue and variant populations for scarcity research. Select a comic series by keyword, an exact publisher name, or reusable CGC group IDs. Each saved row includes the issue identity, variant, total population and a map of grade counts from the official CGC Population Report.

### Who is it for?

Built for comic dealers reviewing inventory, collectors comparing graded supply, and researchers building recurring snapshots. This Actor does not return card populations, prices, ownership records or historical census data.

### Why use this Actor?

- Export issue and variant counts without manually copying census tables.
- Reuse `groupId` values in recurring workflows to keep your series selection stable.
- Keep every grade in the same issue row instead of paying separately for grade rows.
- Retain source URLs and collection timestamps for audit and comparison.

This is an independent automation-lab tool, not affiliated with, endorsed by, or certified by CGC. CGC names are used only to identify the data source.

### Getting started

1. Leave the example series keyword as `Amazing Spider-Man` or choose your own title.
2. Set `maxItems` to the number of issue/variant rows you need.
3. Optionally set `publisher` to an exact source name, such as `Marvel Comics`.
4. Run the Actor and inspect the default dataset.
5. Export JSON, CSV or Excel using Apify's dataset tools. Nested grade maps are easiest to preserve in JSON; flatten them downstream for spreadsheet columns.

### Input parameters

At least one of `seriesKeyword`, `publisher`, or `groupIds` is required. Empty input fails clearly; it does not silently scan the entire census.

| Field | Meaning |
| --- | --- |
| `seriesKeyword` | Trimmed, case-insensitive contiguous substring of a series title. The source search index supplies candidates; matching is also enforced locally. |
| `publisher` | Exact publisher name after trimming and case folding, e.g. Marvel Comics. Unknown names return no rows. |
| `groupIds` | 1–100 positive comic research group IDs. Supplied IDs replace discovery, but publisher and title filters still apply. Duplicate IDs are removed in input order. |
| `maxItems` | Global saved-row limit, default 100, range 1–10000. Not a limit per grade or series. Zero is invalid. |
| `maxSeries` | Global matching-series cap, default 10, range 1–100. Applies to discovery and explicit IDs; can stop collection before maxItems. |

Title and publisher filters combine with AND. For example, `Spider-Man` matches `Amazing Spider-Man`, but `Spider Man` does not match the hyphenated text. There is no word-boundary or linguistic matching. Discovery follows source search order; explicit IDs follow your input order.

```json
{"seriesKeyword":"Amazing Spider-Man","maxItems":10,"maxSeries":1}
```

### Refresh a known comic series

For a stable series refresh:

```json
{"groupIds":[40000],"publisher":"Marvel Comics","maxItems":100,"maxSeries":1}
```

### Extracted data

| Field | Description |
| --- | --- |
| `populationId` | Stable source population record identifier. |
| `groupId` | Reusable research-series identifier. |
| `publisher`, `series` | Publisher and comic title from the source. |
| `issueNumber`, `issueDate`, `year` | Issue identity; date remains source text, year may be null. |
| `variant` | Variant name, or an empty string for the base record. |
| `totalPopulation` | Source total for this issue/variant population record. |
| `gradePopulations` | Numeric-grade count map, including zero counts and source special buckets CVR, PG and NG. |
| `sourceModifiedAt` | Source modification timestamp when available; not a historical observation date. |
| `sourceUrl` | Official Population Report link for the record. |
| `scrapedAt` | UTC collection timestamp. |

The Actor does not infer Universal/Signature/Restored label breakdowns. Grade counts are the aggregate fields returned by the source for this population record. Do not interpret total graded as the number of unique surviving copies or currently available inventory.

### Output example

A representative source record, with the grade map shortened here for readability:

```json
{
  "populationId":193428804,
  "groupId":40000,
  "publisher":"Marvel Comics",
  "series":"Amazing Spider-Man",
  "issueNumber":"1",
  "issueDate":"3/63",
  "year":1963,
  "variant":"",
  "totalPopulation":5443,
  "gradePopulations":{"9.4":15,"9.6":5,"9.8":2,"9.9":0,"10.0":0,"CVR":3,"PG":243,"NG":71},
  "sourceModifiedAt":"2026-10-23T05:50:11.71",
  "sourceUrl":"https://www.cgccomics.com/population-report/comics/comics/1/marvel-comics/5304/amazing-spider-man/40000/?populationID=193428804",
  "scrapedAt":"2026-10-24T06:00:00.000Z"
}
```

Live results include every grade field supplied by CGC, not just the example's subset. Counts can change between runs.

### How much does it cost to export CGC comic census populations?

A run has a **$0.005 start event**, plus one `item` event per saved issue/variant row. Grade entries have no separate event charge. Spend tiers follow your qualifying monthly Apify Store spend, not a private per-Actor volume discount.

At the BRONZE tier the rate is **$0.00916 per row**:

| Saved rows | Calculated total including start |
| --- | --- |
| 1 | $0.01416 |
| 10 | $0.0966 |
| 100 | $0.921 |

These examples exclude any additional Apify platform charges under your plan. The pricing panel is authoritative for your active tier. Empty valid searches incur only the start event. Input validation occurs before the start charge. Duplicate/rejected records are not charged. A failed run may retain partial results and their charges; do not treat it as a complete export.

### Limits and reliability

The Actor uses the anonymous JSON service linked by CGC's public frontend. No source login, paid data subscription, browser or residential proxy is required. It visits pages sequentially and retries transient network, HTTP 429 and server failures at most twice after the first attempt. Permanent HTTP errors and malformed responses fail rather than returning misleading empty success.

The 100-series and 10000-row caps are finite collection limits, not promises of complete publisher coverage. Source search indexing and availability can change. The Actor only covers comics, not magazines, pulps, cards, posters or lobby cards. It does not provide historical snapshots, alerts, label enrichment, prices, valuations or certification verification.

### Integrations and recurring research

Schedule this Actor in Apify with stable `groupIds`, then retain each dataset outside the run. Compare records by `populationId` and timestamp in your warehouse to calculate changes between your own snapshots. A source correction or reclassification can change a count; a delta is not necessarily newly graded supply.

Send dataset exports to Google Sheets through your automation workflow, or load JSON into a warehouse. Use Make, Zapier or Apify webhooks to react to completion and fetch the dataset. These downstream workflows are configured separately; the Actor itself does not send alerts or maintain a historical database.

### API usage

Start a run once and retain its run ID:

```bash
curl -X POST "https://api.apify.com/v2/acts/automation-lab~cgc-comic-census-population/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H 'Content-Type: application/json' \
  -d '{"groupIds":[40000],"maxItems":10,"maxSeries":1}'
```

JavaScript with the Apify client:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/cgc-comic-census-population')
  .call({ groupIds: [40000], maxItems: 10, maxSeries: 1 });
const { items } = await client.dataset(run.defaultDatasetId).listItems({ limit: 10 });
console.log(items);
```

Python:

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/cgc-comic-census-population').call(
    run_input={'groupIds': [40000], 'maxItems': 10, 'maxSeries': 1})
print(client.dataset(run['defaultDatasetId']).list_items(limit=10).items)
```

### MCP: Claude Code, Claude Desktop, Cursor and VS Code

Use the Actor-specific hosted endpoint, then discover actual names and input schemas with read-only `tools/list`:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/cgc-comic-census-population"
```

Equivalent HTTP configuration for Claude Desktop, Cursor and VS Code clients that support remote MCP (adapt the outer configuration key for your client):

```json
{"mcpServers":{"apify":{"url":"https://mcp.apify.com?tools=automation-lab/cgc-comic-census-population"}}}
```

Authenticate with your Apify account through your client's supported secure configuration. Never put credentials in prompts. The selected Actor also exposes run/data helpers; the endpoint is not exactly one tool.

Example prompt: “Run CGC Comic Census Population Scraper for group 40000, at most 10 rows, and show issue numbers and 9.8 populations.” Execution requires your authorization and can incur charges.

Start once and retain the run ID and storage IDs. The hosted call can return before completion; IDs are metadata, not rows. Follow that same run with bounded 2/4/8/10-second backoff and a 120-second total deadline. On a client timeout, check the known run rather than restarting. Report pending at the deadline or failure honestly; partial rows are not a complete successful export.

After success, fetch the returned default dataset in pages of 20 rows, explicitly selecting needed fields and offsets. Limit model context to at most 100 source rows and 64 KiB of serialized UTF-8 content, whichever comes first. Enforce bytes host-side before injection, disclose oversized omissions, and report the next source offset when truncated. If your client cannot intercept responses, do not claim a hard byte guarantee. Full exports belong in storage or downstream processing, not model context. No universal token-saving claim is made.

### Legality and data handling

Use the data in accordance with applicable law, source rights and Apify's standard terms. You are responsible for your downstream use; population counts are research inputs, not financial advice. This Actor processes public comic bibliographic and population data, not personal profiles. It does not use AI at runtime or send census data to a model provider.

Datasets and logs remain in your Apify storage subject to your account's retention and deletion controls. The Actor does not keep a separate census database or cross-run cache. Delete runs and storage through Apify when no longer needed.

### Failure diagnostics and retention

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL query strings are removed; reports are retained for 30 days. Apify provides execution/storage; CGC receives source requests; our private diagnostic service receives sanitized failure details. No undisclosed paid supplier is required.

### FAQ and troubleshooting

**Why are there no rows?** Check the exact publisher spelling and title substring. A valid unknown publisher or no-match search returns an empty dataset. Filters also apply to supplied IDs.

**Why fewer rows than maxItems?** You may have reached source exhaustion or `maxSeries`. Increase the appropriate cap within its supported range, or target specific group IDs. No unlimited option is offered.

**Can I compare historical census values?** Only by retaining snapshots you collect yourself. The Actor does not expose an existing historical database.

**Are variants included?** Yes, source population records distinguish variants and each is a separately saved row. Label categories and signer details are not enriched.

**A run failed after saving rows—what should I do?** Inspect the error and keep the partial dataset separate from complete snapshots. Repeated 403s or malformed responses indicate a source change; open an issue rather than assuming the census is empty.

### Related workflows and support

This is a standalone official-comics census tool; no related portfolio Actor is required. Dataset exports work with your existing research stack. For assistance, use this Actor's Apify Issues tab and include a run link and non-sensitive input. Do not include tokens or source account credentials.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/cgc-comic-census-population/changelog.md

# Actor input Schema

## `seriesKeyword` (type: `string`):

Case-insensitive contiguous substring of the series title after trimming input. The source first searches its own index; this title filter is then enforced locally. Combined with publisher using AND. Applies to explicit IDs too.

## `publisher` (type: `string`):

Exact publisher name, case-insensitive after trimming, e.g. Marvel Comics. Combined with the title filter using AND and applied to explicit IDs. An unknown publisher returns no rows.

## `groupIds` (type: `array`):

Optional 1–100 positive CGC comic research group IDs. When supplied, only these series are visited, in input order with duplicates removed; keyword and publisher still filter them. Other collectible types are rejected.

## `maxItems` (type: `integer`):

Global limit on distinct population records saved across all selected series, not per grade or per series. Default 100; 1–10000; zero is invalid. Each row includes all grades. Pagination stops at this cap or source exhaustion.

## `maxSeries` (type: `integer`):

Global cap on matching series visited, including explicit IDs. Default 10; 1–100. Series are visited in source search order or supplied ID order. This cap can stop collection before maxItems; no promise of complete publisher coverage.

## Actor input object example

```json
{
  "seriesKeyword": "Amazing Spider-Man",
  "maxItems": 10,
  "maxSeries": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

Issue and variant population records with all available grade counts.

# 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 = {
    "seriesKeyword": "Amazing Spider-Man",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/cgc-comic-census-population").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 = {
    "seriesKeyword": "Amazing Spider-Man",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/cgc-comic-census-population").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 '{
  "seriesKeyword": "Amazing Spider-Man",
  "maxItems": 10
}' |
apify call automation-lab/cgc-comic-census-population --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/cgc-comic-census-population"
        }
    }
}
```

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/PLGpB9m7eJVZc4kgf/builds/kOMpC43PO70Q0Qfrf/openapi.json