PTTL(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ PTTL — the "how much time do you have left bestie" command ✨

okay so this is pttl, straight outta the Valkey Command Manual (that's the manual name, folding it in here like a lil name tag 🎀). it tells you how long a key has to live, in milliseconds, and honestly? it's giving stopwatch energy. ⏱️

💖 NAME 💖

pttl — Returns the expiration time in milliseconds of a key. no cap, that's the whole job description. 🫶

🌸 SYNOPSIS 🌸

PTTL key

that's it. one lil argument. iconic minimalism. 💅

🦋 DESCRIPTION 🦋

okay so, like valkey-ttl(7) TTL — this command does the exact same thing, it returns the remaining time to live of a key that has an expire set. the sole difference (and this is the whole personality of PTTL fr fr) is that TTL hands you the remaining time in seconds, while PTTL hands it to you in milliseconds. more digits, more drama, more precision. ✨

and when things go sideways, the command returns these values:

  • The command returns -2 if the key does not exist. 💀
  • The command returns -1 if the key exists but has no associated expire. 🙈
bestie those negative numbers are not a TTL, they're lil error codes wearing a number costume. don't get played. 👑

⭐ REPLY ⭐

One of the following, pick your fighter:

💅 COMPLEXITY 💅

O(1)

constant time, baby. one lookup, zero sweat, main character energy only. 🔥

🌈 ACL CATEGORIES 🌈

@fast @keyspace @read

🧚 HISTORY 🧚

  • Available since: 2.6.0 — an elder, a legend, a pioneer. 👑
  • Changed in 2.8.0: Added the -2 reply. the glow-up era. ✨

🍓 EXAMPLES 🍓

watch it in action, bestie:

127.0.0.1:6379> SET mykey "Hello"
OK
127.0.0.1:6379> EXPIRE mykey 1
(integer) 1
127.0.0.1:6379> PTTL mykey
(integer) 989

see how 989 is just under 1000? that's because the second was already tickin' away. iykyk. 🦋

💜 SEE ALSO 💜

your recommended reading list, all the siblings and cousins:

copy(3valkey), del(3valkey), dump(3valkey), exists(3valkey), expire(3valkey), expireat(3valkey), expiretime(3valkey), keys(3valkey), migrate(3valkey), move(3valkey), object(3valkey), object-encoding(3valkey), object-freq(3valkey), object-help(3valkey), object-idletime(3valkey), object-refcount(3valkey), persist(3valkey), pexpire(3valkey), pexpireat(3valkey), pexpiretime(3valkey), randomkey(3valkey), rename(3valkey), renamenx(3valkey), restore(3valkey), scan(3valkey), sort(3valkey), sort_ro(3valkey), touch(3valkey), ttl(3valkey), type(3valkey), unlink(3valkey), wait(3valkey), waitaof(3valkey)

okay that's the whole page, you ate that reading session fr fr 🫶 this was Valkey 9.0.0, dated 2025-10-21 — go check on your keys' TTLs before they ghost you, periodt. 💖✨

📦 where this page comes from