What is Time to Live (TTL) in Cosmos DB and how do you configure it?

Time to Live (TTL) is a built-in expiry mechanism that automatically deletes items after a specified number of seconds from their last modification timestamp. This is useful for session data, temporary tokens, audit logs with retention windows, or any data with a known shelf life. Cosmos DB's TTL deletion is handled by a background process and does not consume your provisioned RU/s — it is essentially free in terms of throughput impact.

TTL is configured at two levels:

• Container-level TTL (DefaultTimeToLive) — Set this to a positive integer (seconds) to give all items a default TTL. Set to -1 to enable TTL at the container level but make each item's TTL opt-in (items without a ttl property never expire). If this property is absent on the container, TTL is completely disabled.
• Item-level TTL (ttl property) — Set a ttl field on individual items to override the container default. An item-level ttl: -1 means that item never expires regardless of the container default.

An example showing how container default and item override interact:

// Container: DefaultTimeToLive = 3600 (1 hour)

// This item expires in 1 hour (inherits container default)
{ "id": "session-1", "userId": "u123" }

// This item expires in 5 minutes (item override)
{ "id": "temp-token", "userId": "u456", "ttl": 300 }

// This item never expires (item override = -1)
{ "id": "permanent-record", "userId": "u789", "ttl": -1 }

TTL deletion happens within a few seconds to minutes after the expiry time. It is approximate, not exact — do not rely on it for precision timing like security token enforcement (validate the expiry claim in the token itself instead).

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.