firecrawl 4.1.0 → 4.3.0

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

@@ -8,7 +8,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.1.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.1.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,12 +755,50 @@ 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;
   }
 }
+async function getQueueStatus(http) {
+  try {
+    const res = await http.get("/v2/team/queue-status");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get queue status");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get queue status");
+    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");
@@ -1063,6 +1106,18 @@ 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);
+  }
   // Watcher
   /**
    * Create a watcher for a crawl or batch job. Emits: `document`, `snapshot`, `done`, `error`.
@@ -2309,6 +2364,123 @@ var FirecrawlApp = class {
     }
     return { success: false, error: "Internal server error." };
   }
+  /**
+   * Gets metrics about the team's scrape queue.
+   * @returns The current queue status.
+   */
+  async getQueueStatus() {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.getRequest(
+        `${this.apiUrl}/v1/team/queue-status`,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get queue status");
+      }
+    } 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 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: {
@@ -324,6 +350,14 @@ declare class SdkError extends Error {
     details?: unknown;
     constructor(message: string, status?: number, code?: string, details?: unknown);
 }
+interface QueueStatusResponse$1 {
+    success: boolean;
+    jobsInQueue: number;
+    activeJobsInQueue: number;
+    waitingJobsInQueue: number;
+    maxConcurrency: number;
+    mostRecentSuccess: string | null;
+}
 
 interface HttpClientOptions {
     apiKey: string;
@@ -544,6 +578,12 @@ 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>;
     /**
      * Create a watcher for a crawl or batch job. Emits: `document`, `snapshot`, `done`, `error`.
      * @param jobId Job id.
@@ -1068,6 +1108,58 @@ interface GenerateLLMsTextStatusResponse {
     error?: string;
     expiresAt: string;
 }
+/**
+ * Response interface for queue status operations.
+ */
+interface QueueStatusResponse {
+    success: boolean;
+    jobsInQueue: number;
+    activeJobsInQueue: number;
+    waitingJobsInQueue: number;
+    maxConcurrency: number;
+    /**
+     * ISO timestamp of the most recent successful scrape in the past 24 hours. Will be null if no successful scrape has occurred in the past 24 hours.
+     */
+    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.
@@ -1251,7 +1343,7 @@ declare class FirecrawlApp {
      * @param {AxiosResponse} response - The response from the API.
      * @param {string} action - The action being performed when the error occurred.
      */
-    handleError(response: AxiosResponse, action: string): void;
+    handleError(response: AxiosResponse, action: string): never;
     /**
      * Initiates a deep research operation on a given query and polls until completion.
      * @param query - The query to research.
@@ -1333,6 +1425,27 @@ declare class FirecrawlApp {
      * @returns The current status and results of the generation operation.
      */
     checkGenerateLLMsTextStatus(id: string): Promise<GenerateLLMsTextStatusResponse | ErrorResponse>;
+    /**
+     * Gets metrics about the team's scrape queue.
+     * @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>>;
@@ -1374,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 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: {
@@ -324,6 +350,14 @@ declare class SdkError extends Error {
     details?: unknown;
     constructor(message: string, status?: number, code?: string, details?: unknown);
 }
+interface QueueStatusResponse$1 {
+    success: boolean;
+    jobsInQueue: number;
+    activeJobsInQueue: number;
+    waitingJobsInQueue: number;
+    maxConcurrency: number;
+    mostRecentSuccess: string | null;
+}
 
 interface HttpClientOptions {
     apiKey: string;
@@ -544,6 +578,12 @@ 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>;
     /**
      * Create a watcher for a crawl or batch job. Emits: `document`, `snapshot`, `done`, `error`.
      * @param jobId Job id.
@@ -1068,6 +1108,58 @@ interface GenerateLLMsTextStatusResponse {
     error?: string;
     expiresAt: string;
 }
+/**
+ * Response interface for queue status operations.
+ */
+interface QueueStatusResponse {
+    success: boolean;
+    jobsInQueue: number;
+    activeJobsInQueue: number;
+    waitingJobsInQueue: number;
+    maxConcurrency: number;
+    /**
+     * ISO timestamp of the most recent successful scrape in the past 24 hours. Will be null if no successful scrape has occurred in the past 24 hours.
+     */
+    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.
@@ -1251,7 +1343,7 @@ declare class FirecrawlApp {
      * @param {AxiosResponse} response - The response from the API.
      * @param {string} action - The action being performed when the error occurred.
      */
-    handleError(response: AxiosResponse, action: string): void;
+    handleError(response: AxiosResponse, action: string): never;
     /**
      * Initiates a deep research operation on a given query and polls until completion.
      * @param query - The query to research.
@@ -1333,6 +1425,27 @@ declare class FirecrawlApp {
      * @returns The current status and results of the generation operation.
      */
     checkGenerateLLMsTextStatus(id: string): Promise<GenerateLLMsTextStatusResponse | ErrorResponse>;
+    /**
+     * Gets metrics about the team's scrape queue.
+     * @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>>;
@@ -1374,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 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-EX7LNARR.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,12 +639,50 @@ 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;
   }
 }
+async function getQueueStatus(http) {
+  try {
+    const res = await http.get("/v2/team/queue-status");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get queue status");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get queue status");
+    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";
@@ -947,6 +990,18 @@ 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);
+  }
   // Watcher
   /**
    * Create a watcher for a crawl or batch job. Emits: `document`, `snapshot`, `done`, `error`.
@@ -992,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-MVCQF4ZJ.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);
@@ -2193,6 +2248,123 @@ var FirecrawlApp = class {
     }
     return { success: false, error: "Internal server error." };
   }
+  /**
+   * Gets metrics about the team's scrape queue.
+   * @returns The current queue status.
+   */
+  async getQueueStatus() {
+    const headers = this.prepareHeaders();
+    try {
+      const response = await this.getRequest(
+        `${this.apiUrl}/v1/team/queue-status`,
+        headers
+      );
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get queue status");
+      }
+    } 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 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-MVCQF4ZJ.js → package-QFGMHRQZ.js}

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

package/package.json

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

package/src/__tests__/e2e/v2/usage.test.ts

@@ -32,5 +32,13 @@ describe("v2.usage e2e", () => {
     const resp = await client.getTokenUsage();
     expect(typeof resp.remainingTokens).toBe("number");
   }, 60_000);
+
+  test("get_queue_status", async () => {
+    const resp = await client.getQueueStatus();
+    expect(typeof resp.jobsInQueue).toBe("number");
+    expect(typeof resp.activeJobsInQueue).toBe("number");
+    expect(typeof resp.waitingJobsInQueue).toBe("number");
+    expect(typeof resp.maxConcurrency).toBe("number");
+  }, 60_000);
 });
 

package/src/v1/index.ts

@@ -568,6 +568,64 @@ export interface GenerateLLMsTextStatusResponse {
   expiresAt: string;
 }
 
+/**
+ * Response interface for queue status operations.
+ */
+export interface QueueStatusResponse {
+  success: boolean;
+  jobsInQueue: number;
+  activeJobsInQueue: number;
+  waitingJobsInQueue: number;
+  maxConcurrency: number;
+
+  /**
+   * ISO timestamp of the most recent successful scrape in the past 24 hours. Will be null if no successful scrape has occurred in the past 24 hours.
+   */
+  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.
@@ -1586,7 +1644,7 @@ export default class FirecrawlApp {
    * @param {AxiosResponse} response - The response from the API.
    * @param {string} action - The action being performed when the error occurred.
    */
-  handleError(response: AxiosResponse, action: string): void {
+  handleError(response: AxiosResponse, action: string): never {
     if (!response) {
       throw new FirecrawlError(
         `No response received while trying to ${action}. This may be a network error or the server is unreachable.`,
@@ -2027,6 +2085,129 @@ export default class FirecrawlApp {
     }
     return { success: false, error: "Internal server error." };
   }
+
+  /**
+   * Gets metrics about the team's scrape queue.
+   * @returns The current queue status.
+   */
+  async getQueueStatus(): Promise<QueueStatusResponse | ErrorResponse> {
+    const headers = this.prepareHeaders();
+    try {
+      const response: AxiosResponse = await this.getRequest(
+      `${this.apiUrl}/v1/team/queue-status`,
+        headers
+      );
+
+      if (response.status === 200) {
+        return response.data;
+      } else {
+        this.handleError(response, "get queue status");
+      }
+    } 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 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, getTokenUsage } from "./methods/usage";
+import { getConcurrency, getCreditUsage, getQueueStatus, getTokenUsage, getCreditUsageHistorical, getTokenUsageHistorical } from "./methods/usage";
 import type {
   Document,
   ScrapeOptions,
@@ -269,6 +269,21 @@ 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);
+  }
+
   // Watcher
   /**
    * Create a watcher for a crawl or batch job. Emits: `document`, `snapshot`, `done`, `error`.

package/src/v2/methods/usage.ts

@@ -1,4 +1,4 @@
-import type { ConcurrencyCheck, CreditUsage, 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,12 +33,52 @@ 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;
   }
 }
 
+export async function getQueueStatus(http: HttpClient): Promise<QueueStatusResponse> {
+  try {
+    const res = await http.get<QueueStatusResponse>("/v2/team/queue-status");
+    if (res.status !== 200 || !res.data?.success) throwForBadResponse(res, "get queue status");
+    return res.data;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "get queue status");
+    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 {
@@ -388,3 +418,11 @@ export class SdkError extends Error {
   }
 }
 
+export interface QueueStatusResponse {
+  success: boolean;
+  jobsInQueue: number;
+  activeJobsInQueue: number;
+  waitingJobsInQueue: number;
+  maxConcurrency: number;
+  mostRecentSuccess: string | null;
+}