Creators

Get velocity data for a specific YouTube channel, search YouTube channels, and list your rising creators.

Get Channel Velocity

GET /api/creators/youtube/{channelId}

Get growth rate, opportunity score, and alert level for a specific channel. Accepts channel ID, handle, or YouTube URL.

Path Parameters

Parameter	Description
channelId	Channel ID (UCX6O...), handle (@MrBeast), or YouTube URL (https://youtube.com/@MrBeast)

Response

{
  "status": "ok",
  "creator": {
    "channel_id": "UCX6OQ3DkcsbYNE6H8uQQuVA",
    "title": "MrBeast",
    "handle": "@mrbeast",
    "avatar": "https://yt3.ggpht.com/...",
    "current_subscribers": 509000000,
    "total_views": 134728259802,
    "video_count": 994,
    "growth_rate_7d": 2.5,
    "growth_rate_30d": 8.3,
    "opportunity_score": 72,
    "alert_level": "RISING",
    "snapshot_count": 15
  }
}

Fields

Field	Description
growth_rate_7d	Subscriber growth rate over last 7 days (%). 0 if no snapshot history.
growth_rate_30d	Subscriber growth rate over last 30 days (%). 0 if no snapshot history.
opportunity_score	0-100 score based on velocity, acceleration, and data confidence. Higher = faster growth.
alert_level	HIGH_GROWTH (75+), RISING (50+), WATCH (25+), STABLE (<25)
snapshot_count	Number of daily snapshots we have. More = more reliable scores.

Understanding the Scores

• opportunity_score 0: No snapshot history yet. The channel is tracked but we haven't collected enough data points to calculate velocity.
• opportunity_score 25-49 (WATCH): Some growth signals detected. Channel is growing but not dramatically.
• opportunity_score 50-74 (RISING): Clear growth momentum. Channel is gaining subscribers at an above-average rate.
• opportunity_score 75+ (HIGH_GROWTH): Explosive growth. Channel is growing very fast — good time to reach out.

When to Use This

Use this endpoint to validate a specific creator you found via discover or search. It gives you the real velocity data (if we have snapshots) instead of heuristic estimates.

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/youtube/@IndigoGaming"

You can also use a channel ID or YouTube URL:

# By channel ID
curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/youtube/UCX6OQ3DkcsbYNE6H8uQQuVA"

# By YouTube URL
curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/youtube/https://youtube.com/@MrBeast"

---

Search Channels

GET /api/creators/search

Raw YouTube channel search by keyword. Returns up to 50 results with channel stats (subscribers, views, videos).

Query Parameters

Parameter	Required	Default	Description
q	Yes	—	Search query (e.g. "fitness", "tech reviews", "cooking")
offset	No	0	Number of results to skip
limit	No	20	Max results (1-100)

Response

{
  "status": "ok",
  "query": "fitness",
  "count": 10,
  "pagination": {
    "total": 50,
    "offset": 0,
    "limit": 20,
    "has_more": true
  },
  "results": [
    {
      "channel_id": "UCr_k4bDFn0lPp8EN7Es1GYA",
      "title": "Petrof Fitness (PetrofFitness)",
      "description": "Passion | Skill | Knowledge 20 Online Personal Trainer.",
      "thumbnail": "https://yt3.ggpht.com/...",
      "current_subscribers": 25900,
      "total_views": 2594341,
      "video_count": 267
    }
  ]
}

When to Use This

Use this when you want to search for channels by keyword without any scoring or ranking. This is a raw YouTube search — you get whatever YouTube returns for that query.

For ranked results with growth scoring, use /api/discover instead.

Example

# Search for fitness channels
curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/search?q=fitness&limit=5"

# Paginate through results
curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/search?q=tech&limit=10&offset=10"

---

List Rising Creators

GET /api/creators/rising

List YOUR tracked creators ranked by opportunity score. Only returns creators tracked by your API key.

If no snapshot history exists yet (newly tracked creators), live stats are fetched from YouTube automatically.

Query Parameters

Parameter	Default	Description
alert	—	Filter by alert level: HIGH_GROWTH, RISING, WATCH, STABLE
niche	—	Filter by niche (e.g. gaming, fitness, finance)
min_score	0	Minimum opportunity score
offset	0	Number of results to skip
limit	20	Max results (1-100)

Response

{
  "status": "ok",
  "pagination": {
    "total": 2,
    "offset": 0,
    "limit": 20,
    "has_more": false
  },
  "creators": [
    {
      "channel_id": "UCEPWaN-XiZqEQAPiwvBa3ng",
      "title": "Tae Kim - Financial Tortoise",
      "handle": "@taekimfinancialtortoise",
      "avatar_url": "https://...",
      "niche": "finance",
      "current_subscribers": 344000,
      "total_views": 29460278,
      "video_count": 455,
      "growth_rate_7d": 0,
      "growth_rate_30d": 0,
      "opportunity_score": 0,
      "alert_level": "STABLE",
      "snapshot_count": 0
    }
  ]
}

When to Use This

Use this to check on creators you're actively tracking. The opportunity_score and growth_rate fields will be 0 until cron snapshots build up (takes 2+ days).

Filtering

Filter by niche to see creators in a specific category:

curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/rising?niche=gaming"

Filter by alert level to see only creators at a specific growth stage:

curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/rising?alert=RISING"

Filter by minimum score:

curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/rising?min_score=50"

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://beta.pushapi.xyz/api/creators/rising?niche=fitness&alert=RISING&limit=10"