Automated updating of API pages at this location, to reflect patch changes, has ceased from 10.1.7 onwards.

Returns the buffs/debuffs for the unit.

name, icon, count, dispelType, duration, expirationTime, source, isStealable, nameplateShowPersonal,
spellId, canApplyAura, isBossDebuff, castByPlayer, nameplateShowAll, timeMod, ...
    = UnitAura  (unit, index [, filter])
    = UnitBuff  (unit, index [, filter])
    = UnitDebuff(unit, index [, filter])

Arguments

unit

string : UnitId

index

number - Index of an aura to query.

filter

string? - A list of filters, separated by pipe chars or spaces. Otherwise defaults to "HELPFUL".

Filters

• UnitBuff() is an alias for UnitAura(unit, index, "HELPFUL"), returning only buffs.
• UnitDebuff() is an alias for UnitAura(unit, index, "HARMFUL"), returning only debuffs.

Returns

Returns nil when there is no aura for that index or when the aura doesn't pass the filter.

1. name

string - The localized name of the aura, otherwise nil if there is no aura for the index.

2. icon

number : FileID - The icon texture.

3. count

number - The amount of stacks, otherwise 0.

4. dispelType

string? - The locale-independent magic type of the aura: Curse, Disease, Magic, Poison, otherwise nil.

5. duration

number - The full duration of the aura in seconds.

6. expirationTime

number - Time the aura expires compared to GetTime(), e.g. to get the remaining duration: expirationtime - GetTime()

7. source

string : UnitId - The unit that applied the aura.

8. isStealable

boolean - If the aura may be stolen.

9. nameplateShowPersonal

boolean - If the aura should be shown on the player/pet/vehicle nameplate.

10. spellId

number - The spell ID for e.g. GetSpellInfo()

11. canApplyAura

boolean - If the player can apply the aura.

12. isBossDebuff

boolean - If the aura was cast by a boss.

13. castByPlayer

boolean - If the aura was applied by a player.

14. nameplateShowAll

boolean - If the aura should be shown on nameplates.

15. timeMod

number - The scaling factor used for displaying time left.

16+ ...

Variable returns - Some auras return additional values that typically correspond to something shown in the tooltip, such as the remaining strength of an absorption effect.

Details

• UnitBuff() will ignore any HARMFUL filter, and vice versa UnitDebuff() will ignore any HELPFUL filter.
• Filters can be mutually exclusive, e.g. "HELPFUL|HARMFUL" will always return nothing.
• On retail a unit can have an unlimited amount of buffs/debuffs.

• The debuff limit is at 16 for Classic Era and 40 for BCC.

World Buffs

If the unit has the  [Supercharged Chronoboon Displacer] buff, then the world buffs can be selected from the return values. For example for [Warchief's Blessing]:

select(20, UnitBuff("player", index))

Example

• Prints the third aura on the target.

/dump UnitAura("target", 3)

[1] = "Power Word: Fortitude", -- name
[2] = 135987,     -- icon
[3] = 0,          -- count
[4] = "Magic",    -- dispelType
[5] = 3600,       -- duration
[6] = 112994.871, -- expirationTime 
[7] = "player",   -- source
[8] = false,      -- isStealable
[9] = false,      -- nameplateShowPersonal
[10] = 21562,     -- spellID
[11] = true,      -- canApplyAura
[12] = false,     -- isBossDebuff
[13] = true,      -- castByPlayer
[14] = false,     -- nameplateShowAll
[15] = 1,         -- timeMod
[16] = 5,         -- attribute1: Stamina increased by 5%
[17] = 0          -- attribute2: Magic damage taken reduced by 0% (Thorghast Enchanted Shroud power)

• The following are equivalent. Prints the first debuff applied by the player on the target.

/dump UnitAura("target", 1, "PLAYER|HARMFUL")
/dump UnitDebuff("target", 1, "PLAYER")

• GetPlayerAuraBySpellID() is useful for checking only a specific aura on the player character.

/dump GetPlayerAuraBySpellID(21562)

Aura Util

ForEachAura

AuraUtil.ForEachAura(unit, filter, [maxCount], func, [usePackedAura])

This is recommended for iterating over auras. For example to print all buffs:

AuraUtil.ForEachAura("player", "HELPFUL", nil, function(name, icon, ...)
	print(name, icon, ...)
end)

The callback function should return true once it's fine to stop processing further auras.

local function foo(name, icon, _, _, _, _, _, _, _, spellId, ...)
	if spellId == 21562 then -- Power Word: Fortitude
		-- do stuff
		return true
	end
end
AuraUtil.ForEachAura("player", "HELPFUL", nil, foo)

FindAuraByName

AuraUtil.FindAuraByName(name, unit [, filter])

Finds the first aura that matches the name, but note that:

• Aura names are not unique, this will only find the first match.
• Aura names are localized, what works in one locale might not work in another.

/dump AuraUtil.FindAuraByName("Power Word: Fortitude", "player")

• Remember to specify the "HARMFUL" filter for debuffs.

/dump AuraUtil.FindAuraByName("Weakened Soul", "player", "HARMFUL")

Patch changes

Patch 9.0.1 (2020-10-13): Added MAW filter.^[1]
Patch 8.0.1 (2018-07-17): Removed querying by name, and removed rank return value.
Patch 7.0.3 (2016-07-19): Added nameplateShowAll and timeMod; shouldConsolidate changed to nameplateShowPersonal.
Patch 5.1.0 (2012-11-27): isCastByPlayer moved from #17 to #14 after isBossDebuff so that the value[1-n] are at the end and can expand beyond 3 returns.
Patch 4.2.0 (2011-06-28): Re-added the return values canApplyAura and isBossDebuff, and added return values value[1-3].
Patch 4.0.1 (2010-10-12): Removed the return values canApplyAura and isBossDebuff.
Patch 3.3.0 (2009-12-08): Added shouldConsolidate and spellId.
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.
Patch 3.0.2 (2008-10-14): Added UnitDebuff() and UnitBuff()

References