{
  "schema_version": 2,
  "id": "commands/ttl",
  "title": "TTL",
  "url": "https://redis.io/docs/latest/commands/ttl/",
  "summary": "Returns the expiration time in seconds of a key.",
  "since": "1.0.0",
  "tags": [
    "docs",
    "develop",
    "stack",
    "oss",
    "rs",
    "rc",
    "oss",
    "kubernetes",
    "clients"
  ],
  "last_updated": "2026-09-18T09:48:32+01:00",
  "page_type": "content",
  "content_hash": "8b9c0f8835396172648a38becb3f7c3f8455f4c945dd661fb02cfb906bad37e9",
  "sections": [
    {
      "id": "required-arguments",
      "title": "Required arguments",
      "role": "content",
      "text": "<details open><summary><code>key</code></summary>\n\nThe name of the key.\n\n</details>"
    },
    {
      "id": "examples",
      "title": "Examples",
      "role": "example",
      "text": "Foundational: Check remaining time-to-live of a key using TTL (returns seconds remaining, -1 if no expiry, -2 if key doesn't exist)\n\n**Difficulty:** Beginner\n\n**Commands:** SET, EXPIRE, TTL\n\n**Complexity:**\n- SET: O(1)\n- EXPIRE: O(1)\n- TTL: O(1)\n\n**Available in:** Redis CLI, C, C#, Go, Java (Asynchronous - Lettuce), Java (Reactive - Lettuce), Java (Synchronous - Jedis), JavaScript (Node.js), JavaScript (Node.js), PHP, Python, Rust (Asynchronous), Rust (Synchronous)\n\n##### Redis CLI\n\n[code example]\n\n##### C\n\n[code example]\n\n##### C#\n\n[code example]\n\n##### Go\n\n[code example]\n\n##### Java (Asynchronous - Lettuce)\n\n[code example]\n\n##### Java (Reactive - Lettuce)\n\n[code example]\n\n##### Java (Synchronous - Jedis)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### JavaScript (Node.js)\n\n[code example]\n\n##### PHP\n\n[code example]\n\n##### Python\n\n[code example]\n\n##### Rust (Asynchronous)\n\n[code example]\n\n##### Rust (Synchronous)\n\n[code example]"
    },
    {
      "id": "redis-software-and-redis-cloud-compatibility",
      "title": "Redis Software and Redis Cloud compatibility",
      "role": "content",
      "text": "| Redis<br />Software | Redis<br />Cloud | <span style=\"min-width: 9em; display: table-cell\">Notes</span> |\n|:----------------------|:-----------------|:------|\n| <span title=\"Supported\">&#x2705; Standard</span><br /><span title=\"Supported\"><nobr>&#x2705; Active-Active</nobr></span> | <span title=\"Supported\">&#x2705; Standard</span><br /><span title=\"Supported\"><nobr>&#x2705; Active-Active</nobr></span> |  |"
    },
    {
      "id": "return-information",
      "title": "Return information",
      "role": "returns",
      "text": "**RESP2:**\n\nOne of the following:\n* [Integer reply](../../develop/reference/protocol-spec#integers): TTL in seconds.\n* [Integer reply](../../develop/reference/protocol-spec#integers): `-1` if the key exists but has no associated expiration.\n* [Integer reply](../../develop/reference/protocol-spec#integers): `-2` if the key does not exist.\n\n**RESP3:**\n\nOne of the following:\n* [Integer reply](../../develop/reference/protocol-spec#integers): TTL in seconds.\n* [Integer reply](../../develop/reference/protocol-spec#integers): `-1` if the key exists but has no associated expiration.\n* [Integer reply](../../develop/reference/protocol-spec#integers): `-2` if the key does not exist."
    }
  ],
  "examples": [
    {
      "id": "examples-ex0",
      "language": "plaintext",
      "code": "> SET mykey \"Hello\"\nOK\n> EXPIRE mykey 10\n(integer) 1\n> TTL mykey\n(integer) 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex1",
      "language": "c",
      "code": "reply = redisCommand(c, \"SET mykey Hello\");\n    printf(\"%s\\n\", reply->str);\n    // >>> OK\n    freeReplyObject(reply);\n\n    reply = redisCommand(c, \"EXPIRE mykey 10\");\n    printf(\"%lld\\n\", reply->integer);\n    // >>> 1\n    freeReplyObject(reply);\n\n    reply = redisCommand(c, \"TTL mykey\");\n    printf(\"%lld\\n\", reply->integer);\n    // >>> 10\n    freeReplyObject(reply);",
      "section_id": "examples"
    },
    {
      "id": "examples-ex2",
      "language": "csharp",
      "code": "bool ttlResult1 = db.StringSet(\"mykey\", \"Hello\");\n        Console.WriteLine(ttlResult1);  // >>> true\n\n        bool ttlResult2 = db.KeyExpire(\"mykey\", new TimeSpan(0, 0, 10));\n        Console.WriteLine(ttlResult2);\n\n        TimeSpan ttlResult3 = db.KeyTimeToLive(\"mykey\") ?? TimeSpan.Zero;\n        string ttlRes = Math.Round(ttlResult3.TotalSeconds).ToString();\n        Console.WriteLine(Math.Round(ttlResult3.TotalSeconds)); // >>> 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex3",
      "language": "go",
      "code": "ttlResult1, err := rdb.Set(ctx, \"mykey\", \"Hello\", 10*time.Second).Result()\n\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(ttlResult1) // >>> OK\n\n\tttlResult2, err := rdb.TTL(ctx, \"mykey\").Result()\n\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tfmt.Println(math.Round(ttlResult2.Seconds())) // >>> 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex4",
      "language": "java",
      "code": "CompletableFuture<Void> ttlExample = asyncCommands.set(\"mykey\", \"Hello\")\n                    .thenCompose(r1 -> {\n                        System.out.println(r1);              // >>> OK\n                        return asyncCommands.expire(\"mykey\", 10);\n                    })\n                    .thenCompose(r2 -> {\n                        System.out.println(r2);              // >>> true\n                        return asyncCommands.ttl(\"mykey\");\n                    })\n                    .thenAccept(r3 -> {\n                        System.out.println(r3);              // >>> 10\n                    })\n                    .toCompletableFuture();",
      "section_id": "examples"
    },
    {
      "id": "examples-ex5",
      "language": "java",
      "code": "Mono<Void> ttlExample = reactiveCommands.set(\"mykey\", \"Hello\")\n                    .flatMap(r1 -> {\n                        System.out.println(r1);              // >>> OK\n                        return reactiveCommands.expire(\"mykey\", 10);\n                    })\n                    .flatMap(r2 -> {\n                        System.out.println(r2);              // >>> true\n                        return reactiveCommands.ttl(\"mykey\");\n                    })\n                    .doOnNext(r3 -> {\n                        System.out.println(r3);              // >>> 10\n                    })\n                    .then();",
      "section_id": "examples"
    },
    {
      "id": "examples-ex6",
      "language": "java",
      "code": "String ttlResult1 = jedis.set(\"mykey\", \"Hello\");\n        System.out.println(ttlResult1); // >>> OK\n\n        long ttlResult2 = jedis.expire(\"mykey\", 10);\n        System.out.println(ttlResult2); // >>> 1\n\n        long ttlResult3 = jedis.ttl(\"mykey\");\n        System.out.println(ttlResult3); // >>> 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex7",
      "language": "javascript",
      "code": "const ttlRes1 = await client.set('mykey', 'Hello');\nconsole.log(ttlRes1); // OK\n\nconst ttlRes2 = await client.expire('mykey', 10);\nconsole.log(ttlRes2); // 1\n\nconst ttlRes3 = await client.ttl('mykey');\nconsole.log(ttlRes3); // 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex8",
      "language": "javascript",
      "code": "console.log(await redis.set('mykey', 'Hello')); // >>> OK\nconsole.log(await redis.expire('mykey', 10)); // >>> 1\n\nconst ttlResult = await redis.ttl('mykey');\nconsole.log(ttlResult); // >>> 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex9",
      "language": "javascript",
      "code": "const ttlRes1 = await client.set('mykey', 'Hello');\nconsole.log(ttlRes1); // OK\n\nconst ttlRes2 = await client.expire('mykey', 10);\nconsole.log(ttlRes2); // 1\n\nconst ttlRes3 = await client.ttl('mykey');\nconsole.log(ttlRes3); // 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex10",
      "language": "javascript",
      "code": "console.log(await redis.set('mykey', 'Hello')); // >>> OK\nconsole.log(await redis.expire('mykey', 10)); // >>> 1\n\nconst ttlResult = await redis.ttl('mykey');\nconsole.log(ttlResult); // >>> 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex11",
      "language": "php",
      "code": "echo $r->set('mykey', 'Hello') . PHP_EOL;            // >>> OK\n        echo $r->expire('mykey', 10) . PHP_EOL;              // >>> 1\n\n        $ttlResult = $r->ttl('mykey');\n        echo $ttlResult . PHP_EOL;                           // >>> 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex12",
      "language": "python",
      "code": "res = r.set(\"mykey\", \"Hello\")\nprint(res)\n# >>> True\n\nres = r.expire(\"mykey\", 10)\nprint(res)\n# >>> True\n\nres = r.ttl(\"mykey\")\nprint(res)\n# >>> 10",
      "section_id": "examples"
    },
    {
      "id": "examples-ex13",
      "language": "rust",
      "code": "if let Ok(res) = r.set(\"mykey\", \"Hello\").await {\n            let res: String = res;\n            println!(\"{res}\");    // >>> OK\n        }\n\n        match r.expire(\"mykey\", 10).await {\n            Ok(res) => {\n                let res: bool = res;\n                println!(\"{res}\");    // >>> true\n            },\n            Err(e) => {\n                println!(\"Error setting key expiration: {e}\");\n                return;\n            }\n        }\n\n        match r.ttl(\"mykey\").await {\n            Ok(res) => {\n                let res: i64 = res;\n                println!(\"{res}\");    // >>> 10\n            },\n            Err(e) => {\n                println!(\"Error getting key TTL: {e}\");\n                return;\n            }\n        }",
      "section_id": "examples"
    },
    {
      "id": "examples-ex14",
      "language": "rust",
      "code": "if let Ok(res) = r.set(\"mykey\", \"Hello\") {\n            let res: String = res;\n            println!(\"{res}\");    // >>> OK\n        }\n\n        match r.expire(\"mykey\", 10) {\n            Ok(res) => {\n                let res: bool = res;\n                println!(\"{res}\");    // >>> true\n            },\n            Err(e) => {\n                println!(\"Error setting key expiration: {e}\");\n                return;\n            }\n        }\n\n        match r.ttl(\"mykey\") {\n            Ok(res) => {\n                let res: i64 = res;\n                println!(\"{res}\");    // >>> 10\n            },\n            Err(e) => {\n                println!(\"Error getting key TTL: {e}\");\n                return;\n            }\n        }",
      "section_id": "examples"
    }
  ]
}