API UnitBuff

From Wowpedia
Jump to: navigation, search

Retrieve info about a certain buff on a certain unit. This essentially an alias of UnitAura with the "HELPFUL" filter.

name, rank, icon, count, debuffType, duration, expirationTime, unitCaster, isStealable, 
nameplateShowPersonal, spellId, canApplyAura, isBossDebuff, nameplateShowAll, timeMod, value1, value2, value3 = UnitBuff("unit", index or "name"[, "rank"[, "filter"]])

If the second parameter is a string, then the third parameter is the rank (which can be nil)

Either use:
unit, index, filter
unit, name, rank, filter


  • UnitBuff("target", 1) -- First buff on target
  • UnitBuff("target", 1, "PLAYER") -- First buff, cast by the player, on the target
  • UnitBuff("player", "Lightning Shield") -- first instance of "Lightning Shield" on the player
  • UnitBuff("player", "Lightning Shield", nil, "PLAYER") -- first instance of "Lightning Shield" on the player, cast by the player


String - The unit you want debuff information for.
Number - The index of the debuff to retrieve info for. Starts at 1, maximum 40.
This parameter can be any of "PLAYER", "RAID", "CANCELABLE", "NOT_CANCELABLE". You can also specify several filters separated by a | or space character to chain multiple filters together (e.g. "CANCELABLE|RAID" or "CANCELABLE RAID" == cancelable buffs that you can cast on your raid).


String - The name of the spell or effect of the buff, or nil if no buff was found with the specified name or at the specified index. This is the name shown in yellow when you mouse over the buff's icon.
String - The rank of the spell or effect that caused the buff. Returns "" if there is no rank.
String - The identifier of (path and filename to) the indicated buff.
Number - The number of times the buff has been applied to the target.
String - The magic type of the buff
Number - The full duration of the buff in seconds
Number - Time the buff expires (compare to GetTime())
String - The unit that cast the buff
Boolean - true if it is stealable
Boolean - true if the buff should be shown on the player/pet/vehicle nameplate
Number - spell ID of the aura.
Boolean - true if the player can apply the aura (not necessarily if the player did apply the aura, just if the player can apply the aura).
Boolean - true if the aura was cast by a boss.
Boolean - true if the buff should be shown on nameplates
Number - scaling factor used for displaying time left
Number - Value of variable effect 1 of the aura. (HoTs, resource-capturing trinkets, etc.)
Number - Value of variable effect 2 of the aura. (HoTs, resource-capturing trinkets, etc.)
Number - Value of variable effect 3 of the aura. (HoTs, resource-capturing trinkets, etc.)


local buffs, i = { }, 1;
local buff = UnitBuff("player", i);
while buff do
  buffs[#buffs + 1] = buff;
  i = i + 1;
  buff = UnitBuff("player", i);
if #buffs < 1 then
  buffs = "You have no buffs";
  buffs[1] = "You're buffed with: "..buffs[1];
  buffs = table.concat(buffs, ", ");
Macro Options:

1. Prints the names of all buffs on the current target:

/run for i=1,40 do local B=UnitBuff("target",i); if B then print(i.."="..B) end end

2. Prints the name, icon texture, and time left for all buffs on the player.

/run for i=1,40 do local n,_,icon,_,_,dur,x,_,_=UnitBuff("player",i);if n then print(i.."="..n..", "..icon..", "..format("%.2f",-1*(GetTime()-x)/60).." minutes left.")end end

Patch changes

  • Legion Patch 7.0.3 (2016-07-19): Added return values "nameplateShowAll" and "timeMod"; change "shouldConsolidate" to "nameplateShowPersonal".
  • Cataclysm Patch 4.2.0 (2011-06-28): Re-added the return values "canApplyAura" and "isBossDebuff", and added return values value[1-3].
  • Cataclysm Patch 4.0.1 (2010-10-12): Removed the return values "canApplyAura" and "isBossDebuff".
  • WotLK Patch 3.3.0 (2009-12-08): Added shouldConsolidate and spellId.
  • WotLK Patch 3.1.0 (2009-04-14): Changed "isMine" to "unitCaster". It is now possible for addons to retrieve the unitId that cast the buff/debuff.
  • WotLK Patch 3.0.2 (2008-10-14): Updated the return values.
  • TBC Patch 2.4.0 (2008-03-25): Corrected the bug introduced in 2.3.2. The castable parameter correctly filters non-castable buffs once again.
  • TBC Patch 2.3.2 (2008-01-08): Changed behavior of castable parameter - spells cast by other players are no longer shown at all when castable is used. This is a bug.
  • TBC Patch 2.1.0 (2007-05-22): Added duration and timeLeft return values.
  • TBC Patch 2.0.1 (2006-12-05): Added name and rank return values.
  • WoW Icon 16x16.png Patch 1.9.0 (2006-01-03): Added castable to the list of parameters.

See also

HOWTO: Identify Buffs Using Textures
List of known buff and debuff effects that can be queried