Firecrawl MCP Server

Overview Schema Source Related Servers Discussions Admin

Firecrawl credit usage

firecrawl_credit_usage

Read-only

Retrieve your Firecrawl team's current credit balance or 90-day usage history, optionally broken down by endpoint or API key, to track remaining credits and spending.

Instructions

Get the authenticated Firecrawl team's current credit balance or its credit usage over the last 90 days. Use the current view to answer how many credits remain or to check billing-period boundaries. Use the historical view to answer what credits were spent on and when.

The current view returns remainingCredits, planCredits, billingPeriodStart, and billingPeriodEnd. Extra purchased or granted credits can make remainingCredits greater than planCredits. Billing-period dates may be null when the upstream billing provider has no period metadata.

The historical view returns periods sorted by start date with startDate, endDate, and creditsUsed, one per calendar month, or one per UTC day with bin: "day". Set byEndpoint to split each period by the endpoint that used the credits (endpoint: scrape, search, crawl, map, agent, ...), or byApiKey to split it by API key (apiKey). The endpoint split also counts search usage, which the unsplit and per-key figures leave out, so its rows can add up to more. The newest period's endDate can be null. A notice means the requested split or daily periods are not available yet and the periods are monthly figures.

This tool cannot attribute credits to individual jobs, URLs, or MCP clients. Each tool's own result reports what that call used (creditsUsed, or metadata.creditsUsed on scrapes), and the Usage and Logs pages of the Firecrawl dashboard list usage per job.

Input Schema

Name	Required	Description
`bin`	No	Length of each historical period: calendar month (default) or UTC day. When view is omitted, it selects the historical view; it cannot be combined with view "current".
`view`	No	Select current balance or historical usage. Defaults to current.
`byApiKey`	No	Break historical usage down by API key. When view is omitted, true selects the historical view; it cannot be combined with view "current".
`byEndpoint`	No	Break historical usage down by endpoint (scrape, search, crawl, map, agent, ...). When view is omitted, true selects the historical view; it cannot be combined with view "current" or byApiKey.

Output Schema

Name	Required	Description
`bin`	No	Period length the API applied, `month` or `day`; present when the API applied a requested endpoint split or daily periods.
`error`	No	Error message or error object when the call did not succeed.
`notice`	No	Present when the requested split or daily periods are not available yet; the periods are then calendar-month figures.
`periods`	No	Historical periods sorted by start date, each with `startDate`, `endDate`, `creditsUsed`, and `endpoint` or `apiKey` when split.
`success`	No	Whether the API call succeeded.
`planCredits`	No	Credits included in the plan for the period.
`billingPeriodEnd`	No	End of the current billing period; null when the billing provider reports no period.
`remainingCredits`	No	Credits left in the current billing period; can exceed `planCredits` when extra credits were purchased or granted.
`billingPeriodStart`	No	Start of the current billing period; null when the billing provider reports no period.

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.0.2Oct 29, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds substantial behavioral context beyond annotations: returned fields for each view, edge cases (null billing dates, newest endDate null, notice when splits/daily periods unavailable), and a non-obvious discrepancy where the byEndpoint split includes search usage that other figures omit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose and usage, then flows into return details and limitations. Every sentence carries useful information, but it is somewhat long for a tool with only four optional parameters; the density is justified by the edge cases described.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description still explains return values and edge cases (null dates, notice semantics, split discrepancies), and it sets clear expectations about what cannot be attributed. Combined with rich annotations, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents each parameter. The description adds meaning beyond the schema: it explains that byEndpoint counts search usage extra (so rows can add up to more), and that bin selects monthly vs. daily periods. While not exhaustive for all interactions, it adds useful nuance over the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Get the authenticated Firecrawl team's current credit balance or its credit usage over the last 90 days.' It clearly distinguishes between two sub-views (current vs. historical) and their purposes, making it trivial to separate from sibling tools like scrape or crawl.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given: 'Use the current view to answer how many credits remain or to check billing-period boundaries. Use the historical view to answer what credits were spent on and when.' It also states what the tool cannot do and points to alternatives (each tool's own result, dashboard Usage/Logs pages).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.