API UnitAura

Main Menu
WoW API Lua API FrameXML util Widget API Widget scripts XML schema Events CVars Macro commands Combat Log Escape sequences Hyperlinks API changes HOWTOs wowuidev

Retrieve info about an aura (a buff or debuff).

name, icon, count, debuffType, 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 to query.

index

number - Index incremented from 1 until no more results.

filter

string?Optional. Could be nil. - Optional, case-insensitive filters separated by spaces or pipes.

• UnitAura() uses all filters in the table below.
• UnitBuff() implies HELPFUL and ignores HARMFUL.
• UnitDebuff() implies HARMFUL and ignores HELPFUL.

Filter	Description
HELPFUL	Buffs.
HARMFUL	Debuffs.
PLAYER	Auras applied by the player.
RAID	Buffs the player can apply and debuffs the player can dispell.
CANCELABLE	Buffs removable using /cancelaura or CancelUnitBuff().
NOT_CANCELABLE	The complement of CANCELABLE
INCLUDE_NAME_PLATE_ONLY	Auras shown on default nameplates.
MAW	Torghast Anima Powers.

Returns

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

• When multiple filters are used, results will be the intersection of each. Thus, mutually-exclusive filters ("HELPFUL HARMFUL" or "CANCELABLE NOT_CANCELABLE") always return nothing.
• Returns nil when there are no results for a given set of arguments.

Examples

The third aura on the player, without any filtering:

UnitAura("target", 3)

Two equivalent ways to obtain the first debuff cast by the player on the target:

UnitAura("target", 1, "PLAYER HARMFUL")
UnitDebuff("target", 1, "PLAYER")

Printing the names of any stealable buffs on the current target, or advising that none are stealable:

/run local y,n,s,_ for i=1,40 do n,_,_,_,_,_,_,s=UnitAura("target",i)if s then print(n.." on target, steal it!")y=1 end end if y~=1 then print("No stealable buffs.")end

Patch changes

• Patch 9.0.1 (2020-10-13): Added MAW filter.
  
• 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 as a combination of UnitDebuff and UnitBuff.
  

See also

• SecureAuraHeaderTemplate - Automates creating a secure action button for each aura.
• UnitAuraSlots and UnitAuraBySlot - An alternative for a batch of auras.

External links

UnitAura()

• GitHub FrameXML, Gethe
• Globe "wut?" Tool, Townlong-Yak

UnitBuff()

• GitHub FrameXML, Gethe
• Globe "wut?" Tool, Townlong-Yak

UnitDebuff()

• GitHub FrameXML, Gethe
• Globe "wut?" Tool, Townlong-Yak