Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
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.yamlindex 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- '@wagmi/[email protected](@wagmi/[email protected](@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected])))([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]([email protected]))([email protected])([email protected]([email protected])([email protected])([email protected])([email protected]))([email protected])':+ '@wagmi/[email protected](@wagmi/[email protected](@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected])))([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]([email protected]))([email protected])([email protected]([email protected])([email protected])([email protected])([email protected]))([email protected])':dependencies:'@base-org/account': 1.1.1([email protected])([email protected])([email protected])([email protected]([email protected]))([email protected])([email protected])'@coinbase/wallet-sdk': 4.3.6([email protected])([email protected])([email protected])([email protected]([email protected]))([email protected])([email protected])'@safe-global/safe-apps-provider': 0.18.6([email protected])([email protected])([email protected])([email protected])'@safe-global/safe-apps-sdk': 9.1.0([email protected])([email protected])([email protected])([email protected])- '@wagmi/core': 2.18.1(@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected]))+ '@wagmi/core': 2.18.1(@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected]))'@walletconnect/ethereum-provider': 2.21.1([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])cbw-sdk: '@coinbase/[email protected]'optionalDependencies:typescript: 5.8.3transitivePeerDependencies:@@ -10245,11 +10245,11 @@ snapshots:- utf-8-validate- zod- '@wagmi/[email protected](@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected]))':+ '@wagmi/[email protected](@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected]))':dependencies:eventemitter3: 5.0.1mipd: 0.0.7([email protected])optionalDependencies:'@tanstack/query-core': 5.83.1@@ -10799,11 +10799,6 @@ snapshots:typescript: 5.8.3zod: 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- abitype: 1.0.8([email protected])([email protected])- 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- abitype: 1.0.8([email protected])([email protected])- ox: 0.8.6([email protected])([email protected])- ws: 8.18.2([email protected])([email protected])- optionalDependencies:- typescript: 5.8.3- transitivePeerDependencies:- - bufferutil- - utf-8-validate- - zod-dependencies:'@noble/curves': 1.9.2@@ -14324,11 +14287,11 @@ snapshots:[email protected](@tanstack/[email protected])(@tanstack/[email protected]([email protected]))([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]([email protected])([email protected])([email protected])([email protected]))([email protected]):dependencies:'@tanstack/react-query': 5.84.1([email protected])- '@wagmi/connectors': 5.9.1(@wagmi/[email protected](@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected])))([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]([email protected]))([email protected])([email protected]([email protected])([email protected])([email protected])([email protected]))([email protected])- '@wagmi/core': 2.18.1(@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected]))+ '@wagmi/connectors': 5.9.1(@wagmi/[email protected](@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected])))([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]([email protected]))([email protected])([email protected]([email protected])([email protected])([email protected])([email protected]))([email protected])+ '@wagmi/core': 2.18.1(@tanstack/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected])([email protected])([email protected])([email protected]))react: 18.3.1use-sync-external-store: 1.4.0([email protected])optionalDependencies:typescript: 5.8.3transitivePeerDependencies:@@ -14531,7 +14494,7 @@ snapshots:[email protected](@tanstack/[email protected])(@tanstack/[email protected]([email protected]))([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]):dependencies:wagmi: 2.16.1(@tanstack/[email protected])(@tanstack/[email protected]([email protected]))([email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]([email protected])([email protected])([email protected])([email protected]))([email protected])zod: 3.25.76transitivePeerDependencies:diff --git a/apps/api/src/controllers/v1/credit-usage-historical.ts b/apps/api/src/controllers/v1/credit-usage-historical.tsnew file mode 100644index 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 filediff --git a/apps/api/src/controllers/v1/credit-usage.ts b/apps/api/src/controllers/v1/credit-usage.tsindex 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.tsnew file mode 100644index 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 filediff --git a/apps/api/src/controllers/v1/token-usage.ts b/apps/api/src/controllers/v1/token-usage.tsindex 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.tsnew file mode 100644index 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 filediff --git a/apps/api/src/controllers/v2/credit-usage.ts b/apps/api/src/controllers/v2/credit-usage.tsindex 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.tsnew file mode 100644index 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 filediff --git a/apps/api/src/controllers/v2/token-usage.ts b/apps/api/src/controllers/v2/token-usage.tsindex 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.tsindex 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.tsindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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<ConcurrencyCheckexport 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<QueueStatusRespothrow 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.tsindex 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/.gitignorenew file mode 100644index 000000000..386c77b22--- /dev/null+++ b/apps/python-sdk/.gitignore@@ -0,0 +1,4 @@+bin+build+include+lib\ No newline at end of filediff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.pyindex 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 projectlogger: logging.Logger = logging.getLogger("firecrawl")diff --git a/apps/python-sdk/firecrawl/v1/client.py b/apps/python-sdk/firecrawl/v1/client.pyindex 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] = Noneerror: 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.pyindex 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.pyindex 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 AsyncHttpClientfrom ...utils.error_handler import handle_response_error-from ...types import ConcurrencyCheck, CreditUsage, TokenUsage+from ...types import ConcurrencyCheck, CreditUsage, TokenUsage, CreditUsageHistoricalResponse, TokenUsageHistoricalResponseasync 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.pyindex 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, TokenUsageHistoricalResponsedef 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.pyindex 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] = Noneclass 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] = Noneclass QueueStatusResponse(BaseModel):"""Metrics about the team's scrape queue."""@@ -493,6 +499,26 @@ class QueueStatusResponse(BaseModel):max_concurrency: intmost_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 typesclass WaitAction(BaseModel):"""Wait action to perform during scraping."""