MetaTFT APImetatft.com ↗
Access TFT team composition data from MetaTFT: comp names, win rates, pick rates, recommended items, star carries, and traits via 3 structured endpoints.
What is the MetaTFT API?
The MetaTFT API exposes Teamfight Tactics meta data across 3 endpoints, returning comp names, win rates, pick rates, traits, and per-unit item recommendations sourced from MetaTFT. The get_comps endpoint delivers a ranked list of all current meta compositions, while get_comp_details provides build-level breakdowns and daily trend data for any individual comp identified by its comp_id.
curl -X GET 'https://api.parse.bot/scraper/fafd290f-21e4-421b-bd4d-0e7a011e8e05/get_comps?days=1&rank=CHALLENGER%2CDIAMOND%2CEMERALD%2CGRANDMASTER%2CMASTER%2CPLATINUM&patch=current&queue=1100' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace metatft-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: MetaTFT SDK — discover top comps, drill into details, check unit items."""
from parse_apis.metatft_comps_api import MetaTFT, Days, CompNotFound
client = MetaTFT()
# List top compositions sorted by win rate, capped at 5.
for comp in client.comps.list(days=Days.THREE_DAYS, limit=5):
print(comp.name, comp.win_rate, comp.pick_rate)
# Drill into the #1 comp's full details via .first() then .details().
top_comp = client.comps.list(days=Days.THREE_DAYS, limit=1).first()
if top_comp:
detail = top_comp.details()
print(detail.name, detail.avg_placement, detail.levelling)
for build in detail.builds[:3]:
print(build.unit, build.items, build.avg_placement)
# Browse unit item recommendations filtered by name.
for unit in client.units.list(unit_name="Braum", limit=3):
print(unit.unit, unit.pick_rate, unit.top_items[:3])
# Typed error handling: catch CompNotFound on a bad comp_id.
bad_comp = client.comp(cluster_id="999999")
try:
bad_comp.details()
except CompNotFound as exc:
print(f"comp not found: {exc.comp_id}")
print("exercised: comps.list / comp.details / units.list / CompNotFound")
Retrieve all TFT team compositions with their names, units, items, stars, win rates, pick rates, traits, and builds. Results are sorted by win rate (top-4 placement percentage). Each comp includes its best builds, top items, trait synergies, and overall stats aggregated across the specified rank tiers and time window. Pagination is not supported; a single response contains all recognized compositions (typically 50-80).
| Param | Type | Description |
|---|---|---|
| days | string | Number of days for stats aggregation. |
| rank | string | Comma-separated rank filter. Individual values: CHALLENGER, GRANDMASTER, MASTER, DIAMOND, EMERALD, PLATINUM. |
| patch | string | Patch filter. Use 'current' for the active patch. |
| queue | string | Queue ID. 1100 is ranked TFT. |
{
"type": "object",
"fields": {
"comps": "array of Comp objects with cluster_id, name, units, stars, builds, top_items, traits, win_rate, pick_rate, avg_placement, play_count",
"patch": "string TFT set identifier (e.g. TFTSet17)",
"cluster_id": "integer current cluster version ID",
"total_comps": "integer number of compositions returned",
"total_games": "integer total games analyzed in the period"
}
}About the MetaTFT API
Compositions and Meta Overview
The get_comps endpoint returns an array of composition objects, each containing name, units, stars, traits, win_rate, pick_rate, avg_placement, and top_items. Results can be filtered by days (1, 3, or 7), rank (CHALLENGER through PLATINUM as a comma-separated list), patch, and queue (1100 for ranked). The response also includes aggregate fields: total_games (games analyzed in the period), total_comps, and the current patch identifier.
Comp Details and Build Trends
Passing a comp_id from get_comps into get_comp_details unlocks build-level data: an array of builds objects (each with unit, items, avg_placement, score, and place_change), a full all_items map with per-item count, avg_placement, and pick_rate, and a levelling string for recommended level strategy. The trends array provides day-by-day count, avg, and pick data so you can track how a comp's performance shifts across the patch cycle.
Per-Unit Item Recommendations
The get_unit_items endpoint returns up to 10 recommended items per champion, sorted by unit pick rate. Each unit object includes unit, api_name, count, avg_placement, pick_rate, and a top_items array. The optional unit_name parameter accepts a case-insensitive partial match, so querying "ahri" will resolve to the correct champion record without requiring an exact name string.
The MetaTFT API is a managed, monitored endpoint for metatft.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when metatft.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official metatft.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a TFT tier list dashboard using
win_rateandavg_placementfromget_compsfiltered to Challenger/Grandmaster ranks. - Generate patch-over-patch composition trend charts using the
trendsarray fromget_comp_details. - Recommend an in-game item build for a specific unit by querying
get_unit_itemswith the champion name. - Track which star carries (
starsfield) define the current meta after each patch update. - Identify off-meta compositions by comparing
pick_rateagainstwin_rateacross the fullget_compsresponse. - Surface trait synergies in draft tools using the
traitsarray returned per composition. - Evaluate how a specific comp's
avg_placementshifts over a 7-day window using thedaysfilter.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does MetaTFT have an official developer API?+
What rank tiers can I filter compositions by in `get_comps`?+
rank parameter accepts a comma-separated list from: CHALLENGER, GRANDMASTER, MASTER, DIAMOND, EMERALD, and PLATINUM. Passing multiple values (e.g., MASTER,GRANDMASTER,CHALLENGER) returns stats aggregated across those tiers.Does the API return augment data or augment win rates for compositions?+
How fresh is the data returned by these endpoints?+
days parameter in get_comps controls the lookback window (1, 3, or 7 days). The patch parameter also lets you scope results to the current patch. Data reflects recent ranked games within the selected window; real-time match-by-match freshness is not guaranteed.Can I retrieve historical composition performance from previous TFT sets?+
patch field in responses. Historical set data is not exposed through the current endpoints. You can fork this API on Parse and revise it to target prior-set data if that endpoint surface becomes available.