firecrawl-sdk 1.14.0 → 1.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 361f6ab9151b9481824965c07081793bb5a21aa99ef9b5e8ad61ff3db58b64e8
-  data.tar.gz: d99e0a59c24b8cda8618a0d2fa83225c3869dea31768eb9846e4dad7173ab305
+  metadata.gz: 6f3695aabd644bab09a7baa7c340d72fe38f376cba6d2f2cc1635d9df2f3d66e
+  data.tar.gz: 445c52d6c75a8a3ba54b751a00b6ccf3d09745693bbee5462f6253eba3f7eb8d
 SHA512:
-  metadata.gz: 145c0ec698d497bbf326157cb304dee1c4e1d42439865d247b60fcb5ff4fa4b7ebcf818ac86dd0048ca192690570ff501052d65f4254464044d18c6e71b22c61
-  data.tar.gz: 2a2010f8e0b1545d662d782093bfad674be3f1406811ec330e00da0b2addedcd0a9a8e9ccd0821e0c48894e43acf6b72c0beb377e623ba23000b09e7612f8790
+  metadata.gz: daaf47ae8bc4b2ae5a549b873c5978fa01e1abf2cd9a4dfd5829da5a0797b2109892885c991830a4aecd6c69b469ac09ecd52a545f278238d57ecb13a779be42
+  data.tar.gz: 73433fb46a58926b598d1fee36aadf7551dbfdaf636d484860d81bf65fd7c13ce014272e5b32508db76ecfd6db728ba64e5232d764f6207f2b70b1e6867032ac

data/lib/firecrawl/client.rb

@@ -463,6 +463,20 @@ module Firecrawl
       Models::AgentStatusResponse.new(raw)
     end
 
+    # Lists agent tasks, 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 before [Integer, nil] only return agent runs created before this
+    #   unix millisecond timestamp
+    # @return [Models::AgentListResponse]
+    def list_agents(before: nil)
+      raw = @http.get("/v2/agent#{query(before: before)}")
+      Models::AgentListResponse.new(raw)
+    end
+
     # Runs an agent task and waits for completion (auto-polling).
     #
     # @param options [Models::AgentOptions] agent configuration
@@ -493,6 +507,31 @@ module Firecrawl
       @http.delete("/v2/agent/#{job_id}")
     end
 
+    # Gets the trace of an agent task.
+    #
+    # @param job_id [String] the agent job ID
+    # @param live_view [Boolean] include live view URLs for active browser sessions
+    # @return [Models::AgentTraceResponse]
+    def get_agent_trace(job_id, live_view: false)
+      raise ArgumentError, "Job ID is required" if job_id.nil?
+
+      raw = @http.get("/v2/agent/#{job_id}/trace#{query(liveView: live_view ? true : nil)}")
+      Models::AgentTraceResponse.new(raw)
+    end
+
+    # Gets a snapshot of an agent task.
+    #
+    # @param job_id [String] the agent job ID
+    # @param snapshot_id [String] the snapshot ID
+    # @return [Models::AgentSnapshotResponse]
+    def get_agent_snapshot(job_id, snapshot_id)
+      raise ArgumentError, "Job ID is required" if job_id.nil?
+      raise ArgumentError, "Snapshot ID is required" if snapshot_id.nil?
+
+      raw = @http.get("/v2/agent/#{job_id}/snapshots/#{snapshot_id}")
+      Models::AgentSnapshotResponse.new(raw)
+    end
+
     # ================================================================
     # USAGE & METRICS
     # ================================================================

data/lib/firecrawl/models/agent_list_response.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Response from listing agent tasks.
+    class AgentListResponse
+      attr_reader :success, :agents, :next, :error
+
+      def initialize(raw)
+        @success = raw["success"]
+        @agents = raw["agents"]
+        @next = raw["next"]
+        @error = raw["error"]
+      end
+
+      def to_s
+        "AgentListResponse{success=#{success}, agents=#{agents&.size}}"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_options.rb

@@ -3,10 +3,13 @@
 module Firecrawl
   module Models
     # Options for starting an agent task.
+    #
+    # effort: valid values are "low", "medium", and "high"; sets the reasoning
+    # budget for the run (every level runs spark-2).
     class AgentOptions
       FIELDS = %i[
         urls prompt schema integration max_credits
-        strict_constrain_to_urls model webhook audit_metadata
+        strict_constrain_to_urls model effort webhook audit_metadata
       ].freeze
 
       attr_reader(*FIELDS)
@@ -28,6 +31,7 @@ module Firecrawl
           "maxCredits" => max_credits,
           "strictConstrainToURLs" => strict_constrain_to_urls,
           "model" => model,
+          "effort" => effort,
           "webhook" => webhook.is_a?(Hash) ? webhook : webhook&.to_h,
           "auditMetadata" => audit_metadata&.to_h,
         }.compact

data/lib/firecrawl/models/agent_snapshot_response.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Snapshot response for an agent task.
+    class AgentSnapshotResponse
+      attr_reader :success, :id, :snapshot_id, :snapshot, :error
+
+      def initialize(raw)
+        @success = raw["success"]
+        @id = raw["id"]
+        @snapshot_id = raw["snapshotId"]
+        @snapshot = raw["snapshot"]
+        @error = raw["error"]
+      end
+
+      def to_s
+        "AgentSnapshotResponse{id=#{id}, snapshot_id=#{snapshot_id}, success=#{success}}"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/agent_status_response.rb

@@ -4,13 +4,15 @@ module Firecrawl
   module Models
     # Status response for monitoring agent tasks.
     class AgentStatusResponse
-      attr_reader :status, :data, :credits_used, :expires_at
+      attr_reader :status, :data, :credits_used, :expires_at, :effort
 
       def initialize(raw)
         @status = raw["status"]
         @data = raw["data"]
         @credits_used = raw["creditsUsed"]
         @expires_at = raw["expiresAt"]
+        # The effort the job ran with; only present for runs that specified it.
+        @effort = raw["effort"]
       end
 
       def done?

data/lib/firecrawl/models/agent_trace_response.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Firecrawl
+  module Models
+    # Trace response for an agent task.
+    #
+    # Events are raw hashes: each carries a "type" (e.g. "run.started",
+    # "agent.finished", "tool_call.started") plus base fields like
+    # "schemaVersion", "eventId", "runId", "occurredAt", "producerSequence",
+    # and "agent".
+    class AgentTraceResponse
+      attr_reader :success, :id, :events, :active_browser_sessions, :credits_used, :error
+
+      def initialize(raw)
+        @success = raw["success"]
+        @id = raw["id"]
+        @events = raw["events"]
+        @active_browser_sessions = raw["activeBrowserSessions"]
+        @credits_used = raw["creditsUsed"]
+        @error = raw["error"]
+      end
+
+      def to_s
+        "AgentTraceResponse{id=#{id}, success=#{success}}"
+      end
+    end
+  end
+end

data/lib/firecrawl/models/query_format.rb

@@ -42,6 +42,30 @@ module Firecrawl
       end
     end
 
+    # JSON format for extracting structured data from page content using a schema.
+    class JsonFormat
+      attr_reader :schema, :prompt, :check_prompt_injection
+
+      def initialize(schema: nil, prompt: nil, check_prompt_injection: nil)
+        @schema = schema
+        @prompt = prompt
+        @check_prompt_injection = check_prompt_injection
+      end
+
+      def to_h
+        {
+          "type" => "json",
+          "schema" => schema,
+          "prompt" => prompt,
+          "checkPromptInjection" => check_prompt_injection,
+        }.compact
+      end
+
+      def type
+        "json"
+      end
+    end
+
     # Deprecated query format for asking a question about page content.
     class QueryFormat
       MODE_FREEFORM = "freeform"

data/lib/firecrawl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Firecrawl
-  VERSION = "1.14.0"
+  VERSION = "1.16.0"
 end

data/lib/firecrawl.rb

@@ -24,7 +24,10 @@ require_relative "firecrawl/models/parse_file"
 require_relative "firecrawl/models/parse_options"
 require_relative "firecrawl/models/agent_options"
 require_relative "firecrawl/models/agent_response"
+require_relative "firecrawl/models/agent_list_response"
 require_relative "firecrawl/models/agent_status_response"
+require_relative "firecrawl/models/agent_trace_response"
+require_relative "firecrawl/models/agent_snapshot_response"
 require_relative "firecrawl/models/concurrency_check"
 require_relative "firecrawl/models/credit_usage"
 require_relative "firecrawl/models/monitor"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: firecrawl-sdk
 version: !ruby/object:Gem::Version
-  version: 1.14.0
+  version: 1.16.0
 platform: ruby
 authors:
 - Firecrawl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-21 00:00:00.000000000 Z
+date: 2026-08-31 00:00:00.000000000 Z
 dependencies: []
 description: A type-safe Ruby client for the Firecrawl v2 API. Supports scraping,
   crawling, batch scraping, URL mapping, web search, and AI agent operations.
@@ -24,9 +24,12 @@ files:
 - lib/firecrawl/client.rb
 - lib/firecrawl/errors.rb
 - lib/firecrawl/http_client.rb
+- lib/firecrawl/models/agent_list_response.rb
 - lib/firecrawl/models/agent_options.rb
 - lib/firecrawl/models/agent_response.rb
+- lib/firecrawl/models/agent_snapshot_response.rb
 - lib/firecrawl/models/agent_status_response.rb
+- lib/firecrawl/models/agent_trace_response.rb
 - lib/firecrawl/models/audit_metadata.rb
 - lib/firecrawl/models/batch_scrape_job.rb
 - lib/firecrawl/models/batch_scrape_options.rb