@mendable/firecrawl 4.2.0 → 4.3.0

package/dist/{chunk-MKEZ44MR.js → chunk-KCQFB5LN.js}

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       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",

package/dist/index.cjs

@@ -35,7 +35,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       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",
@@ -740,7 +740,12 @@ async function getCreditUsage(http) {
     const res = await http.get("/v2/team/credit-usage");
     if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get credit usage");
     const d = res.data.data || res.data;
-    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) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "get credit usage");
     throw err;
@@ -750,7 +755,13 @@ async function getTokenUsage(http) {
   try {
     const res = await http.get("/v2/team/token-usage");
     if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get token usage");
-    return res.data.data || res.data;
+    const d = res.data.data || res.data;
+    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) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "get token usage");
     throw err;
@@ -766,6 +777,28 @@ async function getQueueStatus(http) {
     throw err;
   }
 }
+async function getCreditUsageHistorical(http, byApiKey) {
+  try {
+    const query = byApiKey ? "?byApiKey=true" : "";
+    const res = await http.get(`/v2/team/credit-usage/historical${query}`);
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get credit usage historical");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get credit usage historical");
+    throw err;
+  }
+}
+async function getTokenUsageHistorical(http, byApiKey) {
+  try {
+    const query = byApiKey ? "?byApiKey=true" : "";
+    const res = await http.get(`/v2/team/token-usage/historical${query}`);
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get token usage historical");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get token usage historical");
+    throw err;
+  }
+}
 
 // src/v2/watcher.ts
 var import_events = require("events");
@@ -1073,6 +1106,14 @@ var FirecrawlClient = class {
   async getTokenUsage() {
     return getTokenUsage(this.http);
   }
+  /** Historical credit usage by month; set byApiKey to true to break down by API key. */
+  async getCreditUsageHistorical(byApiKey) {
+    return getCreditUsageHistorical(this.http, byApiKey);
+  }
+  /** Historical token usage by month; set byApiKey to true to break down by API key. */
+  async getTokenUsageHistorical(byApiKey) {
+    return getTokenUsageHistorical(this.http, byApiKey);
+  }
   /** Metrics about the team's scrape queue. */
   async getQueueStatus() {
     return getQueueStatus(this.http);
@@ -2348,6 +2389,98 @@ var FirecrawlApp = class {
     }
     return { success: false, error: "Internal server error." };
   }
+  /**
+   * Gets current credit usage and billing period for the team (v1).
+   */
+  async getCreditUsage() {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.getRequest(
+        `${this.apiUrl}/v1/team/credit-usage`,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get credit usage");
+      }
+    } catch (error) {
+      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() {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.getRequest(
+        `${this.apiUrl}/v1/team/token-usage`,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get token usage");
+      }
+    } catch (error) {
+      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) {
+    const headers = this.prepareHeaders();
+    try {
+      const url = `${this.apiUrl}/v1/team/credit-usage/historical${byApiKey ? "?byApiKey=true" : ""}`;
+      const response = await this.getRequest(url, headers);
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get credit usage historical");
+      }
+    } catch (error) {
+      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) {
+    const headers = this.prepareHeaders();
+    try {
+      const url = `${this.apiUrl}/v1/team/token-usage/historical${byApiKey ? "?byApiKey=true" : ""}`;
+      const response = await this.getRequest(url, headers);
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get token usage historical");
+      }
+    } catch (error) {
+      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." };
+  }
 };
 var CrawlWatcher = class extends e {
   ws;

package/dist/index.d.cts

@@ -288,9 +288,35 @@ interface ConcurrencyCheck {
 }
 interface CreditUsage {
     remainingCredits: number;
+    planCredits?: number;
+    billingPeriodStart?: string | null;
+    billingPeriodEnd?: string | null;
 }
 interface TokenUsage {
     remainingTokens: number;
+    planTokens?: number;
+    billingPeriodStart?: string | null;
+    billingPeriodEnd?: string | null;
+}
+interface CreditUsageHistoricalPeriod {
+    startDate: string | null;
+    endDate: string | null;
+    apiKey?: string;
+    creditsUsed: number;
+}
+interface CreditUsageHistoricalResponse {
+    success: boolean;
+    periods: CreditUsageHistoricalPeriod[];
+}
+interface TokenUsageHistoricalPeriod {
+    startDate: string | null;
+    endDate: string | null;
+    apiKey?: string;
+    tokensUsed: number;
+}
+interface TokenUsageHistoricalResponse {
+    success: boolean;
+    periods: TokenUsageHistoricalPeriod[];
 }
 interface CrawlErrorsResponse$1 {
     errors: {
@@ -552,6 +578,10 @@ declare class FirecrawlClient {
     getCreditUsage(): Promise<CreditUsage>;
     /** Recent token usage. */
     getTokenUsage(): Promise<TokenUsage>;
+    /** Historical credit usage by month; set byApiKey to true to break down by API key. */
+    getCreditUsageHistorical(byApiKey?: boolean): Promise<CreditUsageHistoricalResponse>;
+    /** Historical token usage by month; set byApiKey to true to break down by API key. */
+    getTokenUsageHistorical(byApiKey?: boolean): Promise<TokenUsageHistoricalResponse>;
     /** Metrics about the team's scrape queue. */
     getQueueStatus(): Promise<QueueStatusResponse$1>;
     /**
@@ -1092,6 +1122,44 @@ interface QueueStatusResponse {
      */
     mostRecentSuccess: string | null;
 }
+/** Credit usage for v1 API (snake_case fields as returned by API). */
+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). */
+interface TokenUsageResponseV1 {
+    success: boolean;
+    data: {
+        remaining_tokens: number;
+        plan_tokens: number;
+        billing_period_start: string | null;
+        billing_period_end: string | null;
+    };
+}
+interface CreditUsageHistoricalResponseV1 {
+    success: boolean;
+    periods: {
+        startDate: string | null;
+        endDate: string | null;
+        apiKey?: string;
+        creditsUsed: number;
+    }[];
+}
+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.
@@ -1362,6 +1430,22 @@ declare class FirecrawlApp {
      * @returns The current queue status.
      */
     getQueueStatus(): Promise<QueueStatusResponse | ErrorResponse>;
+    /**
+     * Gets current credit usage and billing period for the team (v1).
+     */
+    getCreditUsage(): Promise<CreditUsageResponseV1 | ErrorResponse>;
+    /**
+     * Gets current token usage and billing period for the team (v1).
+     */
+    getTokenUsage(): Promise<TokenUsageResponseV1 | ErrorResponse>;
+    /**
+     * Gets historical credit usage. Pass byApiKey=true to break down by API key.
+     */
+    getCreditUsageHistorical(byApiKey?: boolean): Promise<CreditUsageHistoricalResponseV1 | ErrorResponse>;
+    /**
+     * Gets historical token usage. Pass byApiKey=true to break down by API key.
+     */
+    getTokenUsageHistorical(byApiKey?: boolean): Promise<TokenUsageHistoricalResponseV1 | ErrorResponse>;
 }
 interface CrawlWatcherEvents {
     document: CustomEvent<FirecrawlDocument<undefined>>;
@@ -1403,4 +1487,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type JsonFormat, type LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type JsonFormat, type LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.d.ts

@@ -288,9 +288,35 @@ interface ConcurrencyCheck {
 }
 interface CreditUsage {
     remainingCredits: number;
+    planCredits?: number;
+    billingPeriodStart?: string | null;
+    billingPeriodEnd?: string | null;
 }
 interface TokenUsage {
     remainingTokens: number;
+    planTokens?: number;
+    billingPeriodStart?: string | null;
+    billingPeriodEnd?: string | null;
+}
+interface CreditUsageHistoricalPeriod {
+    startDate: string | null;
+    endDate: string | null;
+    apiKey?: string;
+    creditsUsed: number;
+}
+interface CreditUsageHistoricalResponse {
+    success: boolean;
+    periods: CreditUsageHistoricalPeriod[];
+}
+interface TokenUsageHistoricalPeriod {
+    startDate: string | null;
+    endDate: string | null;
+    apiKey?: string;
+    tokensUsed: number;
+}
+interface TokenUsageHistoricalResponse {
+    success: boolean;
+    periods: TokenUsageHistoricalPeriod[];
 }
 interface CrawlErrorsResponse$1 {
     errors: {
@@ -552,6 +578,10 @@ declare class FirecrawlClient {
     getCreditUsage(): Promise<CreditUsage>;
     /** Recent token usage. */
     getTokenUsage(): Promise<TokenUsage>;
+    /** Historical credit usage by month; set byApiKey to true to break down by API key. */
+    getCreditUsageHistorical(byApiKey?: boolean): Promise<CreditUsageHistoricalResponse>;
+    /** Historical token usage by month; set byApiKey to true to break down by API key. */
+    getTokenUsageHistorical(byApiKey?: boolean): Promise<TokenUsageHistoricalResponse>;
     /** Metrics about the team's scrape queue. */
     getQueueStatus(): Promise<QueueStatusResponse$1>;
     /**
@@ -1092,6 +1122,44 @@ interface QueueStatusResponse {
      */
     mostRecentSuccess: string | null;
 }
+/** Credit usage for v1 API (snake_case fields as returned by API). */
+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). */
+interface TokenUsageResponseV1 {
+    success: boolean;
+    data: {
+        remaining_tokens: number;
+        plan_tokens: number;
+        billing_period_start: string | null;
+        billing_period_end: string | null;
+    };
+}
+interface CreditUsageHistoricalResponseV1 {
+    success: boolean;
+    periods: {
+        startDate: string | null;
+        endDate: string | null;
+        apiKey?: string;
+        creditsUsed: number;
+    }[];
+}
+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.
@@ -1362,6 +1430,22 @@ declare class FirecrawlApp {
      * @returns The current queue status.
      */
     getQueueStatus(): Promise<QueueStatusResponse | ErrorResponse>;
+    /**
+     * Gets current credit usage and billing period for the team (v1).
+     */
+    getCreditUsage(): Promise<CreditUsageResponseV1 | ErrorResponse>;
+    /**
+     * Gets current token usage and billing period for the team (v1).
+     */
+    getTokenUsage(): Promise<TokenUsageResponseV1 | ErrorResponse>;
+    /**
+     * Gets historical credit usage. Pass byApiKey=true to break down by API key.
+     */
+    getCreditUsageHistorical(byApiKey?: boolean): Promise<CreditUsageHistoricalResponseV1 | ErrorResponse>;
+    /**
+     * Gets historical token usage. Pass byApiKey=true to break down by API key.
+     */
+    getTokenUsageHistorical(byApiKey?: boolean): Promise<TokenUsageHistoricalResponseV1 | ErrorResponse>;
 }
 interface CrawlWatcherEvents {
     document: CustomEvent<FirecrawlDocument<undefined>>;
@@ -1403,4 +1487,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type JsonFormat, type LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AttributesFormat, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type Document, type DocumentMetadata, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type JsonFormat, type LocationConfig, type MapData, type MapOptions, type PDFAction, type PaginationConfig, type PressAction, type QueueStatusResponse$1 as QueueStatusResponse, type ScrapeAction, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type Viewport, type WaitAction, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-MKEZ44MR.js";
+} from "./chunk-KCQFB5LN.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -624,7 +624,12 @@ async function getCreditUsage(http) {
     const res = await http.get("/v2/team/credit-usage");
     if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get credit usage");
     const d = res.data.data || res.data;
-    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) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "get credit usage");
     throw err;
@@ -634,7 +639,13 @@ async function getTokenUsage(http) {
   try {
     const res = await http.get("/v2/team/token-usage");
     if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get token usage");
-    return res.data.data || res.data;
+    const d = res.data.data || res.data;
+    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) {
     if (err?.isAxiosError) return normalizeAxiosError(err, "get token usage");
     throw err;
@@ -650,6 +661,28 @@ async function getQueueStatus(http) {
     throw err;
   }
 }
+async function getCreditUsageHistorical(http, byApiKey) {
+  try {
+    const query = byApiKey ? "?byApiKey=true" : "";
+    const res = await http.get(`/v2/team/credit-usage/historical${query}`);
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get credit usage historical");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get credit usage historical");
+    throw err;
+  }
+}
+async function getTokenUsageHistorical(http, byApiKey) {
+  try {
+    const query = byApiKey ? "?byApiKey=true" : "";
+    const res = await http.get(`/v2/team/token-usage/historical${query}`);
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get token usage historical");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get token usage historical");
+    throw err;
+  }
+}
 
 // src/v2/watcher.ts
 import { EventEmitter } from "events";
@@ -957,6 +990,14 @@ var FirecrawlClient = class {
   async getTokenUsage() {
     return getTokenUsage(this.http);
   }
+  /** Historical credit usage by month; set byApiKey to true to break down by API key. */
+  async getCreditUsageHistorical(byApiKey) {
+    return getCreditUsageHistorical(this.http, byApiKey);
+  }
+  /** Historical token usage by month; set byApiKey to true to break down by API key. */
+  async getTokenUsageHistorical(byApiKey) {
+    return getTokenUsageHistorical(this.http, byApiKey);
+  }
   /** Metrics about the team's scrape queue. */
   async getQueueStatus() {
     return getQueueStatus(this.http);
@@ -1006,7 +1047,7 @@ var FirecrawlApp = class {
       if (typeof process !== "undefined" && process.env && process.env.npm_package_version) {
         return process.env.npm_package_version;
       }
-      const packageJson = await import("./package-7YDUGTZ6.js");
+      const packageJson = await import("./package-QFGMHRQZ.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);
@@ -2232,6 +2273,98 @@ var FirecrawlApp = class {
     }
     return { success: false, error: "Internal server error." };
   }
+  /**
+   * Gets current credit usage and billing period for the team (v1).
+   */
+  async getCreditUsage() {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.getRequest(
+        `${this.apiUrl}/v1/team/credit-usage`,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get credit usage");
+      }
+    } catch (error) {
+      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() {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.getRequest(
+        `${this.apiUrl}/v1/team/token-usage`,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get token usage");
+      }
+    } catch (error) {
+      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) {
+    const headers = this.prepareHeaders();
+    try {
+      const url = `${this.apiUrl}/v1/team/credit-usage/historical${byApiKey ? "?byApiKey=true" : ""}`;
+      const response = await this.getRequest(url, headers);
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get credit usage historical");
+      }
+    } catch (error) {
+      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) {
+    const headers = this.prepareHeaders();
+    try {
+      const url = `${this.apiUrl}/v1/team/token-usage/historical${byApiKey ? "?byApiKey=true" : ""}`;
+      const response = await this.getRequest(url, headers);
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get token usage historical");
+      }
+    } catch (error) {
+      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." };
+  }
 };
 var CrawlWatcher = class extends e {
   ws;

package/dist/{package-7YDUGTZ6.js → package-QFGMHRQZ.js}

@@ -1,4 +1,4 @@
 import {
   require_package
-} from "./chunk-MKEZ44MR.js";
+} from "./chunk-KCQFB5LN.js";
 export default require_package();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "JavaScript SDK for Firecrawl API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/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 {

package/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);

package/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;
+  }
+}

package/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 {