---
title: "Retrieve a guild's average item level over time during a raid tier, reconstructed from armory and combat-log observations for the top N geared roster characters. Optionally overlay the logged per-pull raid group item level."
method: GET
path: "/api/v1/live-tracking/guild/ilvl-history"
tags: ["Live Tracking - Raiding"]
---

# Retrieve a guild's average item level over time during a raid tier, reconstructed from armory and combat-log observations for the top N geared roster characters. Optionally overlay the logged per-pull raid group item level.

`GET /api/v1/live-tracking/guild/ilvl-history`

The item level series combines Blizzard armory gear snapshots with precise equipped item levels from available raid and Mythic+ combat logs. Characters without logged observations continue to use armory history. The optional <code>include_pulls</code> overlay may be hidden if the guild has restricted data via privacy settings — check the <code>pullsError</code> field.

## Query parameters

- `access_key` string — The API key from your RaiderIO App: http://raider.io/settings/apps. Apps with API keys have higher rate limits.
- `raid` 'the-venomous-abyss' | 'the-tidebound-grotto' | 'sporefall' | 'tier-mn-1' | 'manaforge-omega' | 'liberation-of-undermine' | 'nerubar-palace' | 'blackrock-depths' | 'awakened-amirdrassil-the-dreams-hope' | 'awakened-aberrus-the-shadowed-crucible' | 'awakened-vault-of-the-incarnates' | 'amirdrassil-the-dreams-hope' | 'aberrus-the-shadowed-crucible' | 'vault-of-the-incarnates' | 'fated-sepulcher-of-the-first-ones' | 'fated-sanctum-of-domination' | 'fated-castle-nathria' | 'sepulcher-of-the-first-ones' | 'sanctum-of-domination' | 'castle-nathria' | 'nyalotha-the-waking-city' | 'the-eternal-palace' | 'crucible-of-storms' | 'battle-of-dazaralor' | 'uldir' | 'antorus-the-burning-throne' | 'tomb-of-sargeras' | 'the-nighthold' | 'trial-of-valor' | 'the-emerald-nightmare' | 'latest', required — Raid slug or full name (e.g. "the-venomous-abyss" or "The Venomous Abyss")
- `top_n` integer — How many of the highest geared eligible roster characters to average
- `difficulty` 'mythic' | 'heroic' | 'normal' | 'latest' — Raid difficulty. One of: mythic, heroic, normal. 'latest' resolves per guild to their highest difficulty with kills.
- `include_pulls` boolean — Also return the logged per-pull raid group item level averages
- `pulls_difficulty` string — Comma separated difficulties the pull overlay covers, e.g. `heroic,mythic`. Defaults to `all`, so split runs on a lower difficulty than the tracked progression still show up
- `pulls_scope` 'cohort' | 'all' — Which logged raids the pull overlay covers: 'cohort' keeps only raids one of the tracked top-N characters was in, 'all' keeps every raid any guild member was in
- `bucket` '15min' | 'hour' | '6hour' | 'day' — Sampling interval of the item level series; auto-promoted on long windows
- `scope` 'all' | 'mains' — Which roster characters to sample: every eligible character, or mains only
- `min_date` string, date-time — Clamp the window start to this date (ISO 8601)
- `max_date` string, date-time — Clamp the window end to this date (ISO 8601)
- `region` 'us' | 'eu' | 'tw' | 'kr' | 'cn', required — Region of the guild. One of: us, eu, kr, tw
- `realm` string, required — Realm name. Accepts slug form (e.g. "altar-of-storms") or display name (e.g. "Altar of Storms")
- `guild` string, required — Guild name. Not case sensitive.

## Response `200`

Successful

- ViewGuildIlvlHistoryResponse
  - `guild` GuildSummary
    - `id` integer, required — Internal Raider.IO ID number for this guild
    - `name` string, required — Name of the guild
    - `faction` 'horde' | 'alliance', required
    - `realm` RealmSummary
      - `id` integer, required — Internal Raider.IO ID number for this realm
      - `connectedRealmId` integer, required — Internal connected-realm ID used by Raider.IO
      - `wowRealmId` integer, nullable, required — Blizzard realm ID, or null when unavailable
      - `wowConnectedRealmId` integer, nullable, required — Blizzard connected-realm ID, or null when unavailable
      - `name` string, required — Name of the realm
      - `altName` string, nullable, required — Alternate display name for the realm
      - `slug` string, required — Slug for the realm, suitable for putting in URLs
      - `altSlug` string, required — Alternate slug for the realm
      - `locale` string, nullable, required — Locale configured for the realm
      - `isConnected` boolean, required — Whether the realm is part of a connected realm
      - `realmType` string, required — Realm type summary
    - `region` RegionSummary
      - `name` string, required — Name of the region
      - `short_name` string, required — Short name of the region
      - `slug` string, required — Slug for the region, suitable for putting in URLs
    - `path` string, required — Relative path to the guild profile
    - `logo` string — Guild logo URL
    - `isDefaultLogo` boolean — Whether the guild is using the default logo
    - `color` string — Guild theme color when customized
    - `displayName` string, required — Display name for the guild
    - `alt_name` string — Alternate guild name extracted from the stored name
  - `raid` RaidSummary
    - `id` integer — Raid ID
    - `slug` string — Raid slug
    - `name` string — Raid display name
    - `short_name` string — Abbreviated raid name
    - `icon` string — Icon identifier for the raid
    - `expansion_id` integer — Expansion ID. 11 = Midnight, 10 = TheWarWithin, 9 = Dragonflight, 8 = Shadowlands, 7 = BattleForAzeroth, 6 = Legion
  - `window` GuildIlvlHistoryWindow
    - `start` string — ISO 8601 start of the reconstructed window
    - `end` string — ISO 8601 end of the reconstructed window
  - `raceStart` string — ISO 8601 start of the tier in the guild region, before any min_date clamping
  - `bucket` string — Effective sampling interval, after any long-window promotion
  - `bossCount` integer — Number of bosses in the raid
  - `difficulty` string — Resolved difficulty (per guild when 'latest' was requested)
  - `weeklyResets` string[] — ISO 8601 regional weekly reset boundaries falling inside the window
  - `topN` integer — How many characters each point averages over at most
  - `scope` string — Which roster characters were sampled ("all" or "mains")
  - `roster` GuildIlvlHistoryRoster
    - `size` integer — Total roster size
    - `eligible` integer — Roster characters eligible for guild item level stats (max level and recently seen)
  - `series` GuildIlvlHistoryPoint[] — Armory and combat-log item level series. Continuous - values carry forward between changes.
    - `t` string — ISO 8601 timestamp of the sample
    - `ilvl` number — Mean equipped item level of the top N characters at this time
    - `sampleSize` integer — How many characters this sample averaged over
    - `p10` number, nullable — 10th percentile item level of the sampled characters, or null below 4 samples
    - `p90` number, nullable — 90th percentile item level of the sampled characters, or null below 4 samples
    - `startIlvl` number, nullable — Roster item level at the exact requested window start, before bucket alignment
  - `kills` GuildIlvlHistoryKill[] — Armory-derived boss kills inside the window, ordered oldest first.
    - `bossSlug` string — Boss slug that was defeated
    - `bossName` string — Boss display name
    - `bossShortName` string — Boss short display name
    - `bossIcon` string — Boss icon name, served from /images/wow/icons
    - `bossOrdinal` integer — 1-based position of the boss in the raid
    - `difficulty` string — Difficulty the boss was defeated on
    - `defeatedAt` string — ISO 8601 timestamp of the kill
    - `itemLevelAvg` number, nullable — Average equipped item level of the raid group on the kill
  - `pulls` GuildIlvlHistoryPull[], nullable — Logged per-pull raid group item levels, or null when include_pulls is false
    - `pullStartedAt` string — ISO 8601 timestamp when the pull started
    - `itemLevelAvg` number — Average equipped item level of the raid group on this pull
    - `numMembers` integer — Number of raid members present for the pull
    - `bossSlug` string — Boss slug this pull was on
    - `difficulty` string — Raid difficulty this pull was logged on
    - `cohortMemberIds` integer[] — Tracked top-N characters present for this pull; a split is any pull holding at least one
  - `cohortMembers` CohortMembers, nullable — Character id to name for every tracked character named in these pulls
  - `cohortUnavailable` boolean — The cohort could not be resolved, so no pull was matched
  - `pullsError` PullsError, nullable — Error object if the pull overlay is restricted by guild privacy
    - `code` integer — Error code
    - `error` string — Error message
  - `guildPrivacy` GuildIlvlHistoryPrivacy, nullable
    - `shareRaidUntil` string, nullable — ISO 8601 date until which raid data is shared, or null for indefinite
  - `widgetVersion` integer — Widget version for cache invalidation

---

[API](https://skmtc.net/raider/apis/raider-io-developer-api.md) · [All operations](https://skmtc.net/raider/apis/raider-io-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/raider/raider-io-developer-api/revisions/d89777d7faee/schema)