feat(ptu): surface PTU flat cost on the daily activity read path

[yucheng-berri]

TLDR

Problem this solves:

• The flat cost the rollup writes is not visible anywhere yet
• Sentinel rollup rows must not pollute the per-key or per-provider breakdowns

How it solves it:

• Aggregate ptu_flat_cost into SpendMetrics.flat_cost and total_flat_cost
• Sentinel rows add to parent totals only, never appear as a key

Relevant issues

Linear ticket

Resolves LIT-4077

Pre-Submission checklist

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review

Screenshots / Proof of Fix

Captured live against a proxy on this branch (commit 7ead5b8), real DB, no mocks.

Rebased onto litellm_internal_staging at f6587fa on 2026-08-06, which had moved 441 commits past the original branch point. The whole matrix below was re-run against the rebased head on a live proxy and a real Postgres, so nothing here is carried over from the pre-rebase run

With flat-cost rows and real request rows both present, the response separates them rather than mixing them. Three chat completions went to Gemini 2.5 Flash through a team-scoped key, alongside a 30-day PTU window

GET /team/daily/activity?start_date=2026-07-07&end_date=2026-08-06&page_size=1000
  total_spend        : 0.0056465
  total_flat_cost    : 14880.0
  total_api_requests : 3
  total_tokens       : 2285

  sentinel in api_key breakdown : False
  providers seen                : ['gemini']

The request totals count only the three real calls, so the sentinel rows contribute their flat cost and nothing else. They also stay out of the api_key breakdown, and the provider breakdown holds only the provider that actually served traffic, with no bucket invented for the sentinel's empty provider

The rollup PR wrote a sentinel row of ptu_flat_cost 10 for a team (5 PTU, 2.0/hour, effective from 23:00 so one active hour). With this read path the amount now surfaces on the team daily activity response

GET /team/daily/activity?team_ids=<pr2-proof team>&start_date=2026-07-31&end_date=2026-07-31
-> metadata.total_flat_cost = 10.00

Before this PR the same call returned total_flat_cost 0 because the read path did not read the column. This is the third of a stack; the UI that renders it lands in a follow-up PR

Live run 2026-08-08, commit 8704e38

Ten sentinel rows worth $6,260.00 in LiteLLM_DailyTeamSpend, plus one real Gemini request so request spend and flat cost are both present

GET /team/daily/activity?start_date=2026-08-01&end_date=2026-08-08&page_size=1000

metadata.total_flat_cost   6260.0        matches the DB sum exactly
metadata.total_spend       0.000062      the real request, kept separate

per day   2026-08-01  720.0
          2026-08-05  720.0
          2026-08-06  740.0   = 720 + 20, two deployments
          2026-08-07  1200.0  = 720 + 480
          2026-08-08  720.0

breakdown.models          {"ptu-prod-renamed": 720.0}   display name, not the deployment UUID
breakdown.api_keys        the __ptu_flat_cost__ sentinel does not appear

page_size=1000 matters: the endpoint paginates and the totals are per page, so a bare curl under-reports and reads as a rollup bug. The dashboard passes 1000 and sums pages itself

Type

New Feature

Changes

update_metrics accumulates ptu_flat_cost into SpendMetrics.flat_cost, and _record_to_spend_metrics reads it on the aggregated path; _build_aggregated_sql_query selects SUM(ptu_flat_cost) only for litellm_dailyteamspend and a constant zero otherwise, so every daily table returns the same shape. DailySpendMetadata gains total_flat_cost, populated from the aggregated totals

update_breakdown_metrics guards every api_key sub-breakdown and the top-level api_keys map with the sentinel check, so the ptu_flat_cost row contributes to parent metrics but never becomes a key row; the provider breakdown is skipped entirely for sentinel rows since flat cost is not per-provider request spend. The GROUPING SETS dispatcher applies the same rules: sentinel rows stay out of every api_key sub-breakdown, and because the sentinel has no provider its flat cost is withheld from the provider parent rather than landing under "unknown". The provider bucket itself is still emitted unconditionally, matching the base build: a row predating the api_requests column backfills to all zeroes, and suppressing those would drop a provider the previous build reported

Screens

Flat cost reaching a team's response and rendering alongside request spend, with the sentinel absent from the key breakdown:

Same build, tag usage: the shared response still carries the field at 0.0 and the view renders neither tile, so a non-team consumer sees no change:

Sentinel rows display their model name

The row keys on the deployment id so a rename cannot move it, and the per-model breakdown
is rendered directly as a label by the Usage page and the daily_with_models export, so the
read path keys a sentinel row on model_group. Two deployments sharing a public name merge
under it, which is the collapse the write path used to do by summing them into one row.
Request rows are untouched. Verified through a four-pod proxy, where the breakdown labels
came back as ptu-a and ptu-renamed rather than UUIDs

Behavior changes

flat_cost and total_flat_cost are added to the shared SpendMetrics and DailySpendMetadata, so every daily activity endpoint returns them, defaulting to 0.0 where no PTU cost exists. This mirrors how compression_saved_tokens and prompt_caching_savings_spend were added to the same models in #33810; the fields are additive and no existing value or status code changes. The per-request api_keys sets used to seed key metadata exclude the sentinel string as well

On the aggregated GROUPING SETS path a team whose only rows for a day are PTU sentinels can now show an unknown provider bucket with flat_cost 0, spend 0 and 0 requests. The sentinel carries no provider, and by the time the provider grouping set is aggregated the api_key column has been grouped away, so a sentinel row cannot be told apart from a genuine row that simply has no provider. Suppressing the bucket by checking for request activity was tried and reverted: rows predating the api_requests column backfill to all zeroes, so that check silently dropped provider buckets the previous build reported. An empty bucket is the lesser cost, and no flat cost is ever credited to a provider on either path. The per-row path skips sentinel rows outright and so shows no such bucket; the two paths differ only in this empty entry

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

---

---

Note

Medium Risk
Changes billing/analytics response semantics and breakdown rules for sentinel rows; incorrect handling could misreport spend or leak fake API keys in breakdowns on some aggregation paths.

Overview
Daily spend analytics now expose PTU flat cost alongside token spend: SpendMetrics gains flat_cost, and response metadata includes total_flat_cost.

The read path pulls ptu_flat_cost from LiteLLM_DailyTeamSpend (other daily tables return zero so the shape stays consistent). Aggregation maps that into flat_cost on totals and per-date metrics.

Rows keyed with PTU_SENTINEL_API_KEY (__ptu_flat_cost__) still roll their flat cost into parent buckets (e.g. model totals) but are excluded from per-api-key breakdowns, the top-level api_keys map, and provider breakdown; metadata lookups also skip the sentinel string. Dashboard OpenAPI types pick up the new fields.

^{Reviewed by Cursor Bugbot for commit 6f888e3. Bugbot is set up for automated code reviews on this repo. Configure here.}

[devin-ai-integration]

Devin Review found 2 potential issues.

View 1 additional finding in Devin Review.

[devin-ai-integration]

🟡 Explanatory prose comments added where the repository forbids them

Multi-line narrative comments are added to explain rationale (# A PTU sentinel row keys on the deployment id ... at litellm/proxy/management_endpoints/common_daily_activity.py:221-224) even though the repository's coding guidelines only permit comments that are strictly necessary, tool-directed, or TODO/FIXME, so the code carries prose that must be kept in sync with the logic.
Impact: Future edits can silently leave these explanations stale, which is exactly the maintenance cost the rule exists to prevent.

Where the rule is violated

CLAUDE.md (referenced as mandatory from AGENTS.md) states comments should only exist when "absolutely necessary to explain some very complex business logic (in which case, keep it concise and clear)", as a tool suppression, or as a TODO/FIXME. The PR adds three narrative blocks: litellm/proxy/management_endpoints/common_daily_activity.py:221-224 (why the sentinel keys on model_group), litellm/proxy/management_endpoints/common_daily_activity.py:621-623 (why only the team table sums the column), and litellm/proxy/management_endpoints/common_daily_activity.py:890-895 (why the flat cost is withheld from the provider bucket). The # mutable-ok: pydantic update payload suppression on line 896 is allowed; the surrounding prose is not.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[greptile-apps]

Greptile Summary

This PR surfaces PTU flat costs in daily activity responses while keeping sentinel data out of request-oriented breakdowns

• Adds flat-cost fields to shared spend metrics, response metadata, and generated dashboard types
• Aggregates team PTU flat cost into daily and grand totals
• Excludes PTU sentinel keys from API-key metadata and nested key breakdowns
• Prevents sentinel flat cost from being attributed to provider buckets
• Adds focused coverage for paginated and grouping-set aggregation behavior

Confidence Score: 5/5

The PR appears safe to merge

No blocking failure remains

Important Files Changed

Filename	Overview
litellm/proxy/management_endpoints/common_daily_activity.py	Reads and aggregates PTU flat cost while excluding sentinel rows from API-key and provider attribution; the previously reported provider pollution is resolved
litellm/types/proxy/management_endpoints/common_daily_activity.py	Adds backward-compatible defaulted flat-cost fields to daily activity response models
tests/test_litellm/proxy/management_endpoints/test_common_daily_activity.py	Adds focused tests for flat-cost accumulation, sentinel filtering, provider attribution, and model labels
ui/litellm-dashboard/src/lib/http/schema.d.ts	Updates generated dashboard API declarations with the new flat-cost fields

_{Reviews (18): Last reviewed commit: "feat(ptu): surface PTU flat cost on the ..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[yucheng-berri]

bugbot run

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6f888e3. Configure here.}

[cursor]

Sentinel leaks in grouping-sets path

Medium Severity

This commit wires ptu_flat_cost into the grouping-sets read path and excludes PTU_SENTINEL_API_KEY from key-metadata lookup, but _aggregate_grouping_sets_records_sync still assigns sentinel rows into api_keys, per-model key breakdowns, and provider buckets. Unlike the Python update_breakdown_metrics path, sentinel flat cost can therefore still appear as a fake key and under provider unknown whenever team spend is served through the aggregated query.

Additional Locations (2)

• litellm/proxy/management_endpoints/common_daily_activity.py#L749-L750
• litellm/proxy/management_endpoints/common_daily_activity.py#L893-L894

 

^{Reviewed by Cursor Bugbot for commit 6f888e3. Configure here.}

[yucheng-berri]

@greptileai fixed: the GROUPING SETS dispatcher now excludes the flat-cost sentinel from every api_key breakdown, mirroring the per-row path. Re-review please

[yucheng-berri]

@greptileai rebased onto the updated base; the grouping-sets sentinel guards and read-path coverage are unchanged. Re-review please

[yucheng-berri]

@greptileai rebased onto the updated base with no content change; the grouping-sets sentinel guards and coverage are unchanged. Re-review please

[yucheng-berri]

@greptileai the grouping-sets provider parent no longer attributes sentinel flat cost to "unknown"; provider buckets stay request-only like the per-row path. Re-review please

[yucheng-berri]

@greptileai rebased onto the updated rollup commit; no changes to this PR's own diff. Re-review please

[yucheng-berri]

@greptileai rebased onto the updated rollup commit; this PR's own diff is unchanged from the 5/5 review. Re-review please

[yucheng-berri]

@greptileai review

[yucheng-berri]

@greptileai review

[yucheng-berri]

@greptileai review

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_ptu_read_path (65b0efc) with litellm_internal_staging (f6b9518)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (61218f5) during the generation of this report, so f6b9518 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩