@mendable/firecrawl-js 4.37.0 → 4.38.0

package/dist/{chunk-LFX7WDGT.js → chunk-KSTNOGOD.js}

@@ -12,7 +12,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.37.0",
+      version: "4.38.0",
       description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",

package/dist/index.cjs

@@ -39,7 +39,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@mendable/firecrawl-js",
-      version: "4.37.0",
+      version: "4.38.0",
       description: "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
       main: "dist/index.js",
       types: "dist/index.d.ts",
@@ -1394,6 +1394,17 @@ async function getAgentStatus(http, jobId) {
     throw err;
   }
 }
+async function listAgents(http, options) {
+  try {
+    const query = options?.before !== void 0 ? `?before=${options.before}` : "";
+    const res = await http.get(`/v2/agent${query}`);
+    if (res.status !== 200) throwForBadResponse(res, "list agents");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "list agents");
+    throw err;
+  }
+}
 async function waitAgent(http, jobId, pollInterval = 2, timeout) {
   const start = Date.now();
   while (true) {
@@ -2415,6 +2426,17 @@ var FirecrawlClient = class {
   async getAgentStatus(jobId) {
     return getAgentStatus(this.http, jobId);
   }
+  /**
+   * List agent runs, most recent first.
+   *
+   * Pages are fixed at 20 runs. To fetch the next page, pass the `before`
+   * value from the previous page's `next` URL. This method does not
+   * auto-paginate.
+   * @param options.before Only return runs created before this unix ms timestamp.
+   */
+  async listAgents(options) {
+    return listAgents(this.http, options);
+  }
   /**
    * Convenience waiter: start an agent and poll until it finishes.
    * @param args Agent request plus waiter controls (pollInterval, timeout seconds).

package/dist/index.d.cts

@@ -1113,6 +1113,47 @@ interface AgentStatusResponse {
 }
 /** Reasoning effort for agent jobs. Every level runs spark-2. */
 type AgentEffort = "low" | "medium" | "high";
+/** A single agent run as returned by the agent list endpoint. */
+interface AgentListItem {
+    id: string;
+    createdAt: string;
+    targetHint: string;
+    origin: string;
+    integration?: string;
+    settings: {
+        hidden: boolean;
+        starred: boolean;
+        label?: string;
+    };
+    status: "processing" | "completed" | "failed";
+    options?: {
+        urls?: string[];
+        prompt: string;
+        schema?: unknown;
+        /**
+         * Server-provided model name. Widened past the request-side union on
+         * purpose: new models ship without an SDK release, so pinning this to
+         * known names makes every future model a type error at the call site.
+         */
+        model: "spark-1-pro" | "spark-1-mini" | "spark-2" | (string & {});
+        effort?: AgentEffort;
+    };
+}
+interface AgentListResponse {
+    success: boolean;
+    agents?: AgentListItem[];
+    /**
+     * Absolute URL of the next page (pass its `before` value to listAgents to
+     * continue). Only present when more pages exist.
+     */
+    next?: string;
+    error?: string;
+}
+/** Options for listing agent runs. */
+interface AgentListOptions {
+    /** Only return agent runs created before this unix millisecond timestamp. */
+    before?: number;
+}
 type AgentTraceAgentRole = "orchestrator" | "subagent" | "browser" | "system";
 interface AgentTraceAgentIdentity {
     id: string;
@@ -2026,6 +2067,15 @@ declare class FirecrawlClient {
      * @param jobId Agent job id.
      */
     getAgentStatus(jobId: string): Promise<AgentStatusResponse>;
+    /**
+     * List agent runs, most recent first.
+     *
+     * Pages are fixed at 20 runs. To fetch the next page, pass the `before`
+     * value from the previous page's `next` URL. This method does not
+     * auto-paginate.
+     * @param options.before Only return runs created before this unix ms timestamp.
+     */
+    listAgents(options?: AgentListOptions): Promise<AgentListResponse>;
     /**
      * Convenience waiter: start an agent and poll until it finishes.
      * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
@@ -3057,4 +3107,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, type Document, type DocumentMetadata, type EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchFeedbackRequest, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, type Document, type DocumentMetadata, type EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchFeedbackRequest, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.d.ts

@@ -1113,6 +1113,47 @@ interface AgentStatusResponse {
 }
 /** Reasoning effort for agent jobs. Every level runs spark-2. */
 type AgentEffort = "low" | "medium" | "high";
+/** A single agent run as returned by the agent list endpoint. */
+interface AgentListItem {
+    id: string;
+    createdAt: string;
+    targetHint: string;
+    origin: string;
+    integration?: string;
+    settings: {
+        hidden: boolean;
+        starred: boolean;
+        label?: string;
+    };
+    status: "processing" | "completed" | "failed";
+    options?: {
+        urls?: string[];
+        prompt: string;
+        schema?: unknown;
+        /**
+         * Server-provided model name. Widened past the request-side union on
+         * purpose: new models ship without an SDK release, so pinning this to
+         * known names makes every future model a type error at the call site.
+         */
+        model: "spark-1-pro" | "spark-1-mini" | "spark-2" | (string & {});
+        effort?: AgentEffort;
+    };
+}
+interface AgentListResponse {
+    success: boolean;
+    agents?: AgentListItem[];
+    /**
+     * Absolute URL of the next page (pass its `before` value to listAgents to
+     * continue). Only present when more pages exist.
+     */
+    next?: string;
+    error?: string;
+}
+/** Options for listing agent runs. */
+interface AgentListOptions {
+    /** Only return agent runs created before this unix millisecond timestamp. */
+    before?: number;
+}
 type AgentTraceAgentRole = "orchestrator" | "subagent" | "browser" | "system";
 interface AgentTraceAgentIdentity {
     id: string;
@@ -2026,6 +2067,15 @@ declare class FirecrawlClient {
      * @param jobId Agent job id.
      */
     getAgentStatus(jobId: string): Promise<AgentStatusResponse>;
+    /**
+     * List agent runs, most recent first.
+     *
+     * Pages are fixed at 20 runs. To fetch the next page, pass the `before`
+     * value from the previous page's `next` URL. This method does not
+     * auto-paginate.
+     * @param options.before Only return runs created before this unix ms timestamp.
+     */
+    listAgents(options?: AgentListOptions): Promise<AgentListResponse>;
     /**
      * Convenience waiter: start an agent and poll until it finishes.
      * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
@@ -3057,4 +3107,4 @@ declare class Firecrawl extends FirecrawlClient {
     get v1(): FirecrawlApp;
 }
 
-export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, type Document, type DocumentMetadata, type EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchFeedbackRequest, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };
+export { type ActionOption, type ActiveCrawl, type ActiveCrawlsResponse, type AgentEffort, type AgentListItem, type AgentListOptions, type AgentListResponse, type AgentOptions$1 as AgentOptions, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceActiveBrowserSession, type AgentTraceAgentFinishedEvent, type AgentTraceAgentIdentity, type AgentTraceAgentRole, type AgentTraceAgentStartedEvent, type AgentTraceArtifactChange, type AgentTraceArtifactUpdatedEvent, type AgentTraceBrowserSessionFinishedEvent, type AgentTraceBrowserSessionStartedEvent, type AgentTraceError, type AgentTraceErrorOccurredEvent, type AgentTraceEvent, type AgentTraceProgressReportedEvent, type AgentTraceReasoningSummaryEvent, type AgentTraceResponse, type AgentTraceRunCancelRequestedEvent, type AgentTraceRunFinishedEvent, type AgentTraceRunStartedEvent, type AgentTraceToolCallFinishedEvent, type AgentTraceToolCallStartedEvent, type AgentWebhookConfig, type AgentWebhookEvent, type AttributesFormat, type AuditMetadata$1 as AuditMetadata, type BatchScrapeJob, type BatchScrapeOptions, type BatchScrapeResponse$1 as BatchScrapeResponse, type BrandingProfile, type BrowserCreateResponse, type BrowserDeleteResponse, type BrowserExecuteResponse, type BrowserListResponse, type BrowserSession, type CategoryOption, type ChangeTrackingFormat, type ClickAction, type ConcurrencyCheck, type CrawlErrorsResponse$1 as CrawlErrorsResponse, type CrawlJob, type CrawlOptions, type CrawlResponse$1 as CrawlResponse, type CreateMonitorRequest, type CreditUsage, type CreditUsageHistoricalPeriod, type CreditUsageHistoricalResponse, type DeveloperSearchLicenseDisclosure, type DeveloperSearchOptions, type DeveloperSearchPassage, type DeveloperSearchRepoStatus, type DeveloperSearchResponse, type DeveloperSearchResult, type DeveloperSearchSourceStatus, type DeveloperSearchType, type Document, type DocumentMetadata, type EndpointFeedbackEndpoint, type EndpointFeedbackRequest, type ErrorDetails, type ExecuteJavascriptAction, type ExtractResponse$1 as ExtractResponse, type FeedbackMissingContent, type FeedbackRating, type FeedbackResponse, type FeedbackValuableSource, Firecrawl, FirecrawlApp as FirecrawlAppV1, FirecrawlClient, type FirecrawlClientInput, type FirecrawlClientOptions, type Format, type FormatOption, type FormatString, type GetMonitorCheckOptions, type GetPaperOptions, type GitHubScoreBreakdown, type GitHubSearchItem, type GitHubSearchResponse, type HighlightsFormat, type IdMap, JobTimeoutError, type JsonFormat, type ListMonitorChecksOptions, type ListMonitorsOptions, type LocationConfig$1 as LocationConfig, type MapData, type MapOptions, type MenuAvailability, type MenuImage, type MenuItem, type MenuItemIdentifiers, type MenuMerchant, type MenuPrice, type MenuProfile, type MenuSection, type Monitor, type MonitorCheck, type MonitorCheckDetail, type MonitorCheckPage, type MonitorCrawlTarget, type MonitorCrawlTargetResult, type MonitorEmailNotification, type MonitorEmailRecipientSubscription, type MonitorJsonFieldDiff, type MonitorNotification, type MonitorPageDiff, type MonitorPageJudgment, type MonitorPageSnapshot, type MonitorSchedule, type MonitorScrapeTarget, type MonitorScrapeTargetResult, type MonitorSearchTarget, type MonitorSearchTargetResult, type MonitorSummary, type MonitorTarget, type MonitorTargetResult, type MonitorWebhookConfig, type PDFAction, type PDFParser, type PaginationConfig, type PaperMetadata, type PaperMetadataResponse, type PaperResult, type PaperSignals, type ParseFile, type ParseFileData, type ParseFormat, type ParseFormatOption, type ParseFormatString, type ParseOptions, type Passage, type PdfBlockConfidence, type PdfBlockItem, type PdfPage, type PdfPageBlocks, type PressAction, type ProductAvailability, type ProductImage, type ProductPrice, type ProductProfile, type ProductSale, type ProductVariant, type QueryFormat, type QuestionFormat, type QueueStatusResponse$1 as QueueStatusResponse, type ReadPaperResponse, type RedactPIIEntity, type RedactPIIOptions, ResearchClient, type ScrapeAction, type ScrapeBrowserDeleteResponse, type ScrapeExecuteRequest, type ScrapeExecuteResponse, type ScrapeOptions, type ScreenshotAction, type ScreenshotFormat, type ScrollAction, SdkError, type SearchData, type SearchFeedbackRequest, type SearchGithubOptions, type SearchPapersOptions, type SearchPapersResponse, type SearchRequest, type SearchResultImages, type SearchResultNews, type SearchResultWeb, type SimilarPapersOptions, type SimilarPapersResponse, type ThreatProtectionOptions, type TokenUsage, type TokenUsageHistoricalPeriod, type TokenUsageHistoricalResponse, type UpdateMonitorRequest, type Viewport, type WaitAction, Watcher, type WatcherOptions, type WebhookConfig, type WriteAction, Firecrawl as default };

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   require_package
-} from "./chunk-LFX7WDGT.js";
+} from "./chunk-KSTNOGOD.js";
 
 // src/v2/utils/httpClient.ts
 import axios from "axios";
@@ -1263,6 +1263,17 @@ async function getAgentStatus(http, jobId) {
     throw err;
   }
 }
+async function listAgents(http, options) {
+  try {
+    const query = options?.before !== void 0 ? `?before=${options.before}` : "";
+    const res = await http.get(`/v2/agent${query}`);
+    if (res.status !== 200) throwForBadResponse(res, "list agents");
+    return res.data;
+  } catch (err) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "list agents");
+    throw err;
+  }
+}
 async function waitAgent(http, jobId, pollInterval = 2, timeout) {
   const start = Date.now();
   while (true) {
@@ -2284,6 +2295,17 @@ var FirecrawlClient = class {
   async getAgentStatus(jobId) {
     return getAgentStatus(this.http, jobId);
   }
+  /**
+   * List agent runs, most recent first.
+   *
+   * Pages are fixed at 20 runs. To fetch the next page, pass the `before`
+   * value from the previous page's `next` URL. This method does not
+   * auto-paginate.
+   * @param options.before Only return runs created before this unix ms timestamp.
+   */
+  async listAgents(options) {
+    return listAgents(this.http, options);
+  }
   /**
    * Convenience waiter: start an agent and poll until it finishes.
    * @param args Agent request plus waiter controls (pollInterval, timeout seconds).
@@ -2458,7 +2480,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-SHMK2LJE.js");
+      const packageJson = await import("./package-OS7RONXY.js");
       return packageJson.default.version;
     } catch (error) {
       const isTest = typeof process !== "undefined" && (process.env.JEST_WORKER_ID != null || false);

package/dist/{package-SHMK2LJE.js → package-OS7RONXY.js}

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendable/firecrawl-js",
-  "version": "4.37.0",
+  "version": "4.38.0",
   "description": "JavaScript SDK for the Firecrawl API: web scraping, crawling, web search, and scientific literature search over a research paper index of PubMed, bioRxiv, medRxiv and arXiv abstracts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/__tests__/unit/v2/agent-list.unit.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, jest, test } from "@jest/globals";
+import { listAgents } from "../../../v2/methods/agent";
+
+describe("v2.agent listAgents unit", () => {
+  const sampleAgent = {
+    id: "018f3c5e-0000-7000-8000-000000000000",
+    createdAt: "2026-08-31T12:00:00.000Z",
+    targetHint: "https://example.com",
+    origin: "api",
+    settings: { hidden: false, starred: false },
+    status: "completed",
+    options: {
+      urls: ["https://example.com"],
+      prompt: "Find the pricing",
+      model: "spark-1-pro",
+    },
+  };
+
+  test("hits GET /v2/agent without query by default", async () => {
+    const get = jest.fn().mockResolvedValue({
+      status: 200,
+      data: { success: true, agents: [sampleAgent] },
+    });
+
+    const res = await listAgents({ get } as any);
+
+    expect(get).toHaveBeenCalledWith("/v2/agent");
+    expect(res.success).toBe(true);
+    expect(res.agents).toHaveLength(1);
+    expect(res.agents![0].id).toBe(sampleAgent.id);
+    expect(res.agents![0].settings.starred).toBe(false);
+    expect(res.next).toBeUndefined();
+  });
+
+  test("passes before as a query param", async () => {
+    const get = jest.fn().mockResolvedValue({
+      status: 200,
+      data: {
+        success: true,
+        agents: [sampleAgent],
+        next: "https://api.firecrawl.dev/v2/agent?before=1756600000000",
+      },
+    });
+
+    const res = await listAgents({ get } as any, { before: 1756600000000 });
+
+    expect(get).toHaveBeenCalledWith("/v2/agent?before=1756600000000");
+    expect(res.next).toBe(
+      "https://api.firecrawl.dev/v2/agent?before=1756600000000",
+    );
+  });
+
+  test("does not auto-paginate when next is present", async () => {
+    const get = jest.fn().mockResolvedValue({
+      status: 200,
+      data: {
+        success: true,
+        agents: [sampleAgent],
+        next: "https://api.firecrawl.dev/v2/agent?before=1756600000000",
+      },
+    });
+
+    const res = await listAgents({ get } as any);
+
+    expect(get).toHaveBeenCalledTimes(1);
+    expect(res.agents).toHaveLength(1);
+  });
+});

package/src/v2/client.ts

@@ -26,7 +26,7 @@ import {
   batchScrape as batchWaiter,
 } from "./methods/batch";
 import { startExtract, getExtractStatus, extract as extractWaiter } from "./methods/extract";
-import { startAgent, getAgentStatus, getAgentTrace, getAgentSnapshot, cancelAgent, agent as agentWaiter } from "./methods/agent";
+import { startAgent, getAgentStatus, getAgentTrace, getAgentSnapshot, cancelAgent, listAgents, agent as agentWaiter } from "./methods/agent";
 import {
   browser as browserMethod,
   browserExecute,
@@ -70,6 +70,8 @@ import type {
   AgentStatusResponse,
   AgentTraceResponse,
   AgentSnapshotResponse,
+  AgentListOptions,
+  AgentListResponse,
   CrawlOptions,
   BatchScrapeOptions,
   PaginationConfig,
@@ -521,6 +523,17 @@ export class FirecrawlClient {
   async getAgentStatus(jobId: string): Promise<AgentStatusResponse> {
     return getAgentStatus(this.http, jobId);
   }
+  /**
+   * List agent runs, most recent first.
+   *
+   * Pages are fixed at 20 runs. To fetch the next page, pass the `before`
+   * value from the previous page's `next` URL. This method does not
+   * auto-paginate.
+   * @param options.before Only return runs created before this unix ms timestamp.
+   */
+  async listAgents(options?: AgentListOptions): Promise<AgentListResponse> {
+    return listAgents(this.http, options);
+  }
   /**
    * Convenience waiter: start an agent and poll until it finishes.
    * @param args Agent request plus waiter controls (pollInterval, timeout seconds).

package/src/v2/methods/agent.ts

@@ -1,4 +1,4 @@
-import { type AgentEffort, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceResponse, type AgentWebhookConfig, type AuditMetadata, type ThreatProtectionOptions } from "../types";
+import { type AgentEffort, type AgentListOptions, type AgentListResponse, type AgentResponse, type AgentSnapshotResponse, type AgentStatusResponse, type AgentTraceResponse, type AgentWebhookConfig, type AuditMetadata, type ThreatProtectionOptions } from "../types";
 import { HttpClient } from "../utils/httpClient";
 import { normalizeAxiosError, throwForBadResponse } from "../utils/errorHandler";
 import { isZodSchema, zodSchemaToJsonSchema } from "../../utils/zodSchemaToJson";
@@ -61,6 +61,18 @@ export async function getAgentStatus(http: HttpClient, jobId: string): Promise<A
   }
 }
 
+export async function listAgents(http: HttpClient, options?: AgentListOptions): Promise<AgentListResponse> {
+  try {
+    const query = options?.before !== undefined ? `?before=${options.before}` : "";
+    const res = await http.get<AgentListResponse>(`/v2/agent${query}`);
+    if (res.status !== 200) throwForBadResponse(res, "list agents");
+    return res.data;
+  } catch (err: any) {
+    if (err?.isAxiosError) return normalizeAxiosError(err, "list agents");
+    throw err;
+  }
+}
+
 export async function waitAgent(
   http: HttpClient,
   jobId: string,

package/src/v2/types.ts

@@ -1340,6 +1340,50 @@ export interface AgentStatusResponse {
 /** Reasoning effort for agent jobs. Every level runs spark-2. */
 export type AgentEffort = "low" | "medium" | "high";
 
+/** A single agent run as returned by the agent list endpoint. */
+export interface AgentListItem {
+  id: string;
+  createdAt: string;
+  targetHint: string;
+  origin: string;
+  integration?: string;
+  settings: {
+    hidden: boolean;
+    starred: boolean;
+    label?: string;
+  };
+  status: "processing" | "completed" | "failed";
+  options?: {
+    urls?: string[];
+    prompt: string;
+    schema?: unknown;
+    /**
+     * Server-provided model name. Widened past the request-side union on
+     * purpose: new models ship without an SDK release, so pinning this to
+     * known names makes every future model a type error at the call site.
+     */
+    model: "spark-1-pro" | "spark-1-mini" | "spark-2" | (string & {});
+    effort?: AgentEffort;
+  };
+}
+
+export interface AgentListResponse {
+  success: boolean;
+  agents?: AgentListItem[];
+  /**
+   * Absolute URL of the next page (pass its `before` value to listAgents to
+   * continue). Only present when more pages exist.
+   */
+  next?: string;
+  error?: string;
+}
+
+/** Options for listing agent runs. */
+export interface AgentListOptions {
+  /** Only return agent runs created before this unix millisecond timestamp. */
+  before?: number;
+}
+
 export type AgentTraceAgentRole = "orchestrator" | "subagent" | "browser" | "system";
 
 export interface AgentTraceAgentIdentity {