Idle Clans API
Idle Clans has an official public API. It is read-only, needs no key, and returns JSON from 43 GET endpoints covering players, clans, the player market, leaderboards and the full game data. This site is built on it, so the examples below are calls we make every day.
Example calls
Prefix each path with the base URL. Every one is a plain GET, so it works in a browser, curl or any HTTP library.
GET https://query.idleclans.com/api/PlayerMarket/items/prices/latest
The lowest sell offer and highest buy offer per item id. Our market table is built from it.
GET https://query.idleclans.com/api/PlayerMarket/items/prices/summary?period=7d
Average price and volume per traded item over the period.
GET https://query.idleclans.com/api/Player/profiles?usernames=NameOne&usernames=NameTwo
Repeat the usernames parameter once per player. Returns skills (raw XP), equipment and boss kills.
GET https://query.idleclans.com/api/Clan/experience/top
Clans ranked by experience gained, with a per-skill breakdown.
GET https://query.idleclans.com/api/Leaderboard/top/players:default/fishing
Top players in one skill on the default (non-ironman) board.
GET https://query.idleclans.com/api/Configuration/game-data
Items, tasks, recipes and settings in one large response (about 2.5 MB when we fetch it).
Tips from running it daily
- Send a descriptive User-Agent and space your calls. The spec does not publish a rate limit; we wait about one second between requests.
- Cache
/api/Configuration/game-data. It is large and changes only with game updates, so fetch it rarely, not on every page view. - The game-data response is MongoDB extended JSON:
ObjectId(...)andISODate(...)values appear unquoted, so a strict JSON parser fails until you replace them. - Player skills come back as raw XP. To show levels, convert with the Idle Clans XP table.
- Batch endpoints take a repeated parameter:
?usernames=A&usernames=B, not a comma list.
All endpoints
Every GET endpoint in the official OpenAPI spec, snapshot 2026-10-06. Summaries are the spec's own; check the live docs for new endpoints and full response shapes.
Players
Profiles, skills, gear and activity for one player or a batch.
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Player/clan-logs/{name} | Retrieves the logs for a specific player from all clans. | skip, limit |
| /api/Player/profile/{name} | Retrieves the profile for a specific player. | localize |
| /api/Player/profiles | Retrieves the profiles of multiple players in one request (batch). | usernames, localize |
| /api/Player/profile/simple/{username} | Retrieves a simple profile for a specific player. | — |
| /api/Player/activities | Retrieves activities for multiple players (batch). | usernames |
Clans
Clan XP, recruitment, logs and most-active search.
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Clan/logs/clan/{name} | Retrieves the logs for a specific clan. | skip, limit |
| /api/Clan/logs/clan/{clanName}/{playerName} | Retrieves the logs for a specific player within a clan. | skip, limit |
| /api/Clan/recruitment/{clanName} | Retrieves the recruitment information for a specific clan. | byTag |
| /api/Clan/recruitments | Retrieves the recruitment information for multiple clans in one request (batch). | clanNames |
| /api/Clan/most-active | Searches clans, ordered by activity score (highest first). | clanQueryInfoJson |
| /api/Clan/{clanName}/experience | Gets experience summary for a clan over a specified time period. | hours |
| /api/Clan/{clanName}/experience/timeline | Gets experience timeline for a clan (interval-by-interval breakdown). | hours |
| /api/Clan/experience/top | Gets top clans by total experience gained, including per-skill breakdown. | hours, limit, gameMode |
| /api/Clan/experience/top/{skill} | Gets top clans for a specific skill. | hours, limit, gameMode |
| /api/Clan/{clanName}/experience/player/{username} | Gets a specific player's contributions within a clan. | hours |
Player market
Latest prices, price history and trade volume.
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/PlayerMarket/items/prices/latest/{itemId} | Gets the latest prices for a specific item, including the lowest price, highest price, and optionally the average price. | includeAveragePrice |
| /api/PlayerMarket/items/prices/latest/comprehensive/{itemId} | Retrieves detailed price information for a specific item. | — |
| /api/PlayerMarket/items/prices/latest | Gets the latest prices for all items, including the lowest price, highest price, and optionally the average price. | includeAveragePrice |
| /api/PlayerMarket/items/prices/history/{itemId} | Retrieves the price history of a specific item over a given period. | period |
| /api/PlayerMarket/items/prices/history | Retrieves the price history of all traded items over a given period. | period |
| /api/PlayerMarket/items/prices/summary | Retrieves a compact activity summary for every traded item over a given period. | period |
| /api/PlayerMarket/items/prices/history/value | Retrieves the trades with the highest item prices within a specified period. | period, limit |
| /api/PlayerMarket/items/volume/history | Retrieves the top items by trade volume within a specified period. | period, limit |
Leaderboards
Top lists and single entries on any leaderboard.
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Leaderboard/profile/{leaderboardName}/{name} | Fetches the profile of an entity (player or clan) by their name. | — |
| /api/Leaderboard/top/{leaderboardName}/{name} | Gets a range of entities (players or clans) in the specified leaderboard field. | startCount, maxCount |
Game configuration
The full game data, market settings and build versions.
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Configuration/build-versions | Retrieves the required and latest build versions from the configuration. | — |
| /api/Configuration/market-settings | Retrieves the player market economy settings: the seller-side tax percentage and the buy/sell offer slot caps for premium and non-premium players. | — |
| /api/Configuration/game-data | The full game configuration. | minVersion |
Items
Lightweight metadata for every item.
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Items/metadata | Lightweight metadata for every item in this environment's item catalogue, with localized English display names. | — |
Clan Cup
Standings, rewards and leaderboards for the monthly Clan Cup.
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/ClanCup/standings/{clanName} | Retrieves a clan's standings for all objectives in the Clan Cup. | gameMode, previousCup |
| /api/ClanCup/standing/{clanName} | Retrieves a clan's score and current standing in a given ClanCupObjectiveType. | gameMode, objectiveType, previousCup |
| /api/ClanCup/rewards/{clanName}/previous | The clan credits ACTUALLY awarded to a clan for the previous cup, read from the reward record written when rewards were applied. | — |
| /api/ClanCup/top-clans/current | Retrieves the current top 10 clans in every ClanCupObjectiveType for the currently active cup. | gameMode |
| /api/ClanCup/top-clans/previous | Retrieves the top 10 clans in every ClanCupObjectiveType for the previous cup. | gameMode |
| /api/ClanCup/top-clans/date | Retrieves the top 10 clans in every ClanCupObjectiveType for a cup with the given end date. | gameMode, endDate |
| /api/ClanCup/leaderboard/{gameMode}/totalPoints | Retrieves the overall leaderboard for a specific game mode, showing total points for each clan. | year, month, limit |
| /api/ClanCup/leaderboard/{gameMode}/{category} | Retrieves the leaderboard for a specific category within a game mode. | year, month, limit |
| /api/ClanCup/leaderboard/{gameMode}/clans/{clanName} | Retrieves the standing for a specific clan in a given game mode. | year, month |
Chat
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Chat/recent | Retrieves the public chat history for various channels. | generalDisabled, tradeDisabled, helpDisabled, clanHubDisabled, combatLFGDisabled, raidLFGDisabled, minutes |
Milestone
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Milestone/recent | Global "latest milestones" feed (website landing page). | count |
News
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/news/latest | — | count |
Server
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Server/info | Gets all active game servers and a recommended server to connect to. | — |
Startup
| Endpoint | What it returns | Parameters |
|---|---|---|
| /api/Startup/info | Gets all information needed for game startup in a single call. | — |
Pages on this site built from the API
The live market prices and crafting profit calculator (market endpoints), the top players and clans pages (player, clan and leaderboard endpoints), and the item database and skill calculators (game data).
Frequently asked questions
Does Idle Clans have an API?
Yes. The game runs an official public API at https://query.idleclans.com. It is read-only: 43 GET endpoints that return JSON, documented at https://query.idleclans.com/api-docs/.
Do I need an API key for the Idle Clans API?
No. The endpoints are public and keyless. Send a descriptive User-Agent and space your calls out; this site waits about a second between requests.
How do I get a player's stats from the Idle Clans API?
Call /api/Player/profile/{name} for one player, or /api/Player/profiles with a usernames parameter per player for a batch. Skills come back as raw XP; convert XP to levels with the Idle Clans XP table.
How do I get Idle Clans market prices from the API?
/api/PlayerMarket/items/prices/latest returns current offers for every item, and /api/PlayerMarket/items/prices/history/{itemId} returns one item's price history.
Why does the game-data response fail to parse as JSON?
It is MongoDB extended JSON: values like ObjectId(...) and ISODate(...) appear unquoted. Replace those tokens with plain strings before a strict JSON parse.