Skip to content

Support / FAQ

Frequently
asked.

Everything you need to know about the VLRdevAPI Python SDK, from installation and rate limits to typed errors, pagination, and production use.

FAQ index
Questions
44
Sections
07
Python
3.11+
API key
Not required
Still stuck? Open an issue.
01

Getting Started

6 questions
What is VLRdevAPI?
VLRdevAPI is a Python SDK that provides a type-safe interface for fetching Valorant esports data from VLR.gg. It handles scraping, parsing, and data normalization so you can focus on building your application. See the documentation for full details.
Do I need an API key?
No. VLRdevAPI works without any API key or authentication. Just uv add vlrdevapi or pip install vlrdevapi and start making calls.
What Python version is required?
Python 3.11 or later. The library uses modern Python features including type hints and Pydantic models.
How do I install VLRdevAPI?
Install with uv (recommended): uv add vlrdevapi. Or with pip: pip install vlrdevapi. See the installation guide for more options.
Can I try VLRdevAPI without installing it?
You can experiment with VLRdevAPI in your browser using a Python notebook on Google Colab or similar platforms. Just run pip install vlrdevapi in a notebook cell and start exploring.
Does VLRdevAPI work on Windows, macOS, and Linux?
Yes. VLRdevAPI is pure Python and works on all major operating systems. It has been tested on Windows 10/11, macOS, and Ubuntu Linux.
02

Usage

7 questions
Does VLRdevAPI have rate limits?
Yes. The built-in client respects a default rate limit to avoid overloading VLR.gg. You can configure the rate limit and retry behavior when creating a VLRClient instance. See the API reference for configuration options.
Is VLRdevAPI synchronous or asynchronous?
Synchronous. Every method is a blocking call, so wrap independent fetches in a thread pool, or use asyncio.to_thread from an async framework such as FastAPI. Multi-stage endpoints already parallelize their stage pages internally.
What data can I access?
VLRdevAPI covers six namespaces: matches (upcoming, live, completed), team (info, roster, stats, placements), player (profiles, agents, teams, match history), event (stages, standings, teams, matches), series (VODs, player stats, economy data, rounds), and news (listings and full articles). Browse the full API reference for details.
Is VLRdevAPI production-ready?
It ships with error handling, retry logic, rate limiting, and typed exceptions for reliable operation. See the getting started guide for best practices.
How do I handle errors?
VLRdevAPI provides a typed exception hierarchy: NotFoundError, RateLimitError, RequestError, and more. Import from vlrdevapi.exceptions and handle them with standard try/except blocks.
How do I paginate through results?
List endpoints return paginated responses containing a list of entries and a has_next_page boolean. Pass page=2 to request subsequent pages, or pass return_all=True to automatically fetch and combine all pages.
Can I filter data by date or region?
Some endpoints support optional parameters like date ranges and region filters. Check the API reference for each endpoint to see available query parameters.
03

Model Context Protocol (MCP) & AI

6 questions
What is the VLRdevAPI MCP server?
The Model Context Protocol (MCP) server allows AI assistants (Claude Desktop, Cursor, Claude Code, Windsurf, OpenCode, DeepSeek, Codex, Grok) to directly query live Valorant esports data from VLR.gg. It communicates over standard stdio and provides 40 tools covering matches, player stats, team rosters, tournament brackets, and round-by-round replay timelines. See the MCP setup guide.
How do I connect VLRdevAPI to Claude Desktop or Cursor?
No complex installation is needed. Add a simple command configuration using uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp to your claude_desktop_config.json or .cursor/mcp.json. For Claude Code CLI, run claude mcp add vlrdevapi -- uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp.
Do I need to host an MCP server or run a background daemon?
No. The server executes on-demand over stdio via uvx. Your AI client launches the process when a session begins and shuts it down when you finish. There are no servers to maintain, no ports to open, and no API keys required.
Can I use VLRdevAPI with autonomous AI agents (OpenCode, DeepSeek, Codex, Grok)?
Yes. Any agent framework or LLM environment that supports MCP or external CLI tool execution can invoke the server. We provide a ready-to-paste agent prompt on our MCP page.
What high-level composite tools are available for AI models?
To minimize LLM token usage and prevent multiple roundtrips, VLRdevAPI provides 9 high-level composite tools: get_match_full_context, get_team_overview, compare_teams, get_player_career_summary, get_h2h_matchup, get_tournament_dossier, get_live_and_upcoming_schedule, get_news_digest, and series_map_summary. Full schemas are documented in the MCP reference.
Can I export scraped data into Pandas, Polars, or Excel spreadsheets?
Yes! All models inherit from ExportableModel, allowing instant export with .to_df(), .to_polars(), .to_csv(), .to_parquet(), .to_excel(), .to_json(), and .to_markdown().
04

Technical

7 questions
Does VLRdevAPI have any dependencies?
The core dependency is Pydantic v2 for data modeling and validation. HTTP requests go through httpx.
How does VLRdevAPI compare to web scraping?
VLRdevAPI abstracts away HTML parsing, rate limiting, and data normalization. It is faster, more reliable, and requires less code than scraping VLR.gg directly. Read the comparison post for a detailed breakdown.
Can I use VLRdevAPI in a Jupyter notebook?
Yes. Module-level access works directly in notebooks. Use import vlrdevapi and call methods synchronously.
How do I configure the client?
Pass options to the constructor: VLRClient(timeout=30, max_retries=5, requests_per_second=2). Check the API reference for all options.
Does VLRdevAPI cache responses?
Within a single call, yes. Multi-stage endpoints reuse the pages they have already parsed instead of fetching them twice, so a request that spans several pages still makes one request per page.
What happens if VLR.gg is down?
The client raises a RequestError when it cannot reach VLR.gg. Configure retry logic to automatically retry on transient failures. Check the changelog for any known issues.
Can I contribute to the library itself?
Absolutely. The library is open source on GitHub. Check the development setup guide in the docs to get started with local development.
05

Troubleshooting

6 questions
I get an import error when trying to use VLRdevAPI
Make sure you installed the package: pip list | findstr vlrdevapi (Windows) or pip list | grep vlrdevapi (macOS/Linux). If missing, run uv add vlrdevapi or pip install --upgrade vlrdevapi. Check that you are using Python 3.11+.
My API calls return no data
Check that the parameters you are passing are valid. For example, some endpoints require specific date formats or team IDs. If you are filtering by region or tier, verify that the filter values match the expected format. See the API reference for exact parameter specifications.
VLRdevAPI is running slowly
Slow responses are usually due to rate limiting, network latency, or multi-page enrichment. You can configure requests_per_second and timeout on your VLRClient. For endpoints supporting pagination, request only the records you need with limit instead of fetching all pages. See the guides for performance tips.
I get a RateLimitError. What should I do?
Reduce the frequency of your requests or raise the requests_per_second setting on your VLRClient. The default limit is conservative to protect both your application and VLR.gg. Spacing requests out over longer intervals usually helps more than fetching in parallel.
How do I enable debug logging?
Set the log level to DEBUG in your application. VLRdevAPI uses Python's standard logging module. Add import logging; logging.basicConfig(level=logging.DEBUG) to see detailed information about requests, responses, and caching behavior.
The data I get does not match what I see on VLR.gg
VLR.gg frequently updates match statistics, rosters, and live scores. In-memory client instances cache team details during match enrichment for the lifetime of that client. If you suspect data has changed on VLR.gg, create a fresh VLRClient or wait a few minutes and try again. If a parser discrepancy persists, open an issue on GitHub.
06

Comparison

4 questions
How does VLRdevAPI compare to other Valorant esports APIs?
VLRdevAPI is the only dedicated Python SDK for VLR.gg data. Unlike general-purpose scraping tools, it provides typed models, automatic normalization, built-in rate limiting, and a clean namespace structure. Other options include scraping VLR.gg directly or using third-party APIs that may require API keys or have usage limits.
Should I use VLRdevAPI or scrape VLR.gg directly?
For most projects, VLRdevAPI is faster to set up and more reliable than scraping. It handles markup changes, rate limiting, and data normalization automatically. Scraping gives you full control but requires ongoing maintenance. See the detailed comparison for a full breakdown.
Is VLRdevAPI better than BeautifulSoup for this use case?
Yes, for Valorant esports data. BeautifulSoup requires you to write and maintain CSS selectors for every data point, handle pagination manually, and build your own rate limiting and caching. VLRdevAPI gives you all of that out of the box with a clean Pythonic interface. Use BeautifulSoup if you need data from sources not covered by VLRdevAPI.
Can I use VLRdevAPI with frameworks like FastAPI or Django?
Yes. VLRdevAPI works with any Python web framework. It is synchronous, so call it directly from Django or Flask views, and in FastAPI or another async framework run calls in a thread with asyncio.to_thread so the event loop stays free.
07

Project

8 questions
Is this project affiliated with Riot Games or VLR.gg?
No. VLRdevAPI is an independent open-source project. It is not affiliated with, endorsed by, or connected to Riot Games or VLR.gg.
How can I contribute?
VLRdevAPI is open source on GitHub. Contributions are welcome: bug reports, feature requests, and pull requests are all appreciated. See the contributing guide in the repository.
What is the difference between the docs guides and the standalone guides?
The docs section covers contributor guides (development setup, contributing) and the API reference. The standalone guides section contains step-by-step tutorials for using the library. The blog has news, updates, and comparisons.
Where can I report bugs or request features?
Open an issue on the GitHub repository. Include the version you are using (check with vlrdevapi.__version__) and steps to reproduce.
What is the changelog and where can I find it?
The changelog tracks every release, feature, and fix in VLRdevAPI. It covers all versions with detailed section breakdowns.
Is there a community or Discord server?
Check the GitHub repository for community links and discussions. Issues and pull requests are the primary way to engage with the project.
How often is VLRdevAPI updated?
Updates are published as needed when VLR.gg changes its markup or when new features are added. Follow the changelog and GitHub releases for update notifications.
Can I use VLRdevAPI in a commercial project?
Yes. VLRdevAPI is open source under the MIT license. You can use it in personal, academic, and commercial projects. See the LICENSE file on GitHub for full terms.