Implementation:BerriAI Litellm Duration Parser

Attribute	Value
Sources	litellm/litellm_core_utils/duration_parser.py
Domains	Utilities, Time Parsing, Budget Management, Key Management
last_updated	2026-02-15 16:00 GMT

Overview

The Duration Parser module provides utilities for parsing human-readable duration strings (e.g., "30s", "1h", "7d", "1mo") into seconds and computing standardized reset times for budget and rate-limit cycles.

Description

This module serves two primary use cases in LiteLLM:

1. Provider budget routing -- The Router uses duration_in_seconds() to convert budget reset periods into seconds for tracking provider spend windows.
2. Proxy key/team management -- The Proxy uses both functions to determine when API keys expire or budgets reset.

Core function: duration_in_seconds() Parses a duration string with the format <number><unit> and returns the equivalent number of seconds. Supported units:

• s -- seconds
• m -- minutes (x60)
• h -- hours (x3600)
• d -- days (x86400)
• w -- weeks (x604800)
• mo -- months (calendar-aware: computes actual seconds until the same day next month, handling month-end edge cases)

Standardized reset times: get_next_standardized_reset_time() Computes the next predictable reset boundary aligned to clean intervals. For example:

• "1d" resets at next midnight
• "7d" resets on next Monday at midnight
• "30d" resets on the 1st of next month
• "1h" resets at the next aligned hour boundary
• "1mo" resets at the first of next month

This function supports timezone-aware computation with a limited set of timezone mappings (UTC, US/Eastern, US/Pacific, Asia/Kolkata, Asia/Bangkok, Europe/London).

Internal helper functions handle each time unit separately: _handle_day_reset, _handle_hour_reset, _handle_minute_reset, _handle_second_reset, _handle_month_reset.

Usage

Import the parsing functions for budget or key expiration calculations:

from litellm.litellm_core_utils.duration_parser import duration_in_seconds

Code Reference

Source Location

/litellm/litellm_core_utils/duration_parser.py (401 lines)

Key Functions

Function	Signature	Purpose
duration_in_seconds	def duration_in_seconds(duration: str) -> int	Converts a duration string to seconds
get_next_standardized_reset_time	def get_next_standardized_reset_time(duration: str, current_time: datetime, timezone_str: str = "UTC") -> datetime	Computes the next aligned reset time
get_last_day_of_month	def get_last_day_of_month(year, month) -> int	Returns the last day number for a given month
_extract_from_regex	def _extract_from_regex(duration: str) -> Tuple[int, str]	Parses duration string into (value, unit)
_setup_timezone	def _setup_timezone(current_time, timezone_str) -> Tuple[datetime, timezone]	Resolves timezone and normalizes datetime
_handle_month_reset	def _handle_month_reset(current_time, base_midnight, value) -> datetime	Monthly reset at first of next month

Import

from litellm.litellm_core_utils.duration_parser import (
    duration_in_seconds,
    get_next_standardized_reset_time,
)

I/O Contract

Inputs

Parameter	Type	Description
duration	str	Duration string in format <number><unit> (e.g., "30s", "1h", "7d", "1mo")
current_time	datetime	Reference time for reset calculations
timezone_str	str	Timezone identifier (e.g., "UTC", "US/Eastern")

Outputs

Return	Type	Description
Seconds	int	Number of seconds represented by the duration (from duration_in_seconds)
Reset time	datetime	Next aligned reset time (from get_next_standardized_reset_time)

Raises ValueError for unsupported duration units or invalid format.

Usage Examples

from litellm.litellm_core_utils.duration_parser import (
    duration_in_seconds,
    get_next_standardized_reset_time,
)
from datetime import datetime, timezone

# Simple duration parsing
seconds = duration_in_seconds("30s")   # 30
seconds = duration_in_seconds("5m")    # 300
seconds = duration_in_seconds("2h")    # 7200
seconds = duration_in_seconds("7d")    # 604800
seconds = duration_in_seconds("1mo")   # ~2592000 (calendar-aware)

# Compute next budget reset time
now = datetime(2026, 2, 15, 14, 30, 0, tzinfo=timezone.utc)
next_reset = get_next_standardized_reset_time("1d", now)
# Returns: 2026-02-16 00:00:00 UTC (next midnight)

next_reset = get_next_standardized_reset_time("7d", now)
# Returns: 2026-02-16 00:00:00 UTC (next Monday)

next_reset = get_next_standardized_reset_time("30d", now)
# Returns: 2026-03-01 00:00:00 UTC (first of next month)

Related Pages

• Implementation:BerriAI_Litellm_Constants - defines HOURS_IN_A_DAY, DAYS_IN_A_MONTH, DAYS_IN_A_YEAR
• Implementation:BerriAI_Litellm_Core_Helpers - complementary utility functions