SkillAgentSearch skills...

Vlrggapi

An Unofficial REST API for vlr.gg, a site for Valorant Pro Esports match results and news.

GenerateConvertImprove

Install / Use

/learn @axsddlr/Vlrggapi
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

vlrggapi

Important Notice

https://vlrggapi.vercel.app/ is currently down because it exceeded free-tier limits. Please self-host the API for now, or wait while I look into another solution.

An Unofficial REST API for vlr.gg, a site for Valorant Esports match and news coverage.

Built by Andre Saddler

Support

If this API helps your projects, you can support ongoing maintenance and development on Ko-fi.

<a href='https://ko-fi.com/J3J1IR40C' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://storage.ko-fi.com/cdn/kofi6.png?v=6' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>

Quick Start

  • Public base URL: https://vlrggapi.vercel.app
  • Local base URL: http://127.0.0.1:3001
  • Interactive docs: /
  • Version info: /version
curl https://vlrggapi.vercel.app/v2/news
curl "https://vlrggapi.vercel.app/v2/match?q=live_score"
curl "http://127.0.0.1:3001/v2/player?id=9&timespan=all"

Highlights

  • V2-first API - consistent response envelopes, validation, and per-endpoint caching
  • Backwards compatibility - original unversioned endpoints are still available
  • Deep match coverage - detailed match, player, team, and event match endpoints
  • Operational guardrails - async HTTP, rate limiting, and bounded expensive scrapes

What's New

Match Details, Player Profiles & Team Profiles

New endpoints provide deep coverage of individual matches, players, and teams:

  • Match details — per-map player stats (K/D/A, ACS, rating), round-by-round data, kill matrix, economy breakdown, head-to-head history
  • Player profiles — agent stats (17 metrics), current/past teams, event placements, total winnings, match history
  • Team profiles — roster with roles/captain status, VLR rating/rank, event placements, total winnings, match history, roster transactions
  • Event matches — full match list for any event with scores and VOD links

V2 API

  • Standardized responses — all V2 endpoints return {"status": "success", "data": {...}}
  • Input validation — invalid parameters return HTTP 400 with clear error messages
  • Per-endpoint caching — in-memory TTL cache reduces load on vlr.gg
  • Async HTTP — scrapers use httpx for non-blocking I/O

API Versions

Both the original and V2 endpoints coexist. The original endpoints (/news, /match, etc.) are preserved unchanged for backwards compatibility. V2 endpoints (/v2/news, /v2/match, etc.) are the recommended API going forward.

| Feature | Original | V2 | |---|---|---| | Response shape | Varies per endpoint | Consistent {"status": "success", "data": {...}} | | Input validation | None | HTTP 400 on invalid params | | Caching | None | Per-endpoint TTL cache |

Interactive Swagger docs are available at /.

Operational Notes

  • Recommended base path - use /v2 for new integrations
  • Current version endpoint - GET /version returns the current API version and default API
  • Rate limit - requests are limited to 600/minute
  • Error handling - V2 returns HTTP 400 for invalid input and propagates upstream failures with HTTP error codes
  • Deployment targets - Vercel for the hosted API, Docker for containerized self-hosting

V2 Endpoint Overview

| Area | Route | Purpose | |---|---|---| | News | GET /v2/news | Latest Valorant esports news | | Matches | GET /v2/match | Upcoming, live, extended upcoming, and results feeds | | Match detail | GET /v2/match/details | Per-map stats, rounds, performance, economy, streams | | Rankings | GET /v2/rankings | Regional team rankings | | Stats | GET /v2/stats | Regional player stats by timespan | | Events | GET /v2/events | Upcoming and completed events | | Event matches | GET /v2/events/matches | Match list for a specific event | | Players | GET /v2/player, GET /v2/player/matches | Player profile and match history | | Teams | GET /v2/team, GET /v2/team/matches, GET /v2/team/transactions | Team profile, match history, roster changes | | Health | GET /v2/health | Runtime and upstream health status |

V2 Endpoints

GET /v2/news

Fetches the latest Valorant esports news.

  • Params: none
  • Cache: 10 minutes
GET /v2/news

{
  "status": "success",
  "data": {
    "status": 200,
    "segments": [
      {
        "title": "Article title",
        "description": "Article summary",
        "date": "April 23, 2024",
        "author": "author_name",
        "url_path": "https://vlr.gg/..."
      }
    ]
  }
}

GET /v2/match

Fetches match data by type.

  • Params:
    • q (required) — upcoming, upcoming_extended, live_score, or results
    • num_pages — pages to scrape (default: 1)
    • from_page / to_page — page range (overrides num_pages)
    • max_retries — retry attempts per page (default: 3)
    • request_delay — delay between requests in seconds (default: 1.0)
    • timeout — request timeout in seconds (default: 30)
  • Cache: 30s (live_score), 5min (upcoming), 1hr (results)
GET /v2/match?q=upcoming

{
  "status": "success",
  "data": {
    "status": 200,
    "segments": [
      {
        "team1": "G2 Esports",
        "team2": "Leviatán",
        "flag1": "flag_us",
        "flag2": "flag_cl",
        "time_until_match": "51m from now",
        "match_series": "Regular Season: Week 3",
        "match_event": "Champions Tour 2024: Americas Stage 1",
        "unix_timestamp": "2024-04-24 21:00:00",
        "match_page": "https://www.vlr.gg/..."
      }
    ]
  }
}

GET /v2/rankings

Fetches team rankings for a region.

  • Params:
  • Cache: 1 hour
GET /v2/rankings?region=na

{
  "status": "success",
  "data": {
    "status": 200,
    "segments": [
      {
        "rank": "1",
        "team": "Sentinels",
        "country": "United States",
        "last_played": "22h ago",
        "record": "7-3",
        "earnings": "$295,500",
        "logo": "//owcdn.net/img/..."
      }
    ]
  }
}

GET /v2/stats

Fetches player statistics for a region and timespan.

  • Params:
    • region (required) — see Region Codes
    • timespan (required) — 30, 60, 90, or all
  • Cache: 30 minutes
GET /v2/stats?region=na&timespan=30

{
  "status": "success",
  "data": {
    "status": 200,
    "segments": [
      {
        "player": "player_name",
        "org": "ORG",
        "rating": "1.18",
        "average_combat_score": "235.2",
        "kill_deaths": "1.19",
        "kill_assists_survived_traded": "72%",
        "average_damage_per_round": "158.4",
        "kills_per_round": "0.81",
        "assists_per_round": "0.29",
        "first_kills_per_round": "0.19",
        "first_deaths_per_round": "0.13",
        "headshot_percentage": "26%",
        "clutch_success_percentage": "28%"
      }
    ]
  }
}

GET /v2/events

Fetches Valorant events.

  • Params:
    • q (optional) — upcoming or completed (omit for both)
    • page (optional) — page number for completed events (default: 1)
  • Cache: 30 minutes
GET /v2/events?q=upcoming

{
  "status": "success",
  "data": {
    "status": 200,
    "segments": [
      {
        "title": "VCT 2025: Pacific Stage 2",
        "status": "ongoing",
        "prize": "$250,000",
        "dates": "Jul 15—Aug 31",
        "region": "kr",
        "url_path": "https://www.vlr.gg/event/..."
      }
    ]
  }
}

GET /v2/match/details

Fetches detailed data for a specific match.

  • Params:
    • match_id (required) — VLR.GG match ID
  • Cache: 5 minutes (30s for live matches)
GET /v2/match/details?match_id=595657

{
  "status": "success",
  "data": {
    "event": { "name": "Champions Tour 2024: Americas Stage 1", "series": "Regular Season: Week 3" },
    "teams": [
      { "name": "Sentinels", "score": 2, "logo": "//owcdn.net/img/..." },
      { "name": "Cloud9", "score": 1, "logo": "//owcdn.net/img/..." }
    ],
    "maps": [
      {
        "map_name": "Ascent",
        "picked_by": "Sentinels",
        "duration": "28:41",
        "score": { "team1": { "total": 13, "ct": 8, "t": 5 }, "team2": { "total": 9, "ct": 4, "t": 5 } },
        "players": [
          {
            "team": "Sentinels",
            "player": "TenZ",
            "agent": "Jett",
            "rating": "1.32",
            "acs": "267",
            "kills": "24",
            "deaths": "15",
            "assists": "3",
            "kast": "77%",
            "adr": "172.3",
            "hs_pct": "32%",
            "fk": "4",
            "fd": "2"
          }
        ]
      }
    ],
    "rounds": [
      { "round_number": 1, "team1_win": true, "team2_win": false, "team1_side": "ct", "team2_side": "t" }
    ],
    "head_to_head": [
      { "event": "VCT Americas", "match": "Sentinels vs Cloud9", "score": "2-1" }
    ],
    "streams": [{ "name": "English", "link": "https://twitch.tv/..." }],
    "performance": {
      "kill_matrix": [{ "player": "TenZ", "kills_against": { "opponent1": 5 } }],
      "advanced_stats": [{ "player": "TenZ", "2k": 3, "3k": 1, "4k": 0, "5k": 0, "clutch_1v1": 1 }]
    },
    "economy": [
      { "team": "Sentinels", "pistol": "50%", "eco": "33%", "semi_buy": "60%", "full_buy": "72%" }
    ]
  }
}

GET /v2/player

Fetches a player profile.

  • Params:
    • id (required) — VLR.GG player ID
    • timespan — 30d, 60d, 90d, or all (default: 90d)
  • Cache: 30 minutes
GET /v2/player?id=9&timespan=all

{
  "status": "success",
  "data": {
    "info": {
      "name": "TenZ",
      "real_name": "Tyson Ngo",
      "avatar": "https://owcdn.net/img/...",
      "country": "Canada",
      "socials": [{ "platform": "twitter", "url": "https://twitter.com/TenZOfficial" }]
    },
    "current_teams":

axsddlr

View profile

View on GitHub
GitHub Stars195
CategoryDevelopment
Updated4d ago
Forks55
axsddlr/vlrggapi

Languages

Python

Security Score

100/100

Audited on Apr 6, 2026

No findings