feat(usage): split credit usage by endpoint and by day

Merged
RA
4d ago
+237-26

firecrawl_credit_usage could only report balance and monthly totals, so an agent asked "what did I spend credits on?" had nothing to answer with. This adds two historical options and states what the tool can and can't break down.

  • byEndpoint: true splits each period by the endpoint that used the credits. Rows carry endpoint (scrape, search, crawl, map, agent, ...). It can't be combined with byApiKey or view: "current".
  • bin: "day" returns one period per UTC day instead of per calendar month. It works with the totals, byApiKey and byEndpoint.
  • The description now says the historical view covers the last 90 days and answers "what and when". It also says the tool can't attribute credits to single jobs, URLs or MCP clients, that each tool's result reports its own cost (creditsUsed, metadata.creditsUsed), and that the dashboard's Usage and Logs pages list usage per job.

Depends on firecrawl/firecrawl#5291, which adds byEndpoint and bin to GET /v2/team/credit-usage/historical. This PR is safe to deploy before it. Whenever the tool uses either option, it sends bin, and that API echoes bin back. If the echo is missing, the API ignored the new parameters, and the tool returns the monthly figures it got plus a notice saying the split or daily periods aren't available yet. It doesn't fail and doesn't pass totals off as a breakdown. Calls without the new options send exactly the requests they sent before.

The output schema adds bin and notice. Contract snapshots were regenerated with UPDATE_CONTRACT_SNAPSHOTS=1; the only change is firecrawl_credit_usage. The smoke test covers the new request shapes, the fallback against an older API, and the new argument errors. pnpm test: 198 passed.

Open in Capy

Summary by cubic

firecrawl_credit_usage now supports byEndpoint and bin: "day" so the historical view can answer what credits were spent on and when, not just monthly totals.

  • byEndpoint: true splits each period by endpoint (scrape, search, crawl, map, agent, ...). It cannot be combined with byApiKey or view: "current".
  • bin: "day" returns one period per UTC day instead of per calendar month, and works with totals, byApiKey, and byEndpoint.
  • When the API doesn't support the new options yet, the tool returns monthly figures plus a notice instead of failing or passing totals off as a breakdown.
  • The description now states the historical view covers the last 90 days and that credits can't be attributed to individual jobs, URLs, or MCP clients, and the README documents the new options.
  • Output schema adds bin and notice; contract snapshots regenerated and smoke tests cover new request shapes, the fallback, and new argument errors.