docs(credits): free tier analyzes 5 tracks a month; 402 plan_limit on POST /api/songs/analyze
Item "free tier: 5 analyze requests per calendar month" of recoupable/app#2061. Contract first; the api PR follows and links here, then app /plan and marketing /pricing show the row. Merge order: this PR → api → app + marketing.
What changes
credits.mdx: plan table gains Tracks analyzed a month (Free 5, Starter and Pro Unlimited); new Analyze limits section under Task limits with the 402 body; the credits sample and prose carryanalyze_limit; the Music analysis cost row points at the cap.accounts.json:AccountCreditsResponsegainsanalyze_limit(integer, nullable). The schema was also missingplan,task_limitandmin_cadence_minutes, which the live response andcredits.mdxalready carried; added so the schema matches what the api returns.releases.json:POST /api/songs/analyze402 becomes aoneOfof the newAnalyzePlanLimitErrorand the existingSongAnalyzeInsufficientCreditsResponse, with a named example of each; the description says the plan check runs first.
The rule the api will implement
A track is counted once by its audio_url among the month's Modal charges (UTC calendar month). So full_report (13 model calls) is one track, and re-analyzing a track already analyzed this month costs credits but does not use a slot. Free gets 5; Starter, Pro, org-backed and enterprise accounts are uncapped (analyze_limit: null). No new table: the count is a distinct-resource_url query over usage_events.
Additive edits at brace boundaries in both JSON files; both re-parsed. Local Mintlify render + screenshots in the comment below.
🤖 Generated with Claude Code
https://claude.ai/code/session_0194KNv9zWevLUxi84wPs2TN
Summary by cubic
Documents the free-tier cap of 5 analyzed tracks per calendar month for POST /api/songs/analyze, including the new 402 plan_limit response. Contract first for the free-tier item in recoupable/app#2061; the API PR follows.
What changed
credits.mdxadds a "Tracks analyzed a month" plan row (Free 5, Starter and Pro unlimited) and an "Analyze limits" section with the 402 example.- A track counts once by
audio_url; re-analyzing a track costs credits but uses no slot, and the plan check runs before the credit check or model call. accounts.jsonaddsanalyze_limitplusplan,task_limit, andmin_cadence_minutesas required fields on the credits response; null means uncapped.releases.jsonturns the analyze 402 into aoneOfof the newAnalyzePlanLimitErrorand the existing insufficient-credits response; the error'splanis alwaysfreesince Starter and Pro are uncapped.
Summary by CodeRabbit
-
New Features
- Account balance responses now include subscription plan details, scheduled-task limits, minimum task cadence, and monthly analysis limits.
- Music analysis now reports plan-limit errors separately from insufficient-credit errors, with clearer response details.
-
Documentation
- Documented monthly track-analysis quotas: Free plans include 5 tracks per calendar month, while Starter and Pro plans are unlimited.
- Added details about how analyzed tracks are counted and the related HTTP 402 response.