UnitAura

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.

Filter	Description
"HELPFUL"	Buffs
"HARMFUL"	Debuffs
"PLAYER"	~~Auras~~ Debuffs applied by the player
"RAID"	Buffs the player can apply and debuffs the player can dispell
"CANCELABLE"	Buffs that can be cancelled with /cancelaura or CancelUnitBuff()
"NOT_CANCELABLE"	Buffs that cannot be cancelled
"INCLUDE_NAME_PLATE_ONLY"	Auras that should be shown on nameplates
"MAW"	Torghast Anima Powers

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.

Related Events

UNIT_AURA

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))

Buff	Type	Description
16. Fengus' Ferocity	number	Duration
17. Mol'dar's Moxie	number	Duration
18. Slip'kik's Savvy	number	Duration
19. Rallying Cry of the Dragonslayer	number	Duration
20. Warchief's Blessing	number	Duration
21. Spirit of Zandalar	number	Duration
22. Songflower Serenade	number	Duration
23. Sayge's Fortune	number	spellID of the chosen buff
24. Sayge's Fortune	number	Duration of the chosen buff

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()