# CGC Comic Census - Population Report Data (`lulzasaur/cgc-census-scraper`) Actor

CGC comic population data by title, publisher or series ID. Export issue and variant counts at every grade as JSON, CSV or Excel. Reuse group IDs for recurring census snapshots.

- **URL**: https://apify.com/lulzasaur/cgc-census-scraper.md
- **Developed by:** [lulz bot](https://apify.com/lulzasaur) (community)
- **Categories:** Other
- **Features:** Limited permissions
- **Stats:** 4 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.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?

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 data for comic research

Look up graded comic populations by title, publisher or CGC group ID. Download the issue and variant rows as JSON, CSV or Excel, with counts at every reported grade from 0.5 to 10.0.

### Start with a small title search

```json
{"searchQuery":"Batman","publisher":"DC","category":"comics","maxResults":10,"includeVariants":true}
```

Run the example, open Output, and check the title, issue and variant before expanding the result limit. Publisher filtering narrows title search. Older and newer series can share a name.

### Repeat a series lookup

Each population row now includes `groupID`. Copy the group ID from a matching result into the next run to fetch that series directly. This avoids searching across publishers on every run. Keep `category`, `includeVariants` and the result limit consistent when comparing runs.

Save the input as an Apify task if you need a weekly snapshot. Download each run separately and retain its `scrapedAt` timestamp. Compare rows using `masterID`, `populationID` and variant information. A limited or truncated run is not a complete census. The Actor returns current snapshots; it does not maintain a historical change database.

### Inputs

| Input | What it does |
| --- | --- |
| `searchQuery` | Title search. Add `publisher` to narrow the publishers searched. |
| `publisher` | With no title query, browse the first matching publisher. |
| `groupID` | Fetch a specific series group. Takes precedence over title/publisher input. |
| `masterID` | Fetch raw label-category detail for one issue. Takes precedence over other lookup inputs. This output has a different shape from population rows. |
| `category` | `comics` (default), `magazines`, `pulps`, `concert-posters` or `lobby-cards`. |
| `maxResults` | Maximum population rows returned. Default 100. |
| `includeVariants` | Include variant editions. Default true. |

### Output

The Overview shows issue identity, selected high-grade counts and source IDs. All grades exposes the full grade distribution in the Output table. Download format and field selection are chosen separately in Apify's export controls.

Population rows include title, publisher when available, issue number, issue date, variant, `isBase`, `masterID`, `populationID`, `groupID`, `population_Total`, individual `population_*` grade counts, and `scrapedAt`. CVR, PG and NG are retained as separate source categories. Missing metadata can be blank.

For API use, run `lulzasaur/cgc-census-scraper`, then read the completed run's `defaultDatasetId`. Keep authentication in your Apify client or request header. [Apify's run and dataset guide](https://help.apify.com/en/articles/3224035-run-actor-task-and-retrieve-data-via-api) covers asynchronous runs and exports.

### Cost and coverage

The current result price is $0.01 per row, plus the small Actor Start charge displayed on the Pricing tab. Ten rows are $0.10 in result charges. Set a small result limit and a maximum charge for your first run. The live Pricing tab is authoritative.

Title search gathers up to 100 matching groups, and publisher browsing gathers up to 200 groups. Result limits, upstream changes and category coverage can make a run incomplete. Population counts describe graded supply, not sale prices or guaranteed scarcity.

For public prices and trending issues, see [GoCollect Comic Prices](https://apify.com/lulzasaur/gocollect-scraper). The two sources have different identifiers and coverage; verify the issue, printing and variant before comparing them. Questions or a reproducible issue can be posted in this Actor's Issues tab.

# Actor input Schema

## `searchQuery` (type: `string`):

Search for a comic title (e.g. 'Batman', 'Amazing Spider-Man', 'Walking Dead'). Returns matching titles with full population data.

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

Filter by publisher (e.g. 'Marvel', 'DC Comics', 'Image'). Used with searchQuery or alone to browse.

## `groupID` (type: `integer`):

Direct CGC group ID for a specific title. Get this from a search result. Fetches all issues with grade breakdowns.

## `masterID` (type: `string`):

CGC master ID for a single issue (e.g. '0000186' for Batman #1). Returns detailed label category breakdown.

## `category` (type: `string`):

Category to search in.

## `maxResults` (type: `integer`):

Maximum number of issues to return. Default 100, max 5000.

## `includeVariants` (type: `boolean`):

Include variant covers in results (default: true).

## Actor input object example

```json
{
  "searchQuery": "Batman",
  "category": "comics",
  "maxResults": 100,
  "includeVariants": true
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# 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 = {
    "searchQuery": "Batman"
};

// Run the Actor and wait for it to finish
const run = await client.actor("lulzasaur/cgc-census-scraper").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 = { "searchQuery": "Batman" }

# Run the Actor and wait for it to finish
run = client.actor("lulzasaur/cgc-census-scraper").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 '{
  "searchQuery": "Batman"
}' |
apify call lulzasaur/cgc-census-scraper --silent --output-dataset

```

## MCP server setup

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

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/eQ0Hks8qmR5B1Cah0/builds/QOGzk21ECmj5RqxDw/openapi.json