Valorant Esports API Valorant Esports API

API Documentation

Base URL: /api · Version: v1

This is a fan-made, non-commercial hobby project. Educational use only. Be mindful of the source website and scraping ethics; slight delays may occur due to respectful scraping.

Quickstart

curl -s "https://vlrgg.metehansenyer.tech/api/matches?status=completed&count=5" | jq

Endpoints

Endpoint Method Description
/api/news GET Latest news items
/api/matches GET Upcoming/live/completed matches
/api/matches/{match_id} GET Match details
/api/events GET Events list
/api/events/{event_id} GET Event details
/api/player/{player_id} GET Player details
/api/search GET Search teams/players/events
/api/health GET Health check

Parameters

See per-endpoint sections below for full parameter details, defaults, constraints and examples.

Examples

GET /api/matches?status=completed&count=2

[
  {
    "id": "525810",
    "url": "https://www.vlr.gg/525810/leviat-n-academy-vs-9z-team-challengers-2025-latam-south-ace-stage-2-playoffs-ubf",
    "team1_name": "LEVIATÁN Academy",
    "team2_name": "9z Team",
    "score_team1": 2,
    "score_team2": 0,
    "status": "completed",
    "tournament_name": "Challengers 2025: LATAM South ACE Stage 2",
    "has_stats": true,
    "has_vod": false,
    "time": "2025-08-07T22:00:00"
  },
  {
    "id": "511571",
    "url": "https://www.vlr.gg/511571/natus-vincere-vs-karmine-corp-vct-2025-emea-stage-2-w4",
    "team1_name": "Natus Vincere",
    "team2_name": "Karmine Corp",
    "score_team1": 2,
    "score_team2": 0,
    "status": "completed",
    "tournament_name": "VCT 2025: EMEA Stage 2",
    "has_stats": true,
    "has_vod": false,
    "time": "2025-08-07T21:00:00"
  }
]

GET /api/events/2449

{
  "id": "2449",
  "name": "Esports World Cup 2025",
  "url": "https://www.vlr.gg/event/2449",
  "logo_url": "https://owcdn.net/img/6814dc624bb4c.png",
  "start_date": "2025-07-08T00:00:00",
  "end_date": "2025-07-13T00:00:00",
  "prize_pool": "$1,250,000 USD",
  "location": "stc Esports Arena, Riyadh",
  "status": "completed",
  "prize_distribution": [{ "place": "1st", "prize": "$500,000USD", ... }, ...]
  "participating_teams": [{ "id": "1001", "name": "Team Heretics", ... }, ...]
  "stages_urls": [{ "name": "Playoffs", "url": "..." }, ...]
}

Error Codes

  • 400: Invalid parameters — {"detail": "Invalid ..."}
  • 404: Resource not found — {"detail": "... not found"}
  • 429: Too many requests — {"detail": "Rate limit exceeded"}
  • 500: Internal error — {"detail": "Service is currently unavailable: ..."}

FAQ

Data freshness?

On-demand scraping provides up-to-date results; slight delays added for respectful rate limiting.

Caching?

No mandatory server-side cache. Consider client-side caching where appropriate.

Scraping ethics?

Rate limiting (0.5–2.0s random delay), proper User-Agent, public data only. Non-affiliated, educational use.

Detailed Endpoint Reference

/api/news — GET

Name In Type Required Default Allowed Min/Max Description Example
author query string no — — — Filter by author author=CongoBat
country query string no — Turkey Canada Europe etc. — Filter by country/region country=Europe
count query int no 10 — 50 Number of news items to return count=5

/api/news/{news_id} — GET

Name In Type Required Description Example
news_id path string yes News identifier /api/news/510196

/api/matches — GET

Name In Type Required Default Allowed Min/Max Description Example
status query enum no — upcoming ongoing completed — Filter by match status status=completed
event query string no — — — Contains filter on event name event=Changers
count query int no 10 — 50 Number of matches to return count=5

Note: count is applied after filters.

/api/matches/{match_id} — GET

Name In Type Required Description
match_id path string yes Match identifier

/api/events — GET

Name In Type Required Default Allowed Min/Max Description Example
count query int no 10 — 50 Number of events to return count=10
status query string no — ongoing upcoming completed — Filter events by status status=ongoing
region query string no — NA EU AP KR JP BR LATAM OCE MENA — Filter by region region=AP

/api/events/{event_id} — GET

Name In Type Required Description
event_id path string yes Event identifier

/api/events/{event_id}/stages — GET

Name In Type Required Description
event_id path string yes Event identifier

/api/events/{event_id}/matches — GET

Name In Type Required Default Allowed Min/Max Description Example
event_id path string yes — — — Event identifier /api/events/2449/matches
status query string no — completed live upcoming — Filter matches by status status=upcoming
count query int no 10 — 50 Number of matches to return count=5

Note: count is applied after filters.

/api/events/{event_id}/stats — GET

Name In Type Required Description
event_id path string yes Event identifier

/api/player/{player_id} — GET

Name In Type Required Description
player_id path string yes Player identifier

/api/player/matches/{player_id} — GET

Name In Type Required Default Min/Max Description Example
player_id path string yes — — Player identifier /api/player/matches/573
count query int no 10 50 Number of matches to return count=3

/api/health — GET

Health check endpoint returns service status.