Free REST API for Valorant player data: rank & RR history, match history with headshot % / ADR / first kills, stored match stats, leaderboards and webhooks.
Official JavaScript and Python clients included.
Documentation · Examples · OpenAPI · Changelog · Status · Türkçe
- Quick start
- Get an API key
- Endpoints
- Clients (JavaScript, Python)
- Plans and limits
- Response headers
- Errors
- Webhooks
- Rules
- Legal
curl "https://api.ugilabs.com/v1/rank/eu/Name/Tag" \
-H "Authorization: Bearer YOUR_API_KEY"{
"status": 200,
"data": {
"name": "Name",
"tag": "Tag",
"puuid": "6f1d2c3b-…",
"current_data": { "currenttier": 21, "currenttierpatched": "Ascendant 1", "ranking_in_tier": 47, "wins": 31, "games": 58 },
"peak": { "tier": 22, "tier_patched": "Ascendant 2", "source": "win" },
"by_season": [ … ]
}
}JavaScript (Node.js 18+, no dependencies)
npm install github:bnsware/valorant-api-unofficialimport { UgiApi } from 'ugiapi';
const api = new UgiApi({ apiKey: process.env.UGIAPI_KEY });
const { data } = await api.getMatches({ region: 'eu', name: 'Name', tag: 'Tag', mode: 'competitive', size: 5 });
for (const m of data.matches) console.log(m.map_details?.name, m.player.stats.kills, m.player.combat?.headshot_pct);Python (3.8+)
pip install "git+https://github.com/bnsware/valorant-api-unofficial#subdirectory=python"from ugiapi import UgiApi
api = UgiApi("YOUR_API_KEY")
summary = api.get_stored_matches("eu", "Name", "Tag", mode="competitive").data["summary"]
print(summary["win_pct"], summary["kd"], summary["headshot_pct"], summary["adr"])- Open the developer panel: https://api.ugilabs.com/panel/
- Sign in with Discord.
- Create a key. You can restrict it to your server's IP addresses or your website's origins.
Send the key as Authorization: Bearer YOUR_API_KEY (recommended) or X-API-Key: YOUR_API_KEY. ?api_key= also works (useful for Twitch bots), but it ends up in logs.
Never put your key in public code, a browser bundle or a screenshot. If it leaks, regenerate it in the panel.
Base URL: https://api.ugilabs.com · every endpoint is GET · regions: eu, na, ap, kr, br, latam
Every route that takes a Riot ID also has a PUUID version under /v1/by-puuid/….
| Endpoint | What you get |
|---|---|
/v1/account/{name}/{tag} |
PUUID, Riot ID, account level, player card and title |
/v1/rank/{region}/{name}/{tag} |
Current tier and RR, wins and games this act, all-time peak and a per-act summary |
/v1/rank-history/{region}/{name}/{tag} |
Last 1–10 competitive games: RR earned, tier and RR before/after, performance bonus, RR refunds, derank protection |
/v1/matches/{region}/{name}/{tag} |
Recent matches with K/D/A, headshot %, ADR, first kills/deaths, economy. Filter with ?mode=, page with ?start= |
/v1/stored-matches/{region}/{name}/{tag} |
Long-term match list from our match store with filters (mode, map, agent, act), pagination and a summary (win %, K/D, HS %, ADR, ACS). No Riot query cost |
/v1/match/{matchId} |
Full match: every player with stats and combat numbers, teams, rounds with first kills |
/v1/leaderboard/{region} |
Ranked leaderboard (act, page, search by name) |
/v1/content |
Agents, maps, acts, game modes, player cards and titles (en-US, tr-TR) |
/v1/status/{region} |
Riot service status (no key needed) |
mode values: competitive, unrated, swiftplay, spikerush, deathmatch, teamdeathmatch, premier, escalation, replication, snowball, newmap, custom.
Full parameter and field reference: https://api.ugilabs.com/docs/ · machine-readable: openapi.json (OpenAPI 3.1, import it into Postman or generate your own client).
| Language | Folder | Install |
|---|---|---|
| JavaScript / TypeScript | js/ |
npm install github:bnsware/valorant-api-unofficial |
| Python | python/ |
pip install "git+https://github.com/bnsware/valorant-api-unofficial#subdirectory=python" |
Both clients:
- cover every endpoint, with types (TypeScript definitions included)
- return
{ data, meta }:metacarries cache status, remaining requests, Riot query budget and what the call cost - retry
429/503automatically usingRetry-After(never for daily quota errors) - support ETags (
304 Not Modified) - raise a typed error with a stable
codeand therequest_id - include a webhook signature verifier
Examples: Discord bot · player stats · webhook server · Python Discord bot · Python player stats · Flask webhook
Using another language? Generate a client from openapi.json with OpenAPI Generator.
| Basic | Advanced | Premium | |
|---|---|---|---|
Matches per request (/v1/matches) |
5 | 10 | 20 |
| Stored matches per page | 20 | 50 | 100 |
| Webhooks | – | ✓ | ✓ |
?force=true (skip cache) |
– | – | ✓ |
Every key has a per-minute and a daily request limit, plus a Riot query budget: only lookups that are not already cached count against the budget. Data is served from a shared cache; how fresh live data is (rank, rank history, match list) depends on your plan. Current numbers: https://api.ugilabs.com/docs/#rate-limiting.
| Header | Meaning |
|---|---|
X-Cache, Age, X-Cache-TTL |
Cache hit or miss, age of the data, seconds it still counts as fresh for your plan |
ETag / If-None-Match |
Send the ETag back to get 304 Not Modified |
X-RateLimit-Limit / -Remaining / -Reset |
Per-minute request limit (-Daily-* for the daily one) |
X-RateLimit-Upstream-* |
Riot query budget (minute and day) |
X-Upstream-Cost |
Riot queries this request spent (0 = served from cache) |
RateLimit-Policy, RateLimit |
The same limits in the IETF format: windows "minute", "day", "riot-minute", "riot-day" |
Retry-After |
On 429 and 503: seconds to wait |
X-Request-Id |
Include it when you ask for support |
{ "status": 404, "error": "Player not found", "code": "player_not_found", "request_id": "ab85df05829198f2" }Branch on code, never on the message.
| HTTP | Codes |
|---|---|
| 400 | bad_request, missing_parameters, invalid_region, invalid_name, invalid_tag, invalid_puuid, invalid_match_id, invalid_act, invalid_locale, invalid_mode, invalid_map, invalid_agent, invalid_parameter, force_not_allowed |
| 401 | api_key_missing, api_key_invalid |
| 403 | ip_not_allowed, origin_not_allowed |
| 404 | player_not_found, not_found, endpoint_not_found |
| 429 | rate_limited, daily_quota_exceeded, user_daily_quota_exceeded, upstream_budget_exceeded — wait for Retry-After |
| 503 | service_unavailable, maintenance — wait for Retry-After |
Instead of polling, let us call you. Add tracked players in the panel (https://api.ugilabs.com/panel/webhooks) and you get a signed POST on:
match.new— the player finished a match (with K/D/A, agent, map and result)rank.changed— tier or RR changedaccount.level_changedwebhook.test
Verify every delivery: X-UGI-Signature: sha256=HMAC_SHA256(secret, X-UGI-Timestamp + "." + raw_body). Reject timestamps older than 5 minutes, answer 2xx within 5 seconds and skip X-UGI-Delivery ids you have already processed. Both clients ship a verifier:
import { verifyWebhook } from 'ugiapi';
const ok = await verifyWebhook({ secret, body: rawBody, signature: req.headers['x-ugi-signature'], timestamp: req.headers['x-ugi-timestamp'] });By using ugiAPI you agree to the Terms of Service. In short:
- Do not share your API key with third parties.
- Do not try to get around the rate and quota limits of your key.
- Do not use the service for anything unlawful.
- Do not try to reverse-engineer or abuse the system.
- Do not use the data to harass, stalk or harm other players.
ugiAPI isn't endorsed by Riot Games and doesn't reflect the views or opinions of Riot Games or anyone officially involved in producing or managing Riot Games properties. Riot Games, Valorant and all associated properties are trademarks or registered trademarks of Riot Games, Inc.
The client code in this repository is released under the MIT License. The API itself is provided "as is", without guarantees of uptime or data accuracy.
Images of agents, maps and ranks come from valorant-api.com.