Package com.firecrawl.client

Class FirecrawlClient

  • public class FirecrawlClient
extends java.lang.Object
    Client for the Firecrawl v2 API.

    Example usage: 

    
 FirecrawlClient client = FirecrawlClient.builder()
     .apiKey("fc-your-api-key")
     .build();

 // Scrape a single page
 Document doc = client.scrape("https://example.com",
     ScrapeOptions.builder()
         .formats(List.of("markdown"))
         .build());

 // Crawl a website
 CrawlJob job = client.crawl("https://example.com",
     CrawlOptions.builder()
         .limit(50)
         .build());

    • Method Detail

      • builder

        public static FirecrawlClient.Builder builder()
        Creates a new builder for constructing a FirecrawlClient.

      • fromEnv

        public static FirecrawlClient fromEnv()
        Creates a client from the FIRECRAWL_API_KEY environment variable.

      • scrape

        public Document scrape​(java.lang.String url)
        Scrapes a single URL and returns the document.
        Parameters:
        url - the URL to scrape
        Returns:
        the scraped document

      • scrape

        public Document scrape​(java.lang.String url,
                       ScrapeOptions options)
        Scrapes a single URL with options.
        Parameters:
        url - the URL to scrape
        options - scrape configuration options
        Returns:
        the scraped document

      • interact

        public BrowserExecuteResponse interact​(java.lang.String jobId,
                                       java.lang.String code)
        Interacts with the scrape-bound browser session for a scrape job.
        Parameters:
        jobId - the scrape job ID
        code - the code to execute
        Returns:
        the execution result including stdout, stderr, and exit code

      • interact

        public BrowserExecuteResponse interact​(java.lang.String jobId,
                                       java.lang.String code,
                                       java.lang.String language,
                                       java.lang.Integer timeout)
        Interacts with the scrape-bound browser session for a scrape job.
        Parameters:
        jobId - the scrape job ID
        code - the code to execute
        language - the language: "python", "node", or "bash" (default: "node")
        timeout - execution timeout in seconds (1-300), or null for default (30)
        Returns:
        the execution result including stdout, stderr, and exit code

      • interact

        public BrowserExecuteResponse interact​(java.lang.String jobId,
                                       java.lang.String code,
                                       java.lang.String language,
                                       java.lang.Integer timeout,
                                       java.lang.String origin)
        Interacts with the scrape-bound browser session for a scrape job.
        Parameters:
        jobId - the scrape job ID
        code - the code to execute
        language - the language: "python", "node", or "bash" (default: "node")
        timeout - execution timeout in seconds (1-300), or null for default (30)
        origin - optional origin tag for request attribution
        Returns:
        the execution result including stdout, stderr, and exit code

      • stopInteractiveBrowser

        public BrowserDeleteResponse stopInteractiveBrowser​(java.lang.String jobId)
        Stops the interactive browser session for a scrape job.
        Parameters:
        jobId - the scrape job ID
        Returns:
        the stop response with session duration and billing info

      • startCrawl

        public CrawlResponse startCrawl​(java.lang.String url,
                                CrawlOptions options)
        Starts an async crawl job and returns immediately.
        Parameters:
        url - the URL to start crawling from
        options - crawl configuration options
        Returns:
        the crawl job reference with ID

      • getCrawlStatus

        public CrawlJob getCrawlStatus​(java.lang.String jobId)
        Gets the status and results of a crawl job.
        Parameters:
        jobId - the crawl job ID
        Returns:
        the crawl job status

      • crawl

        public CrawlJob crawl​(java.lang.String url,
                      CrawlOptions options)
        Crawls a website and waits for completion (auto-polling).
        Parameters:
        url - the URL to crawl
        options - crawl configuration options
        Returns:
        the completed crawl job with all documents

      • crawl

        public CrawlJob crawl​(java.lang.String url,
                      CrawlOptions options,
                      int pollIntervalSec,
                      int timeoutSec)
        Crawls a website and waits for completion with custom polling settings.
        Parameters:
        url - the URL to crawl
        options - crawl configuration options
        pollIntervalSec - seconds between status checks
        timeoutSec - maximum seconds to wait
        Returns:
        the completed crawl job with all documents

      • cancelCrawl

        public java.util.Map<java.lang.String,​java.lang.Object> cancelCrawl​(java.lang.String jobId)
        Cancels a running crawl job.
        Parameters:
        jobId - the crawl job ID
        Returns:
        the cancellation response

      • getCrawlErrors

        public java.util.Map<java.lang.String,​java.lang.Object> getCrawlErrors​(java.lang.String jobId)
        Gets errors from a crawl job.
        Parameters:
        jobId - the crawl job ID
        Returns:
        error details

      • startBatchScrape

        public BatchScrapeResponse startBatchScrape​(java.util.List<java.lang.String> urls,
                                            BatchScrapeOptions options)
        Starts an async batch scrape job.
        Parameters:
        urls - the URLs to scrape
        options - batch scrape configuration options
        Returns:
        the batch job reference with ID

      • getBatchScrapeStatus

        public BatchScrapeJob getBatchScrapeStatus​(java.lang.String jobId)
        Gets the status and results of a batch scrape job.
        Parameters:
        jobId - the batch scrape job ID
        Returns:
        the batch scrape job status

      • batchScrape

        public BatchScrapeJob batchScrape​(java.util.List<java.lang.String> urls,
                                  BatchScrapeOptions options)
        Batch-scrapes URLs and waits for completion (auto-polling).
        Parameters:
        urls - the URLs to scrape
        options - batch scrape configuration options
        Returns:
        the completed batch scrape job with all documents

      • batchScrape

        public BatchScrapeJob batchScrape​(java.util.List<java.lang.String> urls,
                                  BatchScrapeOptions options,
                                  int pollIntervalSec,
                                  int timeoutSec)
        Batch-scrapes URLs and waits for completion with custom polling settings.
        Parameters:
        urls - the URLs to scrape
        options - batch scrape configuration options
        pollIntervalSec - seconds between status checks
        timeoutSec - maximum seconds to wait
        Returns:
        the completed batch scrape job with all documents

      • cancelBatchScrape

        public java.util.Map<java.lang.String,​java.lang.Object> cancelBatchScrape​(java.lang.String jobId)
        Cancels a running batch scrape job.
        Parameters:
        jobId - the batch scrape job ID
        Returns:
        the cancellation response

      • map

        public MapData map​(java.lang.String url)
        Discovers URLs on a website.
        Parameters:
        url - the URL to map
        Returns:
        the discovered URLs

      • map

        public MapData map​(java.lang.String url,
                   MapOptions options)
        Discovers URLs on a website with options.
        Parameters:
        url - the URL to map
        options - map configuration options
        Returns:
        the discovered URLs

      • search

        public SearchData search​(java.lang.String query)
        Performs a web search.
        Parameters:
        query - the search query
        Returns:
        search results

      • search

        public SearchData search​(java.lang.String query,
                         SearchOptions options)
        Performs a web search with options.
        Parameters:
        query - the search query
        options - search configuration options
        Returns:
        search results

      • startAgent

        public AgentResponse startAgent​(AgentOptions options)
        Starts an async agent task.
        Parameters:
        options - agent configuration options
        Returns:
        the agent response with job ID

      • getAgentStatus

        public AgentStatusResponse getAgentStatus​(java.lang.String jobId)
        Gets the status of an agent task.
        Parameters:
        jobId - the agent job ID
        Returns:
        the agent status response

      • agent

        public AgentStatusResponse agent​(AgentOptions options)
        Runs an agent task and waits for completion (auto-polling).
        Parameters:
        options - agent configuration options
        Returns:
        the completed agent status response

      • agent

        public AgentStatusResponse agent​(AgentOptions options,
                                 int pollIntervalSec,
                                 int timeoutSec)
        Runs an agent task and waits for completion with custom polling settings.
        Parameters:
        options - agent configuration options
        pollIntervalSec - seconds between status checks
        timeoutSec - maximum seconds to wait
        Returns:
        the completed agent status response

      • cancelAgent

        public java.util.Map<java.lang.String,​java.lang.Object> cancelAgent​(java.lang.String jobId)
        Cancels a running agent task.
        Parameters:
        jobId - the agent job ID
        Returns:
        the cancellation response

      • browser

        public BrowserCreateResponse browser()
        Creates a new browser session with default settings.
        Returns:
        the browser session details including id, CDP URL, and live view URL

      • browser

        public BrowserCreateResponse browser​(java.lang.Integer ttl,
                                     java.lang.Integer activityTtl,
                                     java.lang.Boolean streamWebView)
        Creates a new browser session with options.
        Parameters:
        ttl - total session lifetime in seconds (30-3600), or null for default
        activityTtl - idle timeout in seconds (10-3600), or null for default
        streamWebView - whether to enable live view streaming, or null for default
        Returns:
        the browser session details

      • browserExecute

        public BrowserExecuteResponse browserExecute​(java.lang.String sessionId,
                                             java.lang.String code)
        Executes code in a browser session using the default language (bash).
        Parameters:
        sessionId - the browser session ID
        code - the code to execute
        Returns:
        the execution result including stdout, stderr, and exit code

      • browserExecute

        public BrowserExecuteResponse browserExecute​(java.lang.String sessionId,
                                             java.lang.String code,
                                             java.lang.String language,
                                             java.lang.Integer timeout)
        Executes code in a browser session with options.
        Parameters:
        sessionId - the browser session ID
        code - the code to execute
        language - the language: "python", "node", or "bash" (default: "bash")
        timeout - execution timeout in seconds (1-300), or null for default (30)
        Returns:
        the execution result including stdout, stderr, and exit code

      • deleteBrowser

        public BrowserDeleteResponse deleteBrowser​(java.lang.String sessionId)
        Deletes a browser session.
        Parameters:
        sessionId - the browser session ID
        Returns:
        the deletion response with session duration and billing info

      • listBrowsers

        public BrowserListResponse listBrowsers()
        Lists all browser sessions.
        Returns:
        the list of browser sessions

      • listBrowsers

        public BrowserListResponse listBrowsers​(java.lang.String status)
        Lists browser sessions with optional status filter.
        Parameters:
        status - optional filter: "active" or "destroyed", or null for all
        Returns:
        the list of browser sessions

      • getConcurrency

        public ConcurrencyCheck getConcurrency()
        Gets current concurrency usage.

      • getCreditUsage

        public CreditUsage getCreditUsage()
        Gets current credit usage.

      • scrapeAsync

        public java.util.concurrent.CompletableFuture<Document> scrapeAsync​(java.lang.String url,
                                                                    ScrapeOptions options)
        Asynchronously scrapes a URL.
        Parameters:
        url - the URL to scrape
        options - scrape configuration options
        Returns:
        a CompletableFuture that resolves to the scraped Document

      • interactAsync

        public java.util.concurrent.CompletableFuture<BrowserExecuteResponse> interactAsync​(java.lang.String jobId,
                                                                                    java.lang.String code)
        Asynchronously executes code in a scrape-bound browser session.
        Parameters:
        jobId - the scrape job ID
        code - the code to execute
        Returns:
        a CompletableFuture that resolves to the BrowserExecuteResponse

      • interactAsync

        public java.util.concurrent.CompletableFuture<BrowserExecuteResponse> interactAsync​(java.lang.String jobId,
                                                                                    java.lang.String code,
                                                                                    java.lang.String language,
                                                                                    java.lang.Integer timeout)
        Asynchronously executes code in a scrape-bound browser session.
        Parameters:
        jobId - the scrape job ID
        code - the code to execute
        language - the language: "python", "node", or "bash"
        timeout - execution timeout in seconds, or null for default
        Returns:
        a CompletableFuture that resolves to the BrowserExecuteResponse

      • interactAsync

        public java.util.concurrent.CompletableFuture<BrowserExecuteResponse> interactAsync​(java.lang.String jobId,
                                                                                    java.lang.String code,
                                                                                    java.lang.String language,
                                                                                    java.lang.Integer timeout,
                                                                                    java.lang.String origin)
        Asynchronously executes code in a scrape-bound browser session.
        Parameters:
        jobId - the scrape job ID
        code - the code to execute
        language - the language: "python", "node", or "bash"
        timeout - execution timeout in seconds, or null for default
        origin - optional origin tag for request attribution
        Returns:
        a CompletableFuture that resolves to the BrowserExecuteResponse

      • stopInteractiveBrowserAsync

        public java.util.concurrent.CompletableFuture<BrowserDeleteResponse> stopInteractiveBrowserAsync​(java.lang.String jobId)
        Asynchronously deletes a scrape-bound browser session.
        Parameters:
        jobId - the scrape job ID
        Returns:
        a CompletableFuture that resolves to the BrowserDeleteResponse

      • crawlAsync

        public java.util.concurrent.CompletableFuture<CrawlJob> crawlAsync​(java.lang.String url,
                                                                   CrawlOptions options)
        Asynchronously crawls a website and waits for completion.
        Parameters:
        url - the URL to crawl
        options - crawl configuration options
        Returns:
        a CompletableFuture that resolves to the completed CrawlJob

      • crawlAsync

        public java.util.concurrent.CompletableFuture<CrawlJob> crawlAsync​(java.lang.String url,
                                                                   CrawlOptions options,
                                                                   int pollIntervalSec,
                                                                   int timeoutSec)
        Asynchronously crawls with custom polling settings.
        Parameters:
        url - the URL to crawl
        options - crawl configuration options
        pollIntervalSec - seconds between status checks
        timeoutSec - maximum seconds to wait
        Returns:
        a CompletableFuture that resolves to the completed CrawlJob

      • batchScrapeAsync

        public java.util.concurrent.CompletableFuture<BatchScrapeJob> batchScrapeAsync​(java.util.List<java.lang.String> urls,
                                                                               BatchScrapeOptions options)
        Asynchronously batch-scrapes URLs and waits for completion.
        Parameters:
        urls - the URLs to scrape
        options - batch scrape configuration options
        Returns:
        a CompletableFuture that resolves to the completed BatchScrapeJob

      • searchAsync

        public java.util.concurrent.CompletableFuture<SearchData> searchAsync​(java.lang.String query,
                                                                      SearchOptions options)
        Asynchronously runs a search.
        Parameters:
        query - the search query
        options - search configuration options
        Returns:
        a CompletableFuture that resolves to the SearchData

      • mapAsync

        public java.util.concurrent.CompletableFuture<MapData> mapAsync​(java.lang.String url,
                                                                MapOptions options)
        Asynchronously runs a map operation.
        Parameters:
        url - the URL to map
        options - map configuration options
        Returns:
        a CompletableFuture that resolves to the MapData

      • agentAsync

        public java.util.concurrent.CompletableFuture<AgentStatusResponse> agentAsync​(AgentOptions options)
        Asynchronously runs an agent task and waits for completion.
        Parameters:
        options - agent configuration options
        Returns:
        a CompletableFuture that resolves to the AgentStatusResponse

      • browserAsync

        public java.util.concurrent.CompletableFuture<BrowserCreateResponse> browserAsync​(java.lang.Integer ttl,
                                                                                  java.lang.Integer activityTtl,
                                                                                  java.lang.Boolean streamWebView)
        Asynchronously creates a new browser session.
        Parameters:
        ttl - total session lifetime in seconds, or null for default
        activityTtl - idle timeout in seconds, or null for default
        streamWebView - whether to enable live view streaming, or null for default
        Returns:
        a CompletableFuture that resolves to the BrowserCreateResponse

      • browserExecuteAsync

        public java.util.concurrent.CompletableFuture<BrowserExecuteResponse> browserExecuteAsync​(java.lang.String sessionId,
                                                                                          java.lang.String code,
                                                                                          java.lang.String language,
                                                                                          java.lang.Integer timeout)
        Asynchronously executes code in a browser session.
        Parameters:
        sessionId - the browser session ID
        code - the code to execute
        language - the language: "python", "node", or "bash"
        timeout - execution timeout in seconds, or null for default
        Returns:
        a CompletableFuture that resolves to the BrowserExecuteResponse

      • deleteBrowserAsync

        public java.util.concurrent.CompletableFuture<BrowserDeleteResponse> deleteBrowserAsync​(java.lang.String sessionId)
        Asynchronously deletes a browser session.
        Parameters:
        sessionId - the browser session ID
        Returns:
        a CompletableFuture that resolves to the BrowserDeleteResponse

      • listBrowsersAsync

        public java.util.concurrent.CompletableFuture<BrowserListResponse> listBrowsersAsync​(java.lang.String status)
        Asynchronously lists browser sessions.
        Parameters:
        status - optional filter: "active" or "destroyed", or null for all
        Returns:
        a CompletableFuture that resolves to the BrowserListResponse