Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

feat: historical credit/token usage endpoints + more data in existing usage endpoints (#2077)

Gergő Móricz90778e4604a8
diff --git a/apps/api/pnpm-lock.yaml b/apps/api/pnpm-lock.yaml
index 35aa7d735..00d04d88b 100644
--- a/apps/api/pnpm-lock.yaml
+++ b/apps/api/pnpm-lock.yaml
@@ -10203,17 +10203,17 @@ snapshots:
dependencies:
'@types/yargs-parser': 21.0.3
dependencies:
'@safe-global/safe-apps-provider': 0.18.6([email protected])([email protected])([email protected])([email protected])
cbw-sdk: '@coinbase/[email protected]'
optionalDependencies:
typescript: 5.8.3
transitivePeerDependencies:
@@ -10245,11 +10245,11 @@ snapshots:
- utf-8-validate
- zod
dependencies:
eventemitter3: 5.0.1
mipd: 0.0.7([email protected])
optionalDependencies:
'@tanstack/query-core': 5.83.1
@@ -10799,11 +10799,6 @@ snapshots:
typescript: 5.8.3
zod: 3.22.4
- optionalDependencies:
- typescript: 5.8.3
- zod: 3.24.2
-
optionalDependencies:
typescript: 5.8.3
@@ -13219,21 +13214,6 @@ snapshots:
transitivePeerDependencies:
- zod
- dependencies:
- '@adraffy/ens-normalize': 1.11.0
- '@noble/ciphers': 1.3.0
- '@noble/curves': 1.9.6
- '@noble/hashes': 1.8.0
- '@scure/bip32': 1.7.0
- '@scure/bip39': 1.6.0
- eventemitter3: 5.0.1
- optionalDependencies:
- typescript: 5.8.3
- transitivePeerDependencies:
- - zod
-
dependencies:
'@adraffy/ens-normalize': 1.11.0
@@ -14283,23 +14263,6 @@ snapshots:
- utf-8-validate
- zod
- dependencies:
- '@noble/curves': 1.9.2
- '@noble/hashes': 1.8.0
- '@scure/bip32': 1.7.0
- '@scure/bip39': 1.6.0
- optionalDependencies:
- typescript: 5.8.3
- transitivePeerDependencies:
- - bufferutil
- - utf-8-validate
- - zod
-
dependencies:
'@noble/curves': 1.9.2
@@ -14324,11 +14287,11 @@ snapshots:
dependencies:
'@tanstack/react-query': 5.84.1([email protected])
react: 18.3.1
use-sync-external-store: 1.4.0([email protected])
optionalDependencies:
typescript: 5.8.3
transitivePeerDependencies:
@@ -14531,7 +14494,7 @@ snapshots:
dependencies:
zod: 3.25.76
transitivePeerDependencies:
diff --git a/apps/api/src/controllers/v1/credit-usage-historical.ts b/apps/api/src/controllers/v1/credit-usage-historical.ts
new file mode 100644
index 000000000..a5a7be1ce
--- /dev/null
+++ b/apps/api/src/controllers/v1/credit-usage-historical.ts
@@ -0,0 +1,66 @@
+import { Response } from "express";
+import { ErrorResponse, RequestWithAuth } from "./types";
+import { supabase_rr_service } from "../../services/supabase";
+
+interface CreditUsageHistoricalResponse {
+ success: true;
+ periods: {
+ startDate: string | null;
+ endDate: string | null;
+ apiKey?: string;
+ creditsUsed: number;
+ }[];
+}
+
+export async function creditUsageHistoricalController(
+ req: RequestWithAuth,
+ res: Response<CreditUsageHistoricalResponse | ErrorResponse>,
+): Promise<void> {
+ const byApiKey = req.query.byApiKey === "true";
+
+ const { data, error } = await supabase_rr_service.rpc("get_historical_credit_usage_by_api_key_1", {
+ v_team_id: req.auth.team_id,
+ v_is_extract: false,
+ }, { get: true });
+
+ if (error || !data) {
+ throw error ?? new Error("Failed to get historical credit usage");
+ }
+
+ let periods = data.map((period) => ({
+ startDate: period.start_ts,
+ endDate: period.end_ts,
+ apiKey: period.api_key_name,
+ creditsUsed: period.amount,
+ }));
+
+ if (!byApiKey) {
+ periods = periods.reduce((acc, period) => {
+ let preexisting = acc.find((p) => p.startDate === period.startDate && p.endDate === period.endDate);
+ if (preexisting) {
+ preexisting.creditsUsed += period.creditsUsed;
+ } else {
+ let newPeriod = { ...period };
+ delete newPeriod.apiKey;
+ acc.push(newPeriod);
+ }
+ return acc;
+ }, []);
+ }
+
+ periods.sort((a, b) => {
+ const aTime = a.startDate ? Date.parse(a.startDate) : NaN;
+ const bTime = b.startDate ? Date.parse(b.startDate) : NaN;
+ const aNaN = Number.isNaN(aTime);
+ const bNaN = Number.isNaN(bTime);
+ if (aNaN && bNaN) return 0; // both invalid/null -> keep relative order
+ if (aNaN) return 1; // invalid/null goes last
+ if (bNaN) return -1; // invalid/null goes last
+ return aTime - bTime; // ascending by valid timestamps
+ });
+
+ res.json({
+ success: true,
+ periods,
+ });
+}
\ No newline at end of file
diff --git a/apps/api/src/controllers/v1/credit-usage.ts b/apps/api/src/controllers/v1/credit-usage.ts
index 794861a58..d330e6ebc 100644
--- a/apps/api/src/controllers/v1/credit-usage.ts
+++ b/apps/api/src/controllers/v1/credit-usage.ts
@@ -1,46 +1,38 @@
-import { Request, Response } from "express";
-import { RequestWithAuth } from "./types";
+import { Response } from "express";
+import { ErrorResponse, RequestWithAuth } from "./types";
import { getACUCTeam } from "../auth";
-import { logger } from "../../lib/logger";
import { RateLimiterMode } from "../../types";
+interface CreditUsageResponse {
+ success: true;
+ data: {
+ remaining_credits: number;
+ plan_credits: number;
+ billing_period_start: string | null;
+ billing_period_end: string | null;
+ };
+}
+
export async function creditUsageController(
req: RequestWithAuth,
- res: Response,
+ res: Response<CreditUsageResponse | ErrorResponse>,
): Promise<void> {
- try {
- // If we already have the credit usage info from auth, use it
- if (req.acuc) {
- res.json({
- success: true,
- data: {
- remaining_credits: req.acuc.remaining_credits,
- },
- });
- return;
- }
-
- // Otherwise fetch fresh data
- const chunk = await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Scrape);
- if (!chunk) {
- res.status(404).json({
- success: false,
- error: "Could not find credit usage information",
- });
- return;
- }
-
- res.json({
- success: true,
- data: {
- remaining_credits: chunk.remaining_credits,
- },
- });
- } catch (error) {
- logger.error("Error in credit usage controller:", error);
- res.status(500).json({
+ const chunk = req.acuc ?? await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Scrape);
+ if (!chunk) {
+ res.status(404).json({
success: false,
- error: "Internal server error while fetching credit usage",
+ error: "Could not find credit usage information",
});
+ return;
}
+
+ res.json({
+ success: true,
+ data: {
+ remaining_credits: chunk.remaining_credits,
+ plan_credits: chunk.price_credits,
+ billing_period_start: chunk.sub_current_period_start,
+ billing_period_end: chunk.sub_current_period_end,
+ },
+ });
}
diff --git a/apps/api/src/controllers/v1/token-usage-historical.ts b/apps/api/src/controllers/v1/token-usage-historical.ts
new file mode 100644
index 000000000..f1afb48a7
--- /dev/null
+++ b/apps/api/src/controllers/v1/token-usage-historical.ts
@@ -0,0 +1,57 @@
+import { Response } from "express";
+import { ErrorResponse, RequestWithAuth } from "./types";
+import { supabase_rr_service } from "../../services/supabase";
+
+interface TokenUsageHistoricalResponse {
+ success: true;
+ periods: {
+ startDate: string | null;
+ endDate: string | null;
+ apiKey?: string;
+ tokensUsed: number;
+ }[];
+}
+
+export async function tokenUsageHistoricalController(
+ req: RequestWithAuth,
+ res: Response<TokenUsageHistoricalResponse | ErrorResponse>,
+): Promise<void> {
+ const byApiKey = req.query.byApiKey === "true";
+
+ const { data, error } = await supabase_rr_service.rpc("get_historical_credit_usage_by_api_key_1", {
+ v_team_id: req.auth.team_id,
+ v_is_extract: true,
+ }, { get: true });
+
+ if (error || !data) {
+ throw error ?? new Error("Failed to get historical token usage");
+ }
+
+ let periods = data.map((period) => ({
+ startDate: period.start_ts,
+ endDate: period.end_ts,
+ apiKey: period.api_key_name,
+ tokensUsed: period.amount,
+ }));
+
+ if (!byApiKey) {
+ periods = periods.reduce((acc, period) => {
+ let preexisting = acc.find((p) => p.startDate === period.startDate && p.endDate === period.endDate);
+ if (preexisting) {
+ preexisting.tokensUsed += period.tokensUsed;
+ } else {
+ let newPeriod = { ...period };
+ delete newPeriod.apiKey;
+ acc.push(newPeriod);
+ }
+ return acc;
+ }, []);
+ }
+
+ periods.sort((a, b) => new Date(a.startDate).getTime() - new Date(b.startDate).getTime());
+
+ res.json({
+ success: true,
+ periods,
+ });
+}
\ No newline at end of file
diff --git a/apps/api/src/controllers/v1/token-usage.ts b/apps/api/src/controllers/v1/token-usage.ts
index 1e4f6116c..5bd281674 100644
--- a/apps/api/src/controllers/v1/token-usage.ts
+++ b/apps/api/src/controllers/v1/token-usage.ts
@@ -1,46 +1,38 @@
-import { Request, Response } from "express";
-import { RequestWithAuth } from "./types";
-import { getACUC, getACUCTeam } from "../auth";
-import { logger } from "../../lib/logger";
+import { Response } from "express";
+import { ErrorResponse, RequestWithAuth } from "./types";
+import { getACUCTeam } from "../auth";
import { RateLimiterMode } from "../../types";
+interface TokenUsageResponse {
+ success: true;
+ data: {
+ remaining_tokens: number;
+ plan_tokens: number;
+ billing_period_start: string | null;
+ billing_period_end: string | null;
+ };
+}
+
export async function tokenUsageController(
req: RequestWithAuth,
- res: Response,
+ res: Response<TokenUsageResponse | ErrorResponse>,
): Promise<void> {
- try {
- // If we already have the token usage info from auth, use it
- if (req.acuc) {
- res.json({
- success: true,
- data: {
- remaining_tokens: req.acuc.remaining_credits,
- },
- });
- return;
- }
-
- // Otherwise fetch fresh data
- const chunk = await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Extract);
- if (!chunk) {
- res.status(404).json({
- success: false,
- error: "Could not find token usage information",
- });
- return;
- }
-
- res.json({
- success: true,
- data: {
- remaining_tokens: chunk.remaining_credits,
- },
- });
- } catch (error) {
- logger.error("Error in token usage controller:", error);
- res.status(500).json({
+ const chunk = req.acuc ?? await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Extract);
+ if (!chunk) {
+ res.status(404).json({
success: false,
- error: "Internal server error while fetching token usage",
+ error: "Could not find token usage information",
});
+ return;
}
+
+ res.json({
+ success: true,
+ data: {
+ remaining_tokens: chunk.remaining_credits,
+ plan_tokens: chunk.price_credits,
+ billing_period_start: chunk.sub_current_period_start,
+ billing_period_end: chunk.sub_current_period_end,
+ },
+ });
}
diff --git a/apps/api/src/controllers/v2/credit-usage-historical.ts b/apps/api/src/controllers/v2/credit-usage-historical.ts
new file mode 100644
index 000000000..6ecab6948
--- /dev/null
+++ b/apps/api/src/controllers/v2/credit-usage-historical.ts
@@ -0,0 +1,57 @@
+import { Response } from "express";
+import { ErrorResponse, RequestWithAuth } from "./types";
+import { supabase_rr_service } from "../../services/supabase";
+
+interface CreditUsageHistoricalResponse {
+ success: true;
+ periods: {
+ startDate: string | null;
+ endDate: string | null;
+ apiKey?: string;
+ creditsUsed: number;
+ }[];
+}
+
+export async function creditUsageHistoricalController(
+ req: RequestWithAuth,
+ res: Response<CreditUsageHistoricalResponse | ErrorResponse>,
+): Promise<void> {
+ const byApiKey = req.query.byApiKey === "true";
+
+ const { data, error } = await supabase_rr_service.rpc("get_historical_credit_usage_by_api_key_1", {
+ v_team_id: req.auth.team_id,
+ v_is_extract: false,
+ }, { get: true });
+
+ if (error || !data) {
+ throw error ?? new Error("Failed to get historical credit usage");
+ }
+
+ let periods = data.map((period) => ({
+ startDate: period.start_ts,
+ endDate: period.end_ts,
+ apiKey: period.api_key_name,
+ creditsUsed: period.amount,
+ }));
+
+ if (!byApiKey) {
+ periods = periods.reduce((acc, period) => {
+ let preexisting = acc.find((p) => p.startDate === period.startDate && p.endDate === period.endDate);
+ if (preexisting) {
+ preexisting.creditsUsed += period.creditsUsed;
+ } else {
+ let newPeriod = { ...period };
+ delete newPeriod.apiKey;
+ acc.push(newPeriod);
+ }
+ return acc;
+ }, []);
+ }
+
+ periods.sort((a, b) => new Date(a.startDate).getTime() - new Date(b.startDate).getTime());
+
+ res.json({
+ success: true,
+ periods,
+ });
+}
\ No newline at end of file
diff --git a/apps/api/src/controllers/v2/credit-usage.ts b/apps/api/src/controllers/v2/credit-usage.ts
index 0b3f81771..141c9cc77 100644
--- a/apps/api/src/controllers/v2/credit-usage.ts
+++ b/apps/api/src/controllers/v2/credit-usage.ts
@@ -1,46 +1,39 @@
-import { Request, Response } from "express";
-import { RequestWithAuth } from "./types";
+import { Response } from "express";
+import { ErrorResponse, RequestWithAuth } from "./types";
import { getACUCTeam } from "../auth";
-import { logger } from "../../lib/logger";
import { RateLimiterMode } from "../../types";
+interface CreditUsageResponse {
+ success: true;
+ data: {
+ remainingCredits: number;
+ planCredits: number;
+ billingPeriodStart: string | null;
+ billingPeriodEnd: string | null;
+ };
+}
+
export async function creditUsageController(
req: RequestWithAuth,
- res: Response,
+ res: Response<CreditUsageResponse | ErrorResponse>,
): Promise<void> {
- try {
- // If we already have the credit usage info from auth, use it
- if (req.acuc) {
- res.json({
- success: true,
- data: {
- remainingCredits: req.acuc.remaining_credits,
- },
- });
- return;
- }
-
- // Otherwise fetch fresh data
- const chunk = await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Scrape);
- if (!chunk) {
- res.status(404).json({
- success: false,
- error: "Could not find credit usage information",
- });
- return;
- }
+ const chunk = req.acuc ?? await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Scrape);
- res.json({
- success: true,
- data: {
- remainingCredits: chunk.remaining_credits,
- },
- });
- } catch (error) {
- logger.error("Error in credit usage controller:", error);
- res.status(500).json({
+ if (!chunk) {
+ res.status(404).json({
success: false,
- error: "Internal server error while fetching credit usage",
+ error: "Could not find credit usage information",
});
+ return;
}
+
+ res.json({
+ success: true,
+ data: {
+ remainingCredits: chunk.remaining_credits,
+ planCredits: chunk.price_credits,
+ billingPeriodStart: chunk.sub_current_period_start,
+ billingPeriodEnd: chunk.sub_current_period_end,
+ },
+ });
}
diff --git a/apps/api/src/controllers/v2/token-usage-historical.ts b/apps/api/src/controllers/v2/token-usage-historical.ts
new file mode 100644
index 000000000..f1afb48a7
--- /dev/null
+++ b/apps/api/src/controllers/v2/token-usage-historical.ts
@@ -0,0 +1,57 @@
+import { Response } from "express";
+import { ErrorResponse, RequestWithAuth } from "./types";
+import { supabase_rr_service } from "../../services/supabase";
+
+interface TokenUsageHistoricalResponse {
+ success: true;
+ periods: {
+ startDate: string | null;
+ endDate: string | null;
+ apiKey?: string;
+ tokensUsed: number;
+ }[];
+}
+
+export async function tokenUsageHistoricalController(
+ req: RequestWithAuth,
+ res: Response<TokenUsageHistoricalResponse | ErrorResponse>,
+): Promise<void> {
+ const byApiKey = req.query.byApiKey === "true";
+
+ const { data, error } = await supabase_rr_service.rpc("get_historical_credit_usage_by_api_key_1", {
+ v_team_id: req.auth.team_id,
+ v_is_extract: true,
+ }, { get: true });
+
+ if (error || !data) {
+ throw error ?? new Error("Failed to get historical token usage");
+ }
+
+ let periods = data.map((period) => ({
+ startDate: period.start_ts,
+ endDate: period.end_ts,
+ apiKey: period.api_key_name,
+ tokensUsed: period.amount,
+ }));
+
+ if (!byApiKey) {
+ periods = periods.reduce((acc, period) => {
+ let preexisting = acc.find((p) => p.startDate === period.startDate && p.endDate === period.endDate);
+ if (preexisting) {
+ preexisting.tokensUsed += period.tokensUsed;
+ } else {
+ let newPeriod = { ...period };
+ delete newPeriod.apiKey;
+ acc.push(newPeriod);
+ }
+ return acc;
+ }, []);
+ }
+
+ periods.sort((a, b) => new Date(a.startDate).getTime() - new Date(b.startDate).getTime());
+
+ res.json({
+ success: true,
+ periods,
+ });
+}
\ No newline at end of file
diff --git a/apps/api/src/controllers/v2/token-usage.ts b/apps/api/src/controllers/v2/token-usage.ts
index e99d176a8..5136aaf5f 100644
--- a/apps/api/src/controllers/v2/token-usage.ts
+++ b/apps/api/src/controllers/v2/token-usage.ts
@@ -1,46 +1,40 @@
-import { Request, Response } from "express";
-import { RequestWithAuth } from "./types";
+import { Response } from "express";
+import { ErrorResponse, RequestWithAuth } from "./types";
import { getACUC, getACUCTeam } from "../auth";
import { logger } from "../../lib/logger";
import { RateLimiterMode } from "../../types";
+interface TokenUsageResponse {
+ success: true;
+ data: {
+ remainingTokens: number;
+ planTokens: number;
+ billingPeriodStart: string | null;
+ billingPeriodEnd: string | null;
+ };
+}
+
export async function tokenUsageController(
req: RequestWithAuth,
- res: Response,
+ res: Response<TokenUsageResponse | ErrorResponse>,
): Promise<void> {
- try {
- // If we already have the token usage info from auth, use it
- if (req.acuc) {
- res.json({
- success: true,
- data: {
- remainingTokens: req.acuc.remaining_credits,
- },
- });
- return;
- }
-
- // Otherwise fetch fresh data
- const chunk = await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Extract);
- if (!chunk) {
- res.status(404).json({
- success: false,
- error: "Could not find token usage information",
- });
- return;
- }
+ const chunk = req.acuc ?? await getACUCTeam(req.auth.team_id, false, false, RateLimiterMode.Extract);
- res.json({
- success: true,
- data: {
- remainingTokens: chunk.remaining_credits,
- },
- });
- } catch (error) {
- logger.error("Error in token usage controller:", error);
- res.status(500).json({
+ if (!chunk) {
+ res.status(404).json({
success: false,
- error: "Internal server error while fetching token usage",
+ error: "Could not find token usage information",
});
+ return;
}
+
+ res.json({
+ success: true,
+ data: {
+ remainingTokens: chunk.remaining_credits,
+ planTokens: chunk.price_credits,
+ billingPeriodStart: chunk.sub_current_period_start,
+ billingPeriodEnd: chunk.sub_current_period_end,
+ },
+ });
}
diff --git a/apps/api/src/routes/v1.ts b/apps/api/src/routes/v1.ts
index ed04065e7..9e53cd316 100644
--- a/apps/api/src/routes/v1.ts
+++ b/apps/api/src/routes/v1.ts
@@ -34,6 +34,8 @@ import {
} from "./shared";
import { paymentMiddleware } from "x402-express";
import { queueStatusController } from "../controllers/v1/queue-status";
+import { creditUsageHistoricalController } from "../controllers/v1/credit-usage-historical";
+import { tokenUsageHistoricalController } from "../controllers/v1/token-usage-historical";
expressWs(express());
@@ -229,12 +231,24 @@ v1Router.get(
wrap(creditUsageController),
);
+v1Router.get(
+ "/team/credit-usage/historical",
+ authMiddleware(RateLimiterMode.CrawlStatus),
+ wrap(creditUsageHistoricalController),
+);
+
v1Router.get(
"/team/token-usage",
authMiddleware(RateLimiterMode.ExtractStatus),
wrap(tokenUsageController),
);
+v1Router.get(
+ "/team/token-usage/historical",
+ authMiddleware(RateLimiterMode.ExtractStatus),
+ wrap(tokenUsageHistoricalController),
+);
+
v1Router.get(
"/team/queue-status",
authMiddleware(RateLimiterMode.CrawlStatus),
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index 896c3781b..0b5ac063c 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -27,6 +27,8 @@ import {
wrap,
} from "./shared";
import { queueStatusController } from "../controllers/v2/queue-status";
+import { creditUsageHistoricalController } from "../controllers/v2/credit-usage-historical";
+import { tokenUsageHistoricalController } from "../controllers/v2/token-usage-historical";
expressWs(express());
@@ -156,12 +158,24 @@ v2Router.get(
wrap(creditUsageController),
);
+v2Router.get(
+ "/team/credit-usage/historical",
+ authMiddleware(RateLimiterMode.CrawlStatus),
+ wrap(creditUsageHistoricalController),
+);
+
v2Router.get(
"/team/token-usage",
authMiddleware(RateLimiterMode.ExtractStatus),
wrap(tokenUsageController),
);
+v2Router.get(
+ "/team/token-usage/historical",
+ authMiddleware(RateLimiterMode.ExtractStatus),
+ wrap(tokenUsageHistoricalController),
+);
+
v2Router.get(
"/concurrency-check",
authMiddleware(RateLimiterMode.CrawlStatus),
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.json
index 9ea0c158f..d93a78f0d 100644
--- a/apps/js-sdk/firecrawl/package.json
+++ b/apps/js-sdk/firecrawl/package.json
@@ -1,6 +1,6 @@
{
"name": "@mendable/firecrawl-js",
- "version": "4.2.0",
+ "version": "4.3.0",
"description": "JavaScript SDK for Firecrawl API",
"main": "dist/index.js",
"types": "dist/index.d.ts",
diff --git a/apps/js-sdk/firecrawl/src/v1/index.ts b/apps/js-sdk/firecrawl/src/v1/index.ts
index 8b5b4b786..dfa24cd72 100644
--- a/apps/js-sdk/firecrawl/src/v1/index.ts
+++ b/apps/js-sdk/firecrawl/src/v1/index.ts
@@ -584,6 +584,48 @@ export interface QueueStatusResponse {
mostRecentSuccess: string | null;
}
+/** Credit usage for v1 API (snake_case fields as returned by API). */
+export interface CreditUsageResponseV1 {
+ success: boolean;
+ data: {
+ remaining_credits: number;
+ plan_credits: number;
+ billing_period_start: string | null;
+ billing_period_end: string | null;
+ };
+}
+
+/** Token usage for v1 API (snake_case fields as returned by API). */
+export interface TokenUsageResponseV1 {
+ success: boolean;
+ data: {
+ remaining_tokens: number;
+ plan_tokens: number;
+ billing_period_start: string | null;
+ billing_period_end: string | null;
+ };
+}
+
+export interface CreditUsageHistoricalResponseV1 {
+ success: boolean;
+ periods: {
+ startDate: string | null;
+ endDate: string | null;
+ apiKey?: string;
+ creditsUsed: number;
+ }[];
+}
+
+export interface TokenUsageHistoricalResponseV1 {
+ success: boolean;
+ periods: {
+ startDate: string | null;
+ endDate: string | null;
+ apiKey?: string;
+ tokensUsed: number;
+ }[];
+}
+
/**
* Main class for interacting with the Firecrawl API.
* Provides methods for scraping, searching, crawling, and mapping web content.
@@ -2070,6 +2112,102 @@ export default class FirecrawlApp {
}
return { success: false, error: "Internal server error." };
}
+
+ /**
+ * Gets current credit usage and billing period for the team (v1).
+ */
+ async getCreditUsage(): Promise<CreditUsageResponseV1 | ErrorResponse> {
+ const headers = this.prepareHeaders();
+ try {
+ const response: AxiosResponse = await this.getRequest(
+ `${this.apiUrl}/v1/team/credit-usage`,
+ headers
+ );
+ if (response.status === 200) {
+ return response.data as CreditUsageResponseV1;
+ } else {
+ this.handleError(response, "get credit usage");
+ }
+ } catch (error: any) {
+ if (error.response?.data?.error) {
+ throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ''}`, error.response.status);
+ } else {
+ throw new FirecrawlError(error.message, 500);
+ }
+ }
+ return { success: false, error: "Internal server error." };
+ }
+
+ /**
+ * Gets current token usage and billing period for the team (v1).
+ */
+ async getTokenUsage(): Promise<TokenUsageResponseV1 | ErrorResponse> {
+ const headers = this.prepareHeaders();
+ try {
+ const response: AxiosResponse = await this.getRequest(
+ `${this.apiUrl}/v1/team/token-usage`,
+ headers
+ );
+ if (response.status === 200) {
+ return response.data as TokenUsageResponseV1;
+ } else {
+ this.handleError(response, "get token usage");
+ }
+ } catch (error: any) {
+ if (error.response?.data?.error) {
+ throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ''}`, error.response.status);
+ } else {
+ throw new FirecrawlError(error.message, 500);
+ }
+ }
+ return { success: false, error: "Internal server error." };
+ }
+
+ /**
+ * Gets historical credit usage. Pass byApiKey=true to break down by API key.
+ */
+ async getCreditUsageHistorical(byApiKey?: boolean): Promise<CreditUsageHistoricalResponseV1 | ErrorResponse> {
+ const headers = this.prepareHeaders();
+ try {
+ const url = `${this.apiUrl}/v1/team/credit-usage/historical${byApiKey ? "?byApiKey=true" : ""}`;
+ const response: AxiosResponse = await this.getRequest(url, headers);
+ if (response.status === 200) {
+ return response.data as CreditUsageHistoricalResponseV1;
+ } else {
+ this.handleError(response, "get credit usage historical");
+ }
+ } catch (error: any) {
+ if (error.response?.data?.error) {
+ throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ''}`, error.response.status);
+ } else {
+ throw new FirecrawlError(error.message, 500);
+ }
+ }
+ return { success: false, error: "Internal server error." };
+ }
+
+ /**
+ * Gets historical token usage. Pass byApiKey=true to break down by API key.
+ */
+ async getTokenUsageHistorical(byApiKey?: boolean): Promise<TokenUsageHistoricalResponseV1 | ErrorResponse> {
+ const headers = this.prepareHeaders();
+ try {
+ const url = `${this.apiUrl}/v1/team/token-usage/historical${byApiKey ? "?byApiKey=true" : ""}`;
+ const response: AxiosResponse = await this.getRequest(url, headers);
+ if (response.status === 200) {
+ return response.data as TokenUsageHistoricalResponseV1;
+ } else {
+ this.handleError(response, "get token usage historical");
+ }
+ } catch (error: any) {
+ if (error.response?.data?.error) {
+ throw new FirecrawlError(`Request failed with status code ${error.response.status}. Error: ${error.response.data.error} ${error.response.data.details ? ` - ${JSON.stringify(error.response.data.details)}` : ''}`, error.response.status);
+ } else {
+ throw new FirecrawlError(error.message, 500);
+ }
+ }
+ return { success: false, error: "Internal server error." };
+ }
}
interface CrawlWatcherEvents {
diff --git a/apps/js-sdk/firecrawl/src/v2/client.ts b/apps/js-sdk/firecrawl/src/v2/client.ts
index 04f8c2b60..840c38be6 100644
--- a/apps/js-sdk/firecrawl/src/v2/client.ts
+++ b/apps/js-sdk/firecrawl/src/v2/client.ts
@@ -19,7 +19,7 @@ import {
batchScrape as batchWaiter,
} from "./methods/batch";
import { startExtract, getExtractStatus, extract as extractWaiter } from "./methods/extract";
-import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage } from "./methods/usage";
+import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
import type {
Document,
ScrapeOptions,
@@ -269,6 +269,16 @@ export class FirecrawlClient {
return getTokenUsage(this.http);
}
+ /** Historical credit usage by month; set byApiKey to true to break down by API key. */
+ async getCreditUsageHistorical(byApiKey?: boolean) {
+ return getCreditUsageHistorical(this.http, byApiKey);
+ }
+
+ /** Historical token usage by month; set byApiKey to true to break down by API key. */
+ async getTokenUsageHistorical(byApiKey?: boolean) {
+ return getTokenUsageHistorical(this.http, byApiKey);
+ }
+
/** Metrics about the team's scrape queue. */
async getQueueStatus() {
return getQueueStatus(this.http);
diff --git a/apps/js-sdk/firecrawl/src/v2/methods/usage.ts b/apps/js-sdk/firecrawl/src/v2/methods/usage.ts
index a3a471df8..1cbf0896a 100644
--- a/apps/js-sdk/firecrawl/src/v2/methods/usage.ts
+++ b/apps/js-sdk/firecrawl/src/v2/methods/usage.ts
@@ -1,4 +1,4 @@
-import type { ConcurrencyCheck, CreditUsage, QueueStatusResponse, TokenUsage } from "../types";
+import type { ConcurrencyCheck, CreditUsage, QueueStatusResponse, TokenUsage, CreditUsageHistoricalResponse, TokenUsageHistoricalResponse } from "../types";
import { HttpClient } from "../utils/httpClient";
import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";
@@ -16,10 +16,15 @@ export async function getConcurrency(http: HttpClient): Promise<ConcurrencyCheck
export async function getCreditUsage(http: HttpClient): Promise<CreditUsage> {
try {
- const res = await http.get<{ success: boolean; data?: { remainingCredits?: number; remaining_credits?: number } }>("/v2/team/credit-usage");
+ const res = await http.get<{ success: boolean; data?: { remainingCredits?: number; remaining_credits?: number; planCredits?: number; plan_credits?: number; billingPeriodStart?: string | null; billing_period_start?: string | null; billingPeriodEnd?: string | null; billing_period_end?: string | null } }>("/v2/team/credit-usage");
if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get credit usage");
const d = res.data.data || (res.data as any);
- return { remainingCredits: d.remainingCredits ?? d.remaining_credits ?? 0 };
+ return {
+ remainingCredits: d.remainingCredits ?? d.remaining_credits ?? 0,
+ planCredits: d.planCredits ?? d.plan_credits,
+ billingPeriodStart: d.billingPeriodStart ?? d.billing_period_start ?? null,
+ billingPeriodEnd: d.billingPeriodEnd ?? d.billing_period_end ?? null,
+ };
} catch (err: any) {
if (err?.isAxiosError) return normalizeAxiosError(err, "get credit usage");
throw err;
@@ -28,9 +33,15 @@ export async function getCreditUsage(http: HttpClient): Promise<CreditUsage> {
export async function getTokenUsage(http: HttpClient): Promise<TokenUsage> {
try {
- const res = await http.get<{ success: boolean; data?: TokenUsage }>("/v2/team/token-usage");
+ const res = await http.get<{ success: boolean; data?: { remainingTokens?: number; planTokens?: number; billingPeriodStart?: string | null; billingPeriodEnd?: string | null; remaining_tokens?: number; plan_tokens?: number; billing_period_start?: string | null; billing_period_end?: string | null } }>("/v2/team/token-usage");
if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get token usage");
- return (res.data.data || (res.data as any)) as TokenUsage;
+ const d = res.data.data || (res.data as any);
+ return {
+ remainingTokens: d.remainingTokens ?? d.remaining_tokens ?? 0,
+ planTokens: d.planTokens ?? d.plan_tokens,
+ billingPeriodStart: d.billingPeriodStart ?? d.billing_period_start ?? null,
+ billingPeriodEnd: d.billingPeriodEnd ?? d.billing_period_end ?? null,
+ };
} catch (err: any) {
if (err?.isAxiosError) return normalizeAxiosError(err, "get token usage");
throw err;
@@ -47,3 +58,27 @@ export async function getQueueStatus(http: HttpClient): Promise<QueueStatusRespo
throw err;
}
}
+
+export async function getCreditUsageHistorical(http: HttpClient, byApiKey?: boolean): Promise<CreditUsageHistoricalResponse> {
+ try {
+ const query = byApiKey ? "?byApiKey=true" : "";
+ const res = await http.get<CreditUsageHistoricalResponse>(`/v2/team/credit-usage/historical${query}`);
+ if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get credit usage historical");
+ return res.data;
+ } catch (err: any) {
+ if (err?.isAxiosError) return normalizeAxiosError(err, "get credit usage historical");
+ throw err;
+ }
+}
+
+export async function getTokenUsageHistorical(http: HttpClient, byApiKey?: boolean): Promise<TokenUsageHistoricalResponse> {
+ try {
+ const query = byApiKey ? "?byApiKey=true" : "";
+ const res = await http.get<TokenUsageHistoricalResponse>(`/v2/team/token-usage/historical${query}`);
+ if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get token usage historical");
+ return res.data;
+ } catch (err: any) {
+ if (err?.isAxiosError) return normalizeAxiosError(err, "get token usage historical");
+ throw err;
+ }
+}
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index 83bddcf4c..31434a1ff 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -339,10 +339,40 @@ export interface ConcurrencyCheck {
export interface CreditUsage {
remainingCredits: number;
+ planCredits?: number;
+ billingPeriodStart?: string | null;
+ billingPeriodEnd?: string | null;
}
export interface TokenUsage {
remainingTokens: number;
+ planTokens?: number;
+ billingPeriodStart?: string | null;
+ billingPeriodEnd?: string | null;
+}
+
+export interface CreditUsageHistoricalPeriod {
+ startDate: string | null;
+ endDate: string | null;
+ apiKey?: string;
+ creditsUsed: number;
+}
+
+export interface CreditUsageHistoricalResponse {
+ success: boolean;
+ periods: CreditUsageHistoricalPeriod[];
+}
+
+export interface TokenUsageHistoricalPeriod {
+ startDate: string | null;
+ endDate: string | null;
+ apiKey?: string;
+ tokensUsed: number;
+}
+
+export interface TokenUsageHistoricalResponse {
+ success: boolean;
+ periods: TokenUsageHistoricalPeriod[];
}
export interface CrawlErrorsResponse {
diff --git a/apps/python-sdk/.gitignore b/apps/python-sdk/.gitignore
new file mode 100644
index 000000000..386c77b22
--- /dev/null
+++ b/apps/python-sdk/.gitignore
@@ -0,0 +1,4 @@
+bin
+build
+include
+lib
\ No newline at end of file
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.py
index 8c47d7995..f1e621169 100644
--- a/apps/python-sdk/firecrawl/__init__.py
+++ b/apps/python-sdk/firecrawl/__init__.py
@@ -17,7 +17,7 @@ from .v1 import (
V1ChangeTrackingOptions,
)
-__version__ = "4.2.0"
+__version__ = "4.3.0"
# Define the logger for the Firecrawl project
logger: logging.Logger = logging.getLogger("firecrawl")
diff --git a/apps/python-sdk/firecrawl/v1/client.py b/apps/python-sdk/firecrawl/v1/client.py
index 52e328119..b6c94eca2 100644
--- a/apps/python-sdk/firecrawl/v1/client.py
+++ b/apps/python-sdk/firecrawl/v1/client.py
@@ -358,6 +358,46 @@ class V1SearchResponse(pydantic.BaseModel):
warning: Optional[str] = None
error: Optional[str] = None
+class V1CreditUsageData(pydantic.BaseModel):
+ remaining_credits: int
+ plan_credits: Optional[int] = None
+ billing_period_start: Optional[str] = None
+ billing_period_end: Optional[str] = None
+
+class V1CreditUsageResponse(pydantic.BaseModel):
+ success: bool
+ data: V1CreditUsageData
+
+class V1TokenUsageData(pydantic.BaseModel):
+ remaining_tokens: int
+ plan_tokens: Optional[int] = None
+ billing_period_start: Optional[str] = None
+ billing_period_end: Optional[str] = None
+
+class V1TokenUsageResponse(pydantic.BaseModel):
+ success: bool
+ data: V1TokenUsageData
+
+class V1CreditUsageHistoricalPeriod(pydantic.BaseModel):
+ startDate: Optional[str] = None
+ endDate: Optional[str] = None
+ apiKey: Optional[str] = None
+ creditsUsed: int
+
+class V1CreditUsageHistoricalResponse(pydantic.BaseModel):
+ success: bool
+ periods: List[V1CreditUsageHistoricalPeriod]
+
+class V1TokenUsageHistoricalPeriod(pydantic.BaseModel):
+ startDate: Optional[str] = None
+ endDate: Optional[str] = None
+ apiKey: Optional[str] = None
+ tokensUsed: int
+
+class V1TokenUsageHistoricalResponse(pydantic.BaseModel):
+ success: bool
+ periods: List[V1TokenUsageHistoricalPeriod]
+
class V1GenerateLLMsTextParams(pydantic.BaseModel):
"""
Parameters for the LLMs.txt generation operation.
@@ -722,6 +762,90 @@ class V1FirecrawlApp:
else:
self._handle_error(response, 'search')
+ def get_credit_usage(self) -> V1CreditUsageResponse:
+ """Get current credit usage and billing period (v1)."""
+ _headers = self._prepare_headers()
+ response = self._get_request(
+ f"{self.api_url}/v1/team/credit-usage",
+ _headers
+ )
+
+ if response.status_code == 200:
+ try:
+ response_json = response.json()
+ if response_json.get('success') and 'data' in response_json:
+ return V1CreditUsageResponse(**response_json)
+ elif "error" in response_json:
+ raise Exception(f"Failed to get credit usage. Error: {response_json['error']}")
+ else:
+ raise Exception(f"Failed to get credit usage. Error: {response_json}")
+ except ValueError:
+ raise Exception('Failed to parse Firecrawl response as JSON.')
+ else:
+ self._handle_error(response, 'get credit usage')
+
+ def get_token_usage(self) -> V1TokenUsageResponse:
+ """Get current token usage and billing period (v1)."""
+ _headers = self._prepare_headers()
+ response = self._get_request(
+ f"{self.api_url}/v1/team/token-usage",
+ _headers
+ )
+
+ if response.status_code == 200:
+ try:
+ response_json = response.json()
+ if response_json.get('success') and 'data' in response_json:
+ return V1TokenUsageResponse(**response_json)
+ elif "error" in response_json:
+ raise Exception(f"Failed to get token usage. Error: {response_json['error']}")
+ else:
+ raise Exception(f"Failed to get token usage. Error: {response_json}")
+ except ValueError:
+ raise Exception('Failed to parse Firecrawl response as JSON.')
+ else:
+ self._handle_error(response, 'get token usage')
+
+ def get_credit_usage_historical(self, by_api_key: bool = False) -> V1CreditUsageHistoricalResponse:
+ """Get historical credit usage (v1)."""
+ _headers = self._prepare_headers()
+ url = f"{self.api_url}/v1/team/credit-usage/historical" + ("?byApiKey=true" if by_api_key else "")
+ response = self._get_request(url, _headers)
+
+ if response.status_code == 200:
+ try:
+ response_json = response.json()
+ if response_json.get('success') and 'periods' in response_json:
+ return V1CreditUsageHistoricalResponse(**response_json)
+ elif "error" in response_json:
+ raise Exception(f"Failed to get historical credit usage. Error: {response_json['error']}")
+ else:
+ raise Exception(f"Failed to get historical credit usage. Error: {response_json}")
+ except ValueError:
+ raise Exception('Failed to parse Firecrawl response as JSON.')
+ else:
+ self._handle_error(response, 'get credit usage historical')
+
+ def get_token_usage_historical(self, by_api_key: bool = False) -> V1TokenUsageHistoricalResponse:
+ """Get historical token usage (v1)."""
+ _headers = self._prepare_headers()
+ url = f"{self.api_url}/v1/team/token-usage/historical" + ("?byApiKey=true" if by_api_key else "")
+ response = self._get_request(url, _headers)
+
+ if response.status_code == 200:
+ try:
+ response_json = response.json()
+ if response_json.get('success') and 'periods' in response_json:
+ return V1TokenUsageHistoricalResponse(**response_json)
+ elif "error" in response_json:
+ raise Exception(f"Failed to get historical token usage. Error: {response_json['error']}")
+ else:
+ raise Exception(f"Failed to get historical token usage. Error: {response_json}")
+ except ValueError:
+ raise Exception('Failed to parse Firecrawl response as JSON.')
+ else:
+ self._handle_error(response, 'get token usage historical')
+
def crawl_url(
self,
url: str,
@@ -2913,6 +3037,24 @@ class AsyncV1FirecrawlApp(V1FirecrawlApp):
"""
return self._get_error_message(status_code, action, error_message, error_details)
+ async def get_credit_usage(self) -> V1CreditUsageResponse:
+ """Get current credit usage and billing period (v1, async)."""
+ headers = self._prepare_headers()
+ resp = await self._async_get_request(
+ f"{self.api_url}/v1/team/credit-usage",
+ headers
+ )
+ return V1CreditUsageResponse(**resp)
+
+ async def get_token_usage(self) -> V1TokenUsageResponse:
+ """Get current token usage and billing period (v1, async)."""
+ headers = self._prepare_headers()
+ resp = await self._async_get_request(
+ f"{self.api_url}/v1/team/token-usage",
+ headers
+ )
+ return V1TokenUsageResponse(**resp)
+
async def crawl_url_and_watch(
self,
url: str,
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index c97e5089a..5c4e3f867 100644
--- a/apps/python-sdk/firecrawl/v2/client.py
+++ b/apps/python-sdk/firecrawl/v2/client.py
@@ -727,6 +727,14 @@ class FirecrawlClient:
"""Get recent token usage metrics (v2)."""
return usage_methods.get_token_usage(self.http_client)
+ def get_credit_usage_historical(self, by_api_key: bool = False):
+ """Get historical credit usage (v2)."""
+ return usage_methods.get_credit_usage_historical(self.http_client, by_api_key)
+
+ def get_token_usage_historical(self, by_api_key: bool = False):
+ """Get historical token usage (v2)."""
+ return usage_methods.get_token_usage_historical(self.http_client, by_api_key)
+
def get_queue_status(self):
"""Get metrics about the team's scrape queue."""
return usage_methods.get_queue_status(self.http_client)
diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/usage.py b/apps/python-sdk/firecrawl/v2/methods/aio/usage.py
index ceadcb0da..e1c9fb18e 100644
--- a/apps/python-sdk/firecrawl/v2/methods/aio/usage.py
+++ b/apps/python-sdk/firecrawl/v2/methods/aio/usage.py
@@ -1,6 +1,6 @@
from ...utils.http_client_async import AsyncHttpClient
from ...utils.error_handler import handle_response_error
-from ...types import ConcurrencyCheck, CreditUsage, TokenUsage
+from ...types import ConcurrencyCheck, CreditUsage, TokenUsage, CreditUsageHistoricalResponse, TokenUsageHistoricalResponse
async def get_concurrency(client: AsyncHttpClient) -> ConcurrencyCheck:
@@ -25,7 +25,12 @@ async def get_credit_usage(client: AsyncHttpClient) -> CreditUsage:
if not body.get("success"):
raise Exception(body.get("error", "Unknown error"))
data = body.get("data", body)
- return CreditUsage(remaining_credits=data.get("remainingCredits", data.get("remaining_credits", 0)))
+ return CreditUsage(
+ remaining_credits=data.get("remainingCredits", data.get("remaining_credits", 0)),
+ plan_credits=data.get("planCredits", data.get("plan_credits")),
+ billing_period_start=data.get("billingPeriodStart", data.get("billing_period_start")),
+ billing_period_end=data.get("billingPeriodEnd", data.get("billing_period_end")),
+ )
async def get_token_usage(client: AsyncHttpClient) -> TokenUsage:
@@ -37,6 +42,31 @@ async def get_token_usage(client: AsyncHttpClient) -> TokenUsage:
raise Exception(body.get("error", "Unknown error"))
data = body.get("data", body)
return TokenUsage(
- remaining_tokens=data.get("remainingTokens", 0)
+ remaining_tokens=data.get("remainingTokens", data.get("remaining_tokens", 0)),
+ plan_tokens=data.get("planTokens", data.get("plan_tokens")),
+ billing_period_start=data.get("billingPeriodStart", data.get("billing_period_start")),
+ billing_period_end=data.get("billingPeriodEnd", data.get("billing_period_end")),
)
+
+async def get_credit_usage_historical(client: AsyncHttpClient, by_api_key: bool = False) -> CreditUsageHistoricalResponse:
+ query = "?byApiKey=true" if by_api_key else ""
+ resp = await client.get(f"/v2/team/credit-usage/historical{query}")
+ if resp.status_code >= 400:
+ handle_response_error(resp, "get credit usage historical")
+ body = resp.json()
+ if not body.get("success"):
+ raise Exception(body.get("error", "Unknown error"))
+ return CreditUsageHistoricalResponse(**body)
+
+
+async def get_token_usage_historical(client: AsyncHttpClient, by_api_key: bool = False) -> TokenUsageHistoricalResponse:
+ query = "?byApiKey=true" if by_api_key else ""
+ resp = await client.get(f"/v2/team/token-usage/historical{query}")
+ if resp.status_code >= 400:
+ handle_response_error(resp, "get token usage historical")
+ body = resp.json()
+ if not body.get("success"):
+ raise Exception(body.get("error", "Unknown error"))
+ return TokenUsageHistoricalResponse(**body)
+
diff --git a/apps/python-sdk/firecrawl/v2/methods/usage.py b/apps/python-sdk/firecrawl/v2/methods/usage.py
index 418176780..76c8009bd 100644
--- a/apps/python-sdk/firecrawl/v2/methods/usage.py
+++ b/apps/python-sdk/firecrawl/v2/methods/usage.py
@@ -1,5 +1,5 @@
from ..utils import HttpClient, handle_response_error
-from ..types import ConcurrencyCheck, CreditUsage, QueueStatusResponse, TokenUsage
+from ..types import ConcurrencyCheck, CreditUsage, QueueStatusResponse, TokenUsage, CreditUsageHistoricalResponse, TokenUsageHistoricalResponse
def get_concurrency(client: HttpClient) -> ConcurrencyCheck:
@@ -24,7 +24,12 @@ def get_credit_usage(client: HttpClient) -> CreditUsage:
if not body.get("success"):
raise Exception(body.get("error", "Unknown error"))
data = body.get("data", body)
- return CreditUsage(remaining_credits=data.get("remainingCredits", data.get("remaining_credits", 0)))
+ return CreditUsage(
+ remaining_credits=data.get("remainingCredits", data.get("remaining_credits", 0)),
+ plan_credits=data.get("planCredits", data.get("plan_credits")),
+ billing_period_start=data.get("billingPeriodStart", data.get("billing_period_start")),
+ billing_period_end=data.get("billingPeriodEnd", data.get("billing_period_end")),
+ )
def get_token_usage(client: HttpClient) -> TokenUsage:
@@ -36,7 +41,10 @@ def get_token_usage(client: HttpClient) -> TokenUsage:
raise Exception(body.get("error", "Unknown error"))
data = body.get("data", body)
return TokenUsage(
- remaining_tokens=data.get("remainingTokens", 0)
+ remaining_tokens=data.get("remainingTokens", data.get("remaining_tokens", 0)),
+ plan_tokens=data.get("planTokens", data.get("plan_tokens")),
+ billing_period_start=data.get("billingPeriodStart", data.get("billing_period_start")),
+ billing_period_end=data.get("billingPeriodEnd", data.get("billing_period_end")),
)
def get_queue_status(client: HttpClient) -> QueueStatusResponse:
@@ -54,3 +62,23 @@ def get_queue_status(client: HttpClient) -> QueueStatusResponse:
max_concurrency=data.get("maxConcurrency", 0),
most_recent_success=data.get("mostRecentSuccess", None),
)
+
+
+def get_credit_usage_historical(client: HttpClient, by_api_key: bool = False) -> CreditUsageHistoricalResponse:
+ resp = client.get(f"/v2/team/credit-usage/historical{'?byApiKey=true' if by_api_key else ''}")
+ if not resp.ok:
+ handle_response_error(resp, "get credit usage historical")
+ body = resp.json()
+ if not body.get("success"):
+ raise Exception(body.get("error", "Unknown error"))
+ return CreditUsageHistoricalResponse(**body)
+
+
+def get_token_usage_historical(client: HttpClient, by_api_key: bool = False) -> TokenUsageHistoricalResponse:
+ resp = client.get(f"/v2/team/token-usage/historical{'?byApiKey=true' if by_api_key else ''}")
+ if not resp.ok:
+ handle_response_error(resp, "get token usage historical")
+ body = resp.json()
+ if not body.get("success"):
+ raise Exception(body.get("error", "Unknown error"))
+ return TokenUsageHistoricalResponse(**body)
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index f3f613b35..e0a8a2794 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -480,10 +480,16 @@ class ConcurrencyCheck(BaseModel):
class CreditUsage(BaseModel):
"""Remaining credits for the team/API key."""
remaining_credits: int
+ plan_credits: Optional[int] = None
+ billing_period_start: Optional[str] = None
+ billing_period_end: Optional[str] = None
class TokenUsage(BaseModel):
"""Recent token usage metrics (if available)."""
remaining_tokens: int
+ plan_tokens: Optional[int] = None
+ billing_period_start: Optional[str] = None
+ billing_period_end: Optional[str] = None
class QueueStatusResponse(BaseModel):
"""Metrics about the team's scrape queue."""
@@ -493,6 +499,26 @@ class QueueStatusResponse(BaseModel):
max_concurrency: int
most_recent_success: Optional[datetime] = None
+class CreditUsageHistoricalPeriod(BaseModel):
+ startDate: Optional[str] = None
+ endDate: Optional[str] = None
+ apiKey: Optional[str] = None
+ creditsUsed: int
+
+class CreditUsageHistoricalResponse(BaseModel):
+ success: bool
+ periods: List[CreditUsageHistoricalPeriod]
+
+class TokenUsageHistoricalPeriod(BaseModel):
+ startDate: Optional[str] = None
+ endDate: Optional[str] = None
+ apiKey: Optional[str] = None
+ tokensUsed: int
+
+class TokenUsageHistoricalResponse(BaseModel):
+ success: bool
+ periods: List[TokenUsageHistoricalPeriod]
+
# Action types
class WaitAction(BaseModel):
"""Wait action to perform during scraping."""