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')

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).

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, 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 (YYYY-MM-DD or ISO 8601).

  • 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')

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).

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')

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).

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')

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).

Return type:

dict

Returns:

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

copilot_session_usage.api.load_pricing(ref_dir=None)

Load pricing data.

Parameters:

ref_dir (Path | None) – Directory containing pricing YAML files. If None, uses the bundled data directory shipped with the package.

Return type:

dict

Returns:

Pricing dict with model rates.

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.