Python API Reference

copilot_session_usage.api

All public functions are in copilot_session_usage.api.

Public Python API for copilot-session-usage.

All functions accept an optional agent parameter for future routing between VS Code and Copilot-CLI providers.

copilot_session_usage.api.analyze_session(path, detail='compact', agent='vscode', *, auto_refresh=True)

Analyze one session by its debug-log directory path.

Parameters:

  • path (Path) – Path to the session’s debug-log directory.

  • detail (str) – minimal, compact (default), or full.

  • agent (str) – Provider to use (vscode or cli).

  • auto_refresh (bool) – Attempt the daily runtime pricing refresh before loading pricing. Set to false for offline or tightly controlled callers.

Return type:

dict

Returns:

Session analysis dict shaped to the requested detail level.

Raises:

NotImplementedError – If agent is "cli".

copilot_session_usage.api.list_sessions(workspace_roots=None, limit=20, since=None, until=None, name_pattern=None, workspace_filter=None, agent='vscode')

List recent sessions (metadata only, no JSONL reads).

Parameters:

  • workspace_roots (list[Path] | None) – Override workspaceStorage directories. Auto-detected if None.

  • limit (int) – Maximum sessions to return.

  • since (str | None) – Only sessions created after this date (ISO 8601 with timezone).

  • until (str | None) – Only sessions created before this date (ISO 8601 with timezone).

  • name_pattern (str | None) – Only sessions whose title or ID matches this regex.

  • workspace_filter (str | None) – Only sessions from this workspace folder.

  • agent (str) – Provider to use (vscode or cli).

Return type:

list[dict]

Returns:

List of session metadata dicts, most-recent first.

copilot_session_usage.api.find_sessions_by_title(title, workspace_roots=None, agent='vscode')

Fuzzy-match sessions by title substring.

Parameters:

  • title (str) – Substring to search for (case-insensitive).

  • workspace_roots (list[Path] | None) – Override workspaceStorage directories.

  • agent (str) – Provider to use (vscode or cli).

Return type:

list[dict]

Returns:

Matching session metadata dicts, most-recent first.

copilot_session_usage.api.find_session_by_id(session_id, workspace_roots=None, agent='vscode', *, auto_refresh=True)

Analyze a session by its exact UUID.

Parameters:

  • session_id (str) – The session UUID.

  • workspace_roots (list[Path] | None) – Override workspaceStorage directories.

  • agent (str) – Provider to use (vscode or cli).

  • auto_refresh (bool) – Attempt the daily runtime pricing refresh before loading pricing. Set to false for offline or tightly controlled callers.

Return type:

dict | None

Returns:

Session analysis dict, or None if not found.

copilot_session_usage.api.analyze_latest(workspace_roots=None, detail='compact', workspace_filter=None, agent='vscode', *, auto_refresh=True)

Analyze the most recently modified session.

Parameters:

  • workspace_roots (list[Path] | None) – Override workspaceStorage directories.

  • detail (str) – minimal, compact (default), or full.

  • workspace_filter (str | None) – Only sessions from this workspace folder.

  • agent (str) – Provider to use (vscode or cli).

  • auto_refresh (bool) – Attempt the daily runtime pricing refresh before loading pricing. Set to false for offline or tightly controlled callers.

Return type:

dict

Returns:

Session analysis dict shaped to the requested detail level.

Raises:

ValueError – If no sessions are found.

copilot_session_usage.api.batch_analyze(n, workspace_roots=None, detail='compact', since=None, workspace_filter=None, agent='vscode', *, auto_refresh=True)

Analyze the N most recent sessions.

Parameters:

  • n (int) – Number of sessions to analyze.

  • workspace_roots (list[Path] | None) – Override workspaceStorage directories.

  • detail (str) – minimal, compact (default), or full.

  • since (str | None) – Only sessions created after this date.

  • workspace_filter (str | None) – Only sessions from this workspace folder.

  • agent (str) – Provider to use (vscode or cli).

  • auto_refresh (bool) – Attempt the daily runtime pricing refresh before loading pricing. Set to false for offline or tightly controlled callers.

Return type:

dict

Returns:

Dict with summary (aggregate) and sessions (per-session list).

copilot_session_usage.api.aggregate_sessions(results)

Aggregate multiple session analyses into a single efficiency summary.

Parameters:

results (list[dict]) – Full session analysis dicts (e.g. from analyze_session).

Return type:

dict

Returns:

Dict with session count, totals, average cache ratio, model split, and cost per 1M tokens.

copilot_session_usage.api.load_pricing(ref_dir=None, *, auto_refresh=True)

Load pricing data.

Parameters:

  • ref_dir (Path | None) – Directory containing pricing YAML files. If None, uses the newest valid user snapshot or the bundled data directory shipped with the package.

  • auto_refresh (bool) – Attempt the daily runtime pricing refresh when ref_dir is None. Set to false for offline or tightly controlled callers.

Return type:

dict

Returns:

Pricing dict with model rates.

copilot_session_usage.api.refresh_pricing(force=False)

Refresh the user pricing snapshot from GitHub.

Parameters:

force (bool) – Bypass the normal rolling 24-hour refresh limit.

Return type:

PricingRefreshResult

Returns:

A typed result describing whether pricing was updated, unchanged, skipped, or unavailable.

copilot_session_usage.api.pricing_status()

Return the runtime pricing cache location and refresh metadata.

Return type:

dict

Internal models

These return types are produced by the API. They are plain dicts shaped by the detail parameter — see How Cost Estimation Works for the full field list.

Pricing lifecycle

load_pricing(ref_dir=None, auto_refresh=True) loads the newest valid pricing source. With the default arguments it performs a throttled runtime refresh attempt before selecting between the user cache and bundled fallback. Set auto_refresh=False for offline or tightly controlled callers. Supplying ref_dir always loads that directory directly and never contacts the network.

refresh_pricing(force=False) explicitly refreshes the user cache and returns a PricingRefreshResult with a status of updated, unchanged, skipped, or failed. Use force=True to bypass the rolling 24-hour limit. The pricing_status() helper returns cache paths and the last refresh metadata.