Viewstats APIviewstats.com ↗
Search YouTube channels, fetch subscriber/view stats, and pull top channel leaderboards via the Viewstats API. 3 endpoints, JSON responses.
What is the Viewstats API?
The Viewstats API exposes three endpoints for querying YouTube channel analytics and leaderboard data tracked by Viewstats. Use search_channels to find channels by name or handle, get_channel_stats to retrieve subscriber counts, view totals, verification status, and global/country/category rankings for a specific channel, or get_top_channels to pull a ranked leaderboard of up to 150 channels sorted by subscribers or views over a configurable time interval.
curl -X GET 'https://api.parse.bot/scraper/466820c3-e12c-426d-954d-acb9bc2f7456/search_channels?query=MrBeast' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace viewstats-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Viewstats SDK — YouTube channel analytics and rankings."""
from parse_apis.viewstats_api import Viewstats, Sort, Interval, ChannelNotFound
client = Viewstats()
# Search for channels by name — limit caps total items returned.
for ch in client.channels.search(query="MrBeast", limit=3):
print(ch.display_name, ch.handle, ch.subscriber_count)
# Drill into full detail for one search result.
summary = client.channels.search(query="PewDiePie", limit=1).first()
if summary:
detail = summary.details()
print(detail.display_name, detail.verified, detail.global_subscribers_ranking)
# Get a channel directly by handle.
channel = client.channels.get(handle="MrBeast")
print(channel.display_name, channel.subscriber_count, channel.country)
# Browse the weekly top channels leaderboard sorted by subscribers.
for ranked in client.channels.top(sort_by=Sort.SUBS, interval=Interval.WEEKLY, limit=5):
print(ranked.rank, ranked.channel.display_name, ranked.subscriber_count_delta)
# Typed error handling for a missing channel.
try:
client.channels.get(handle="this_handle_does_not_exist_xyz")
except ChannelNotFound as exc:
print(f"Channel not found: {exc.handle}")
print("exercised: channels.search / summary.details / channels.get / channels.top / ChannelNotFound")
Full-text search across YouTube channels tracked by Viewstats. Returns up to 10 matching channels with subscriber count, view count, and handle. Matches against channel name and handle.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword matching channel name or handle |
{
"type": "object",
"fields": {
"channels": "array of channel objects with id, display_name, handle, avatar_url, country, subscriber_count, view_count, video_count",
"total_count": "integer total number of matching channels"
}
}About the Viewstats API
Searching and Identifying Channels
The search_channels endpoint accepts a query string and returns up to 10 matching YouTube channels with their id, display_name, handle, avatar_url, country, subscriber_count, view_count, and video_count. The total_count field tells you how many channels matched in total, even when only 10 are returned. Matching runs against both channel names and handles, making it useful for resolving ambiguous creator identities.
Channel-Level Statistics
get_channel_stats takes a channel handle — with or without the leading @ symbol — and returns the full stats profile for that channel. Response fields include subscriber_count, view_count, video_count, verified boolean, avatar_url, banner_url, country (two-letter code), and the YouTube id. This endpoint is the right choice when you already know which channel you want and need authoritative counts.
Leaderboard and Ranking Data
get_top_channels returns a ranked list of up to 150 channels. Each entry in the channels array contains a rank, subscriber_ranking, and subscriber_count_delta showing growth over the selected interval, alongside a nested channel object with core identity and count fields. The sort_by parameter controls whether ranking is by subscribers or views, and interval scopes the delta calculations to the desired time window. Both parameters are optional and fall back to defaults when omitted.
The Viewstats API is a managed, monitored endpoint for viewstats.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when viewstats.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official viewstats.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track subscriber growth deltas for top YouTube creators over weekly or monthly intervals using
get_top_channels. - Resolve a creator's YouTube channel ID from their handle for use in downstream video or analytics pipelines via
get_channel_stats. - Build a channel discovery tool that surfaces channels by keyword using
search_channelswith name or handle queries. - Compare global, country, and category rankings for a set of channels using the ranking fields from
get_channel_stats. - Monitor whether a channel has achieved YouTube verification status by checking the
verifiedfield returned byget_channel_stats. - Generate leaderboard snapshots sorted by total views or subscriber count for a specific time interval using
get_top_channels. - Enrich a creator database with avatar URLs, banner images, and country codes pulled from
get_channel_stats.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Viewstats have an official developer API?+
What ranking data does `get_channel_stats` return beyond raw counts?+
get_channel_stats returns global rank, country rank, and category rank for the channel alongside the core metrics. These fields reflect the channel's standing within its region and content category as tracked by Viewstats, not just raw subscriber or view totals.Does the API return historical time-series data for individual channels?+
get_channel_stats returns current point-in-time counts, and get_top_channels provides growth deltas over a selectable interval but not a full historical series per channel. You can fork this API on Parse and revise it to add a historical stats endpoint if Viewstats exposes that data.