UnitAura

Category nav.

Retrieve info about a certain buff on a certain unit.

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

Arguments

unit

String (unitId) - unit whose auras to query.

index

Number or String - index

filter

String (optional) - list of filters, separated by spaces or pipes. "HELPFUL" by default. The following filters are available:

HELPFUL - buffs.

HARMFUL - debuffs.

PLAYER - auras that were applied by the player.

RAID - auras that can be applied (if HELPFUL) or dispelled (if HARMFUL) by the player.

CANCELABLE - buffs that can be removed (such as by right-clicking or using the /cancelaura command)

NOT_CANCELABLE - buffs that cannot be removed

INCLUDE_NAME_PLATE_ONLY

Returns

[edit]

see Aura Type

1. name: String - The localized name of the aura, or nil if no aura was found at the specified index. This is the name shown in yellow when you mouse over the aura's icon.
2. icon: Number (fileDataID) - Identifier of the aura's icon for use with SetTexture()
3. count: Number - The number of stacks, or 0 for a non-stackable aura
4. debuffType: String - The magic type of the aura
5. duration: Number - The full duration of the aura in seconds
6. expirationTime: Number - Time the aura expires (compare to GetTime())
7. source: String - The unit that cast the aura
8. isStealable: Boolean - true if it the aura may be stolen (see [Spellsteal])
9. nameplateShowPersonal: Boolean - true if the aura should be shown on the player/pet/vehicle nameplate
10. spellId: Number - unique ID of the aura for use with the spell API such as GetSpellInfo()
11. canApplyAura: Boolean - true if the player can apply the aura (not necessarily that the player did apply it, just that the player can).
12. isBossDebuff: Boolean - true if the aura was cast by a boss.
13. castByPlayer: Boolean - true if the aura was applied by a player.
14. nameplateShowAll: Boolean - true if the aura should be shown on nameplates
15. timeMod: Number - scaling factor used for displaying time left
16 and subsequent. ...: Additional values, documented as up to 11 but possibly more, based on the specifics of the aura in question.

Examples

UnitAura("target", 1): the first buff on the target
UnitAura("target", 1, "PLAYER HARMFUL"): the first debuff cast by the player on the target

The following macro prints the names of any stealable buffs on the current target, or a notice if nothing is 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

Notes

Spell ranks were removed in Patch 4.0 (Cataclysm), so the rank argument to this function is largely useless today.
Some filters are mutually exclusive. Using "HELPFUL HARMFUL" together will return no results, since no aura can be both a buff and a debuff at the same time. Using "CANCELABLE NOT_CANCELABLE" will also return no results, since no buff can be both removable and unremovable.
The debuffType return value is not localized.
The UnitBuff function is an alias for using UnitAura with the "HELPFUL" filter. The UnitDebuff function is an alias for using UnitAura with the "HARMFUL" filter. Both aliases will ignore the "HELPFUL" and "HARMFUL" filters, but will accept other filters.

Patch changes

Patch 8.0.1 (2018-07-17): Removed querying by name, and removed rank return value.
[8.0.1 API changes]
Patch 7.0.3 (2016-07-19): Added nameplateShowAll and timeMod; shouldConsolidate changed to nameplateShowPersonal.
[7.0.3 API changes]
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.
[5.1.0 API changes]
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.
[4.0.1 API changes]
Patch 3.3.0 (2009-12-08): Added shouldConsolidate and spellId.
[3.3.0 API changes]
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.
[3.1.0 API changes]
Patch 3.0.2 (2008-10-14): Added as a combination of UnitDebuff and UnitBuff.
[3.0.2 API changes]