perf: defer API run creation until first emission upload (3/4)

[davidberenstein1957]

Summary

Part 3/4 of the tracker performance stack. Depends on #1251 → #1252.

cc @inimaz — small, isolated API write-path change from the #1246 split.

Defers the POST /runs API call until the first emission is actually uploaded, so online trackers with API output enabled no longer block on run creation during startup:

• CodeCarbonAPIOutput uses create_run_automatically=False
• _ensure_api_run() creates the run lazily on first live_out / out call

Benchmarks (measured locally, offline Mac ARM, 2026-06-21)

Mocked geo/cloud/API network; measures EmissionsTracker(save_to_api=True) cold start():

Metric	#1251 + #1252	+ this PR	Notes
API tracker start() avg	407 ms	369 ms	~9% faster — avoids blocking POST /runs at startup
Tracker __init__ / warm lifecycle	unchanged	unchanged	No change expected — run creation deferred to first upload

Stack

1. perf: defer tracker initialization and slim import path (1/4) #1251 — lazy initialization & import slimming
2. perf: cache hardware detection and optimize warm-path reuse (2/4) #1252 — hardware detection cache & warm-path reuse
3. This PR — lazy API run creation
4. perf: speed up CLI monitor startup and fix wrapped commands (4/4) #1254 — CLI monitor startup

CI / quality

• pre-commit run on all changed files — passed
• pytest tests/output_methods/test_http.py — 9 passed
• Full stacked suite (perf: speed up CLI monitor startup and fix wrapped commands (4/4) #1254 tip) — 535 passed locally

Test plan

• Reviewer: online tracker with API output still uploads emissions correctly

Replaces

Split from #1246.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.28%. Comparing base (00817d8) to head (928621d).

Additional details and impacted files

@@                            Coverage Diff                             @@
##           davidberenstein1957/perf-2-hardware-cache    #1253   +/-   ##
==========================================================================
  Coverage                                      89.27%   89.28%           
==========================================================================
  Files                                             48       48           
  Lines                                           4757     4761    +4     
==========================================================================
+ Hits                                            4247     4251    +4     
  Misses                                           510      510           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[davidberenstein1957]

@inimaz — #1246 has been split into this 4-PR stack for easier review. Benchmarks in the description are measured locally (Mac ARM, 2026-06-21); pre-commit and tests pass on each branch. Please start with #1251.