firecrawl-sdk 1.14.0 → 1.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 361f6ab9151b9481824965c07081793bb5a21aa99ef9b5e8ad61ff3db58b64e8
-  data.tar.gz: d99e0a59c24b8cda8618a0d2fa83225c3869dea31768eb9846e4dad7173ab305
+  metadata.gz: 7c7e11ff05113a301d334412a0aea3f1d421aa93cd45756c0546193d1cc3839e
+  data.tar.gz: 46b8f0dc763344c1372212a1e612812292c67efc6042a3ff5a45c66a4e63dcee
 SHA512:
-  metadata.gz: 145c0ec698d497bbf326157cb304dee1c4e1d42439865d247b60fcb5ff4fa4b7ebcf818ac86dd0048ca192690570ff501052d65f4254464044d18c6e71b22c61
-  data.tar.gz: 2a2010f8e0b1545d662d782093bfad674be3f1406811ec330e00da0b2addedcd0a9a8e9ccd0821e0c48894e43acf6b72c0beb377e623ba23000b09e7612f8790
+  metadata.gz: 7f29c1250ccac6a0b7aece8951bc655dd3b55aee9f4d18dd66a987829514490c350dde4865527e0a48bf52fa1362c5d2d7bcd0ae168b319bbff51c824148d190
+  data.tar.gz: 1e907fd282ee7314cafe5223fc63571ada85ce45381de830f99baf2dcf41c7cb9b45d4a5ad45863cb1b1d0b812918a1bcda778e57886eea12811b421196932f9

data/lib/firecrawl/client.rb

@@ -493,6 +493,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_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.15.0"
 end

data/lib/firecrawl.rb

@@ -25,6 +25,8 @@ require_relative "firecrawl/models/parse_options"
 require_relative "firecrawl/models/agent_options"
 require_relative "firecrawl/models/agent_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.15.0
 platform: ruby
 authors:
 - Firecrawl
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-21 00:00:00.000000000 Z
+date: 2026-08-26 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.
@@ -26,7 +26,9 @@ files:
 - lib/firecrawl/http_client.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