docs(credits): free tier analyzes 5 tracks a month; 402 plan_limit on POST /api/songs/analyze

SW
2mo ago
+158-5

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 carry analyze_limit; the Music analysis cost row points at the cap.
  • accounts.json: AccountCreditsResponse gains analyze_limit (integer, nullable). The schema was also missing plan, task_limit and min_cadence_minutes, which the live response and credits.mdx already carried; added so the schema matches what the api returns.
  • releases.json: POST /api/songs/analyze 402 becomes a oneOf of the new AnalyzePlanLimitError and the existing SongAnalyzeInsufficientCreditsResponse, 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.mdx adds 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.json adds analyze_limit plus plan, task_limit, and min_cadence_minutes as required fields on the credits response; null means uncapped.
  • releases.json turns the analyze 402 into a oneOf of the new AnalyzePlanLimitError and the existing insufficient-credits response; the error's plan is always free since 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.