Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

Add 'search' monitor target support

Developers Digest82973f6c90f4
diff --git a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
index 19b83f883..799039f11 100644
--- a/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
+++ b/apps/dot-net-sdk/Firecrawl.Tests/ModelsTests.cs
@@ -475,4 +475,59 @@ public class ModelsTests
Assert.NotNull(response.InvalidURLs);
Assert.Single(response.InvalidURLs);
}
+
+ [Fact]
+ public void MonitorSearchTarget_SerializesCorrectly()
+ {
+ var target = new MonitorSearchTarget
+ {
+ Queries = new List<string> { "firecrawl pricing", "firecrawl changelog" },
+ SearchWindow = "24h",
+ IncludeDomains = new List<string> { "firecrawl.dev" },
+ ExcludeDomains = new List<string> { "example.com" },
+ MaxResults = 10
+ };
+
+ var json = JsonSerializer.Serialize(target, JsonOptions);
+ Assert.Contains("\"type\":\"search\"", json);
+ Assert.Contains("\"queries\"", json);
+ Assert.Contains("\"searchWindow\":\"24h\"", json);
+ Assert.Contains("\"includeDomains\"", json);
+ Assert.Contains("\"excludeDomains\"", json);
+ Assert.Contains("\"maxResults\":10", json);
+ }
+
+ [Fact]
+ public void MonitorSearchTargetResult_DeserializesCorrectly()
+ {
+ var json = """
+ {
+ "targetId": "tgt-1",
+ "type": "search",
+ "searchCompleted": true,
+ "resultCount": 5,
+ "matches": 2,
+ "summary": "Two new results matched.",
+ "judgeDegraded": false,
+ "degradedReason": null,
+ "searchCredits": 5,
+ "judgeCredits": 1,
+ "resultsJudged": 5
+ }
+ """;
+
+ var result = JsonSerializer.Deserialize<MonitorSearchTargetResult>(json, JsonOptions);
+ Assert.NotNull(result);
+ Assert.Equal("tgt-1", result.TargetId);
+ Assert.Equal("search", result.Type);
+ Assert.True(result.SearchCompleted);
+ Assert.Equal(5, result.ResultCount);
+ Assert.Equal(2, result.Matches);
+ Assert.Equal("Two new results matched.", result.Summary);
+ Assert.False(result.JudgeDegraded);
+ Assert.Null(result.DegradedReason);
+ Assert.Equal(5, result.SearchCredits);
+ Assert.Equal(1, result.JudgeCredits);
+ Assert.Equal(5, result.ResultsJudged);
+ }
}
diff --git a/apps/dot-net-sdk/Firecrawl/Models/MonitorModels.cs b/apps/dot-net-sdk/Firecrawl/Models/MonitorModels.cs
index ea809cc44..71f38a030 100644
--- a/apps/dot-net-sdk/Firecrawl/Models/MonitorModels.cs
+++ b/apps/dot-net-sdk/Firecrawl/Models/MonitorModels.cs
@@ -78,6 +78,82 @@ public class UpdateMonitorRequest
public bool? JudgeEnabled { get; set; }
}
+/// <summary>
+/// Strongly-typed representation of a search target stored on a monitor
+/// (<c>type</c> = <c>"search"</c>), alongside the scrape and crawl targets.
+/// Monitor request/response models expose targets as untyped
+/// <see cref="Dictionary{TKey, TValue}"/> entries; use this type to build a
+/// search target and re-serialize it into that dictionary shape, or to
+/// re-deserialize a target entry when its <c>type</c> is <c>"search"</c>.
+/// </summary>
+public class MonitorSearchTarget
+{
+ [JsonPropertyName("id")]
+ public string? Id { get; set; }
+
+ [JsonPropertyName("type")]
+ public string Type { get; set; } = "search";
+
+ [JsonPropertyName("queries")]
+ public List<string> Queries { get; set; } = new();
+
+ /// <summary>One of <c>5m</c>, <c>15m</c>, <c>1h</c>, <c>6h</c>, <c>24h</c>, <c>7d</c>.</summary>
+ [JsonPropertyName("searchWindow")]
+ public string? SearchWindow { get; set; }
+
+ [JsonPropertyName("includeDomains")]
+ public List<string>? IncludeDomains { get; set; }
+
+ [JsonPropertyName("excludeDomains")]
+ public List<string>? ExcludeDomains { get; set; }
+
+ [JsonPropertyName("maxResults")]
+ public int? MaxResults { get; set; }
+}
+
+/// <summary>
+/// Strongly-typed per-target result for a search target (<c>type</c> =
+/// <c>"search"</c>) on a monitor check, alongside the scrape and crawl
+/// target results. Monitor checks expose <c>targetResults</c> as an
+/// untyped <see cref="object"/>; re-deserialize an entry into this type
+/// when its <c>type</c> is <c>"search"</c>.
+/// </summary>
+public class MonitorSearchTargetResult
+{
+ [JsonPropertyName("targetId")]
+ public string? TargetId { get; set; }
+
+ [JsonPropertyName("type")]
+ public string Type { get; set; } = "search";
+
+ [JsonPropertyName("searchCompleted")]
+ public bool? SearchCompleted { get; set; }
+
+ [JsonPropertyName("resultCount")]
+ public int? ResultCount { get; set; }
+
+ [JsonPropertyName("matches")]
+ public int? Matches { get; set; }
+
+ [JsonPropertyName("summary")]
+ public string? Summary { get; set; }
+
+ [JsonPropertyName("judgeDegraded")]
+ public bool? JudgeDegraded { get; set; }
+
+ [JsonPropertyName("degradedReason")]
+ public string? DegradedReason { get; set; }
+
+ [JsonPropertyName("searchCredits")]
+ public double? SearchCredits { get; set; }
+
+ [JsonPropertyName("judgeCredits")]
+ public double? JudgeCredits { get; set; }
+
+ [JsonPropertyName("resultsJudged")]
+ public int? ResultsJudged { get; set; }
+}
+
public class MonitorSummary
{
[JsonPropertyName("totalPages")]
diff --git a/apps/elixir-sdk/lib/firecrawl.ex b/apps/elixir-sdk/lib/firecrawl.ex
index f81a95ecf..c75cd4674 100644
--- a/apps/elixir-sdk/lib/firecrawl.ex
+++ b/apps/elixir-sdk/lib/firecrawl.ex
@@ -1465,6 +1465,22 @@ defmodule Firecrawl do
Create a scheduled monitor.
`POST /monitor`
+
+ ## Targets
+
+ `targets` is a list of maps/keyword lists. Each target is sent as-is (keys are
+ camelCased), so the supported target shapes are:
+
+ * Scrape: `[type: "scrape", url: "https://example.com", ...]`
+ * Crawl: `[type: "crawl", url: "https://example.com", ...]`
+ * Search:
+ `[type: "search", queries: ["term"], search_window: "24h",
+ include_domains: ["example.com"], exclude_domains: [],
+ max_results: 10]`
+ (`search_window` is one of `"5m"`, `"15m"`, `"1h"`, `"6h"`, `"24h"`,
+ `"7d"`; only `queries` is required.)
+
+ Optionally pass `goal` and `judge_enabled: true` to enable AI judging.
"""
@spec create_monitor(keyword(), keyword()) :: response()
def create_monitor(params \\ [], opts \\ []) do
diff --git a/apps/elixir-sdk/test/firecrawl_test.exs b/apps/elixir-sdk/test/firecrawl_test.exs
index 41e1754c1..9da76abd8 100644
--- a/apps/elixir-sdk/test/firecrawl_test.exs
+++ b/apps/elixir-sdk/test/firecrawl_test.exs
@@ -78,6 +78,38 @@ defmodule FirecrawlTest do
end
end
+ test "create_monitor accepts a search target" do
+ Application.put_env(:firecrawl, :api_key, "test-key")
+ on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)
+
+ result =
+ Firecrawl.create_monitor(
+ [
+ name: "search monitor",
+ schedule: [interval: "24h"],
+ goal: "Track new mentions",
+ judge_enabled: true,
+ targets: [
+ [
+ type: "search",
+ queries: ["firecrawl"],
+ search_window: "24h",
+ include_domains: ["example.com"],
+ exclude_domains: [],
+ max_results: 10
+ ]
+ ]
+ ],
+ base_url: "http://localhost:1",
+ retry: false
+ )
+
+ # Validation passes (it is not a ValidationError); the request itself fails
+ # because the base_url is unreachable.
+ assert {:error, error} = result
+ refute match?(%NimbleOptions.ValidationError{}, error)
+ end
+
test "accepts atom values for enum params" do
Application.put_env(:firecrawl, :api_key, "test-key")
on_exit(fn -> Application.delete_env(:firecrawl, :api_key) end)
diff --git a/apps/go-sdk/models.go b/apps/go-sdk/models.go
index 47626b925..62f826fba 100644
--- a/apps/go-sdk/models.go
+++ b/apps/go-sdk/models.go
@@ -338,6 +338,36 @@ type MonitorSchedule struct {
Timezone string `json:"timezone,omitempty"`
}
+// MonitorSearchTarget is a search monitor target. It is one variant of the
+// monitor target union (alongside scrape and crawl targets) used in the
+// Targets field of monitor requests and the Monitor struct.
+type MonitorSearchTarget struct {
+ ID string `json:"id,omitempty"`
+ Type string `json:"type"`
+ Queries []string `json:"queries"`
+ SearchWindow string `json:"searchWindow,omitempty"`
+ IncludeDomains []string `json:"includeDomains,omitempty"`
+ ExcludeDomains []string `json:"excludeDomains,omitempty"`
+ MaxResults *int `json:"maxResults,omitempty"`
+}
+
+// MonitorSearchTargetResult is the per-target result for a search target on a
+// monitor check. It is one variant of the monitor target-result union
+// (alongside scrape and crawl results) found in a check's TargetResults.
+type MonitorSearchTargetResult struct {
+ TargetID string `json:"targetId"`
+ Type string `json:"type"`
+ SearchCompleted *bool `json:"searchCompleted,omitempty"`
+ ResultCount *int `json:"resultCount,omitempty"`
+ Matches *int `json:"matches,omitempty"`
+ Summary string `json:"summary,omitempty"`
+ JudgeDegraded *bool `json:"judgeDegraded,omitempty"`
+ DegradedReason *string `json:"degradedReason,omitempty"`
+ SearchCredits *float64 `json:"searchCredits,omitempty"`
+ JudgeCredits *float64 `json:"judgeCredits,omitempty"`
+ ResultsJudged *int `json:"resultsJudged,omitempty"`
+}
+
// MonitorCreateRequest creates a scheduled monitor.
//
// Goal is an optional natural-language description of what the monitor is
diff --git a/apps/go-sdk/monitor_models_test.go b/apps/go-sdk/monitor_models_test.go
index ac41c62a3..8f8d66270 100644
--- a/apps/go-sdk/monitor_models_test.go
+++ b/apps/go-sdk/monitor_models_test.go
@@ -36,3 +36,81 @@ func TestMonitorPageJudgmentParsesMeaningfulChanges(t *testing.T) {
t.Fatalf("meaningful change = %+v", change)
}
}
+
+func TestMonitorSearchTargetRoundTrips(t *testing.T) {
+ max := 25
+ target := MonitorSearchTarget{
+ Type: "search",
+ Queries: []string{"firecrawl pricing", "firecrawl changelog"},
+ SearchWindow: "24h",
+ IncludeDomains: []string{"firecrawl.dev"},
+ ExcludeDomains: []string{"example.com"},
+ MaxResults: &max,
+ }
+
+ data, err := json.Marshal(target)
+ if err != nil {
+ t.Fatalf("Marshal MonitorSearchTarget: %v", err)
+ }
+
+ var decoded MonitorSearchTarget
+ if err := json.Unmarshal(data, &decoded); err != nil {
+ t.Fatalf("Unmarshal MonitorSearchTarget: %v", err)
+ }
+
+ if decoded.Type != "search" || len(decoded.Queries) != 2 || decoded.SearchWindow != "24h" {
+ t.Fatalf("target = %+v", decoded)
+ }
+ if decoded.MaxResults == nil || *decoded.MaxResults != 25 {
+ t.Fatalf("maxResults = %v", decoded.MaxResults)
+ }
+ if decoded.ID != "" {
+ t.Fatalf("expected omitted id, got %q", decoded.ID)
+ }
+}
+
+func TestMonitorSearchTargetResultParses(t *testing.T) {
+ payload := []byte(`{
+ "targetId": "tgt_1",
+ "type": "search",
+ "searchCompleted": true,
+ "resultCount": 10,
+ "matches": 3,
+ "summary": "Found 3 matching results.",
+ "judgeDegraded": false,
+ "degradedReason": null,
+ "searchCredits": 1.5,
+ "judgeCredits": 0.25,
+ "resultsJudged": 8
+ }`)
+
+ var result MonitorSearchTargetResult
+ if err := json.Unmarshal(payload, &result); err != nil {
+ t.Fatalf("Unmarshal MonitorSearchTargetResult: %v", err)
+ }
+
+ if result.TargetID != "tgt_1" || result.Type != "search" {
+ t.Fatalf("result = %+v", result)
+ }
+ if result.SearchCompleted == nil || !*result.SearchCompleted {
+ t.Fatalf("searchCompleted = %v", result.SearchCompleted)
+ }
+ if result.ResultCount == nil || *result.ResultCount != 10 {
+ t.Fatalf("resultCount = %v", result.ResultCount)
+ }
+ if result.Matches == nil || *result.Matches != 3 {
+ t.Fatalf("matches = %v", result.Matches)
+ }
+ if result.JudgeDegraded == nil || *result.JudgeDegraded {
+ t.Fatalf("judgeDegraded = %v", result.JudgeDegraded)
+ }
+ if result.DegradedReason != nil {
+ t.Fatalf("degradedReason = %v", result.DegradedReason)
+ }
+ if result.SearchCredits == nil || *result.SearchCredits != 1.5 {
+ t.Fatalf("searchCredits = %v", result.SearchCredits)
+ }
+ if result.ResultsJudged == nil || *result.ResultsJudged != 8 {
+ t.Fatalf("resultsJudged = %v", result.ResultsJudged)
+ }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MonitorSearchTarget.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MonitorSearchTarget.java
new file mode 100644
index 000000000..28d063136
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MonitorSearchTarget.java
@@ -0,0 +1,52 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
+import java.util.List;
+
+/**
+ * A search monitor target ({@code type = "search"}).
+ *
+ * <p>Search targets run one or more queries on each monitor check and report how many
+ * results matched the monitor's goal. They live in a monitor's {@code targets} list
+ * alongside scrape and crawl targets.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class MonitorSearchTarget {
+ private String id;
+ private final String type = "search";
+ private List<String> queries;
+ private String searchWindow;
+ private List<String> includeDomains;
+ private List<String> excludeDomains;
+ private Integer maxResults;
+
+ public MonitorSearchTarget() {}
+
+ public MonitorSearchTarget(List<String> queries) {
+ this.queries = queries;
+ }
+
+ public String getId() { return id; }
+ public void setId(String id) { this.id = id; }
+
+ /** Always {@code "search"}. */
+ public String getType() { return type; }
+
+ public List<String> getQueries() { return queries; }
+ public void setQueries(List<String> queries) { this.queries = queries; }
+
+ /** One of {@code 5m}, {@code 15m}, {@code 1h}, {@code 6h}, {@code 24h}, {@code 7d}. */
+ public String getSearchWindow() { return searchWindow; }
+ public void setSearchWindow(String searchWindow) { this.searchWindow = searchWindow; }
+
+ public List<String> getIncludeDomains() { return includeDomains; }
+ public void setIncludeDomains(List<String> includeDomains) { this.includeDomains = includeDomains; }
+
+ public List<String> getExcludeDomains() { return excludeDomains; }
+ public void setExcludeDomains(List<String> excludeDomains) { this.excludeDomains = excludeDomains; }
+
+ public Integer getMaxResults() { return maxResults; }
+ public void setMaxResults(Integer maxResults) { this.maxResults = maxResults; }
+}
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/MonitorSearchTargetResult.java b/apps/java-sdk/src/main/java/com/firecrawl/models/MonitorSearchTargetResult.java
new file mode 100644
index 000000000..81cb6c9f4
--- /dev/null
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/MonitorSearchTargetResult.java
@@ -0,0 +1,38 @@
+package com.firecrawl.models;
+
+import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+
+/**
+ * Per-target result for a search monitor target ({@code type = "search"}).
+ *
+ * <p>Reported on a {@link MonitorCheck}'s {@code targetResults} for each search target,
+ * summarizing how the check's queries performed and what the judge concluded.
+ */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MonitorSearchTargetResult {
+ private String targetId;
+ private String type = "search";
+ private Boolean searchCompleted;
+ private Integer resultCount;
+ private Integer matches;
+ private String summary;
+ private Boolean judgeDegraded;
+ private String degradedReason;
+ private Number searchCredits;
+ private Number judgeCredits;
+ private Integer resultsJudged;
+
+ public String getTargetId() { return targetId; }
+ /** Always {@code "search"}. */
+ public String getType() { return type; }
+ public Boolean getSearchCompleted() { return searchCompleted; }
+ public Integer getResultCount() { return resultCount; }
+ public Integer getMatches() { return matches; }
+ public String getSummary() { return summary; }
+ public Boolean getJudgeDegraded() { return judgeDegraded; }
+ /** Nullable reason the judge was degraded for this target. */
+ public String getDegradedReason() { return degradedReason; }
+ public Number getSearchCredits() { return searchCredits; }
+ public Number getJudgeCredits() { return judgeCredits; }
+ public Integer getResultsJudged() { return resultsJudged; }
+}
diff --git a/apps/php-sdk/src/Client/FirecrawlClient.php b/apps/php-sdk/src/Client/FirecrawlClient.php
index 8660c0c91..d1992107d 100644
--- a/apps/php-sdk/src/Client/FirecrawlClient.php
+++ b/apps/php-sdk/src/Client/FirecrawlClient.php
@@ -400,7 +400,14 @@ final class FirecrawlClient
* Create a scheduled monitor.
*
* @param array<string, mixed> $schedule
- * @param list<array<string, mixed>> $targets
+ * @param list<array<string, mixed>> $targets Each target array has a
+ * `type` of `scrape`, `crawl`, or `search`, plus an optional
+ * `id`. `scrape`/`crawl` targets carry `urls`/`url` and
+ * `scrapeOptions`/`crawlOptions`. `search` targets carry
+ * `queries` (list<string>, required) and optional
+ * `searchWindow` (one of `5m`, `15m`, `1h`, `6h`, `24h`, `7d`),
+ * `includeDomains` (list<string>), `excludeDomains`
+ * (list<string>), and `maxResults` (int). All keys are camelCase.
* @param array<string, mixed>|null $webhook
* @param array<string, mixed>|null $notification
*/
diff --git a/apps/php-sdk/src/Models/Monitor.php b/apps/php-sdk/src/Models/Monitor.php
index 19f97a4f8..5a37177fb 100644
--- a/apps/php-sdk/src/Models/Monitor.php
+++ b/apps/php-sdk/src/Models/Monitor.php
@@ -7,7 +7,14 @@ namespace Firecrawl\Models;
final class Monitor
{
/**
- * @param list<array<string, mixed>> $targets
+ * @param list<array<string, mixed>> $targets Each target array has a
+ * `type` of `scrape`, `crawl`, or `search`, plus an optional
+ * `id`. `scrape`/`crawl` targets carry `urls`/`url` and
+ * `scrapeOptions`/`crawlOptions`. `search` targets carry
+ * `queries` (list<string>, required) and optional
+ * `searchWindow` (one of `5m`, `15m`, `1h`, `6h`, `24h`, `7d`),
+ * `includeDomains` (list<string>), `excludeDomains`
+ * (list<string>), and `maxResults` (int). All keys are camelCase.
* @param array<string, mixed>|null $schedule
* @param array<string, mixed>|null $webhook
* @param array<string, mixed>|null $notification
diff --git a/apps/php-sdk/src/Models/MonitorCheck.php b/apps/php-sdk/src/Models/MonitorCheck.php
index 935f20c04..113a85301 100644
--- a/apps/php-sdk/src/Models/MonitorCheck.php
+++ b/apps/php-sdk/src/Models/MonitorCheck.php
@@ -9,7 +9,15 @@ class MonitorCheck
{
/**
* @param array<string, mixed> $summary
- * @param mixed $targetResults
+ * @param mixed $targetResults A list of per-target
+ * result arrays. Each entry has a `targetId` (string) and a `type`
+ * of `scrape`, `crawl`, or `search`. `scrape`/`crawl` results carry
+ * `expectedJobs` (list<string>) and `crawlId` (string). `search`
+ * results carry optional `searchCompleted` (bool), `resultCount`
+ * (int), `matches` (int), `summary` (string), `judgeDegraded`
+ * (bool), `degradedReason` (string|null), `searchCredits` (number),
+ * `judgeCredits` (number), and `resultsJudged` (int). All keys are
+ * camelCase.
* @param mixed $notificationStatus
*/
public function __construct(
diff --git a/apps/php-sdk/tests/Unit/ModelsTest.php b/apps/php-sdk/tests/Unit/ModelsTest.php
index 0ffa3e577..2b77c6300 100644
--- a/apps/php-sdk/tests/Unit/ModelsTest.php
+++ b/apps/php-sdk/tests/Unit/ModelsTest.php
@@ -13,6 +13,8 @@ use Firecrawl\Models\HighlightsFormat;
use Firecrawl\Models\QueryFormat;
use Firecrawl\Models\QuestionFormat;
use Firecrawl\Models\ScrapeOptions;
+use Firecrawl\Models\Monitor;
+use Firecrawl\Models\MonitorCheck;
it('hydrates CreditUsage from nested data key', function (): void {
$response = [
@@ -366,3 +368,72 @@ it('serializes question and highlights formats in ScrapeOptions', function (): v
it('rejects invalid query format mode', function (): void {
QueryFormat::with('What is Firecrawl?', 'quoted');
})->throws(InvalidArgumentException::class, "query mode must be 'freeform' or 'directQuote'");
+
+it('hydrates a search target and goal/judgeEnabled in Monitor', function (): void {
+ $monitor = Monitor::fromArray([
+ 'id' => 'mon-1',
+ 'name' => 'AI news',
+ 'status' => 'active',
+ 'goal' => 'Track new AI launches',
+ 'judgeEnabled' => true,
+ 'targets' => [
+ [
+ 'id' => 'tgt-1',
+ 'type' => 'search',
+ 'queries' => ['firecrawl release', 'firecrawl changelog'],
+ 'searchWindow' => '24h',
+ 'includeDomains' => ['firecrawl.dev'],
+ 'excludeDomains' => ['spam.example'],
+ 'maxResults' => 10,
+ ],
+ ],
+ ]);
+
+ expect($monitor->getGoal())->toBe('Track new AI launches');
+ expect($monitor->getJudgeEnabled())->toBeTrue();
+ expect($monitor->getTargets())->toHaveCount(1);
+
+ $target = $monitor->getTargets()[0];
+ expect($target['type'])->toBe('search');
+ expect($target['queries'])->toBe(['firecrawl release', 'firecrawl changelog']);
+ expect($target['searchWindow'])->toBe('24h');
+ expect($target['includeDomains'])->toBe(['firecrawl.dev']);
+ expect($target['excludeDomains'])->toBe(['spam.example']);
+ expect($target['maxResults'])->toBe(10);
+});
+
+it('passes through a search target result on MonitorCheck', function (): void {
+ $check = MonitorCheck::fromArray([
+ 'id' => 'chk-1',
+ 'monitorId' => 'mon-1',
+ 'status' => 'completed',
+ 'targetResults' => [
+ [
+ 'targetId' => 'tgt-1',
+ 'type' => 'search',
+ 'searchCompleted' => true,
+ 'resultCount' => 7,
+ 'matches' => 2,
+ 'summary' => 'Two new launches detected.',
+ 'judgeDegraded' => false,
+ 'degradedReason' => null,
+ 'searchCredits' => 7,
+ 'judgeCredits' => 2,
+ 'resultsJudged' => 7,
+ ],
+ ],
+ ]);
+
+ $results = $check->getTargetResults();
+ expect($results)->toBeArray();
+ expect($results[0]['type'])->toBe('search');
+ expect($results[0]['searchCompleted'])->toBeTrue();
+ expect($results[0]['resultCount'])->toBe(7);
+ expect($results[0]['matches'])->toBe(2);
+ expect($results[0]['summary'])->toBe('Two new launches detected.');
+ expect($results[0]['judgeDegraded'])->toBeFalse();
+ expect($results[0]['degradedReason'])->toBeNull();
+ expect($results[0]['searchCredits'])->toBe(7);
+ expect($results[0]['judgeCredits'])->toBe(2);
+ expect($results[0]['resultsJudged'])->toBe(7);
+});
diff --git a/apps/ruby-sdk/lib/firecrawl/models/monitor.rb b/apps/ruby-sdk/lib/firecrawl/models/monitor.rb
index 60ec34027..eae07f794 100644
--- a/apps/ruby-sdk/lib/firecrawl/models/monitor.rb
+++ b/apps/ruby-sdk/lib/firecrawl/models/monitor.rb
@@ -2,6 +2,81 @@
module Firecrawl
module Models
+ # A scrape, crawl, or search target stored on a monitor.
+ #
+ # Targets are forwarded to the API verbatim, so callers may also pass
+ # plain Hashes with camelCase keys. This class is a convenience for
+ # building well-formed target payloads (and is what {#to_h} emits).
+ #
+ # Search targets (+type: "search"+) use the +queries+, +search_window+,
+ # +include_domains+, +exclude_domains+, and +max_results+ fields.
+ class MonitorTarget
+ attr_reader :id, :type, :urls, :url, :scrape_options, :crawl_options,
+ :queries, :search_window, :include_domains,
+ :exclude_domains, :max_results
+
+ def initialize(data)
+ @id = data["id"]
+ @type = data["type"]
+ @urls = data["urls"]
+ @url = data["url"]
+ @scrape_options = data["scrapeOptions"]
+ @crawl_options = data["crawlOptions"]
+ # search target fields
+ @queries = data["queries"]
+ @search_window = data["searchWindow"]
+ @include_domains = data["includeDomains"]
+ @exclude_domains = data["excludeDomains"]
+ @max_results = data["maxResults"]
+ end
+
+ def to_h
+ {
+ "id" => @id,
+ "type" => @type,
+ "urls" => @urls,
+ "url" => @url,
+ "scrapeOptions" => @scrape_options,
+ "crawlOptions" => @crawl_options,
+ "queries" => @queries,
+ "searchWindow" => @search_window,
+ "includeDomains" => @include_domains,
+ "excludeDomains" => @exclude_domains,
+ "maxResults" => @max_results,
+ }.compact
+ end
+ end
+
+ # A per-target result on a monitor check.
+ #
+ # Search targets (+type: "search"+) populate the +search_completed+,
+ # +result_count+, +matches+, +summary+, +judge_degraded+,
+ # +degraded_reason+, +search_credits+, +judge_credits+, and
+ # +results_judged+ fields.
+ class MonitorTargetResult
+ attr_reader :target_id, :type, :expected_jobs, :crawl_id,
+ :search_completed, :result_count, :matches, :summary,
+ :judge_degraded, :degraded_reason, :search_credits,
+ :judge_credits, :results_judged
+
+ def initialize(data)
+ @target_id = data["targetId"]
+ @type = data["type"]
+ @expected_jobs = data["expectedJobs"]
+ @crawl_id = data["crawlId"]
+ # search target result fields
+ @search_completed = data["searchCompleted"]
+ @result_count = data["resultCount"]
+ @matches = data["matches"]
+ @summary = data["summary"]
+ @judge_degraded = data["judgeDegraded"]
+ @degraded_reason = data["degradedReason"]
+ @search_credits = data["searchCredits"]
+ @judge_credits = data["judgeCredits"]
+ @results_judged = data["resultsJudged"]
+ end
+ end
+
class Monitor
attr_reader :id, :name, :status, :schedule, :next_run_at, :last_run_at,
:current_check_id, :targets, :webhook, :notification,
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index 840506716..a620506e8 100644
--- a/apps/ruby-sdk/test/firecrawl/client_test.rb
+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb
@@ -939,4 +939,97 @@ class ClientTest < Minitest::Test
doc = @client.parse(file, Firecrawl::Models::ParseOptions.new(formats: ["markdown"]))
assert_equal "# Parsed", doc.markdown
end
+
+ # ================================================================
+ # MONITOR - SEARCH TARGET
+ # ================================================================
+
+ def test_create_monitor_forwards_search_target
+ captured = nil
+ stub_request(:post, "#{BASE_URL}/v2/monitor")
+ .with { |req| captured = JSON.parse(req.body); true }
+ .to_return(
+ status: 200,
+ body: JSON.generate(success: true, data: { id: "mon_1", judgeEnabled: true, goal: "g" }),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ search_target = {
+ "type" => "search",
+ "queries" => ["firecrawl launch"],
+ "searchWindow" => "24h",
+ "includeDomains" => ["firecrawl.dev"],
+ "excludeDomains" => ["spam.com"],
+ "maxResults" => 20,
+ }
+
+ monitor = @client.create_monitor(
+ name: "Search monitor",
+ schedule: { "text" => "every 30 minutes" },
+ targets: [search_target],
+ goal: "g",
+ judge_enabled: true
+ )
+
+ assert_equal search_target, captured["targets"][0]
+ assert_equal "search", captured["targets"][0]["type"]
+ assert_equal "24h", captured["targets"][0]["searchWindow"]
+ assert_equal "g", monitor.goal
+ assert_equal true, monitor.judge_enabled
+ end
+
+ def test_monitor_search_target_model_to_h
+ target = Firecrawl::Models::MonitorTarget.new(
+ "type" => "search",
+ "queries" => ["a", "b"],
+ "searchWindow" => "1h",
+ "includeDomains" => ["x.com"],
+ "excludeDomains" => ["y.com"],
+ "maxResults" => 5
+ )
+
+ assert_equal "search", target.type
+ assert_equal ["a", "b"], target.queries
+ assert_equal "1h", target.search_window
+ assert_equal 5, target.max_results
+ assert_equal(
+ {
+ "type" => "search",
+ "queries" => ["a", "b"],
+ "searchWindow" => "1h",
+ "includeDomains" => ["x.com"],
+ "excludeDomains" => ["y.com"],
+ "maxResults" => 5,
+ },
+ target.to_h
+ )
+ end
+
+ def test_monitor_search_target_result_model
+ result = Firecrawl::Models::MonitorTargetResult.new(
+ "targetId" => "tgt_1",
+ "type" => "search",
+ "searchCompleted" => true,
+ "resultCount" => 10,
+ "matches" => 3,
+ "summary" => "found stuff",
+ "judgeDegraded" => false,
+ "degradedReason" => nil,
+ "searchCredits" => 1.5,
+ "judgeCredits" => 0.5,
+ "resultsJudged" => 8
+ )
+
+ assert_equal "tgt_1", result.target_id
+ assert_equal "search", result.type
+ assert_equal true, result.search_completed
+ assert_equal 10, result.result_count
+ assert_equal 3, result.matches
+ assert_equal "found stuff", result.summary
+ assert_equal false, result.judge_degraded
+ assert_nil result.degraded_reason
+ assert_in_delta 1.5, result.search_credits
+ assert_in_delta 0.5, result.judge_credits
+ assert_equal 8, result.results_judged
+ end
end
diff --git a/apps/rust-sdk/src/monitor.rs b/apps/rust-sdk/src/monitor.rs
index c28b137c9..9f06f1723 100644
--- a/apps/rust-sdk/src/monitor.rs
+++ b/apps/rust-sdk/src/monitor.rs
@@ -48,6 +48,59 @@ pub struct UpdateMonitorRequest {
pub judge_enabled: Option<bool>,
}
+/// Search window for a [`MonitorSearchTarget`]: how far back the search
+/// should look for results on each run.
+#[derive(Deserialize, Serialize, Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MonitorSearchWindow {
+ #[serde(rename = "5m")]
+ FiveMinutes,
+ #[serde(rename = "15m")]
+ FifteenMinutes,
+ #[serde(rename = "1h")]
+ OneHour,
+ #[serde(rename = "6h")]
+ SixHours,
+ #[serde(rename = "24h")]
+ TwentyFourHours,
+ #[serde(rename = "7d")]
+ SevenDays,
+}
+
+/// A search monitor target. Serialize this and place it (as JSON) into the
+/// `targets` of a [`CreateMonitorRequest`] or [`UpdateMonitorRequest`].
+///
+/// The `type` discriminator is always `"search"`.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Clone)]
+#[serde(rename_all = "camelCase", tag = "type", rename = "search")]
+pub struct MonitorSearchTarget {
+ pub id: Option<String>,
+ pub queries: Vec<String>,
+ pub search_window: Option<MonitorSearchWindow>,
+ pub include_domains: Option<Vec<String>>,
+ pub exclude_domains: Option<Vec<String>>,
+ pub max_results: Option<u32>,
+}
+
+/// Per-target result for a search target on a [`MonitorCheck`]. Decode the
+/// entries of [`MonitorCheck::target_results`] into this when the target's
+/// `type` is `"search"`.
+#[serde_with::skip_serializing_none]
+#[derive(Deserialize, Serialize, Debug, Clone)]
+#[serde(rename_all = "camelCase", tag = "type", rename = "search")]
+pub struct MonitorSearchTargetResult {
+ pub target_id: String,
+ pub search_completed: Option<bool>,
+ pub result_count: Option<u32>,
+ pub matches: Option<u32>,
+ pub summary: Option<String>,
+ pub judge_degraded: Option<bool>,
+ pub degraded_reason: Option<String>,
+ pub search_credits: Option<f64>,
+ pub judge_credits: Option<f64>,
+ pub results_judged: Option<u32>,
+}
+
#[derive(Deserialize, Serialize, Debug, Default, Clone)]
#[serde(rename_all = "camelCase")]
pub struct MonitorSummary {
@@ -431,3 +484,78 @@ impl Client {
Ok(response.data)
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn search_target_serializes_to_camel_case_wire_format() {
+ let target = MonitorSearchTarget {
+ id: Some("t1".to_string()),
+ queries: vec!["firecrawl funding".to_string(), "firecrawl news".to_string()],
+ search_window: Some(MonitorSearchWindow::TwentyFourHours),
+ include_domains: Some(vec!["techcrunch.com".to_string()]),
+ exclude_domains: None,
+ max_results: Some(10),
+ };
+
+ let json = serde_json::to_value(&target).unwrap();
+ assert_eq!(json["type"], "search");
+ assert_eq!(json["id"], "t1");
+ assert_eq!(json["queries"][0], "firecrawl funding");
+ assert_eq!(json["searchWindow"], "24h");
+ assert_eq!(json["includeDomains"][0], "techcrunch.com");
+ assert_eq!(json["maxResults"], 10);
+ // skip_serializing_none drops absent fields.
+ assert!(json.get("excludeDomains").is_none());
+ }
+
+ #[test]
+ fn search_target_round_trips() {
+ let raw = serde_json::json!({
+ "type": "search",
+ "queries": ["rust release"],
+ "searchWindow": "7d",
+ "maxResults": 5
+ });
+ let target: MonitorSearchTarget = serde_json::from_value(raw).unwrap();
+ assert_eq!(target.queries, vec!["rust release".to_string()]);
+ assert_eq!(target.search_window, Some(MonitorSearchWindow::SevenDays));
+ assert_eq!(target.max_results, Some(5));
+ assert!(target.id.is_none());
+ }
+
+ #[test]
+ fn search_target_result_deserializes_from_wire_format() {
+ let raw = serde_json::json!({
+ "targetId": "t1",
+ "type": "search",
+ "searchCompleted": true,
+ "resultCount": 12,
+ "matches": 3,
+ "summary": "Found new funding coverage",
+ "judgeDegraded": false,
+ "degradedReason": null,
+ "searchCredits": 2.5,
+ "judgeCredits": 1.0,
+ "resultsJudged": 12
+ });
+ let result: MonitorSearchTargetResult = serde_json::from_value(raw).unwrap();
+ assert_eq!(result.target_id, "t1");
+ assert_eq!(result.search_completed, Some(true));
+ assert_eq!(result.result_count, Some(12));
+ assert_eq!(result.matches, Some(3));
+ assert_eq!(result.summary.as_deref(), Some("Found new funding coverage"));
+ assert_eq!(result.judge_degraded, Some(false));
+ assert_eq!(result.degraded_reason, None);
+ assert_eq!(result.search_credits, Some(2.5));
+ assert_eq!(result.judge_credits, Some(1.0));
+ assert_eq!(result.results_judged, Some(12));
+
+ let json = serde_json::to_value(&result).unwrap();
+ assert_eq!(json["type"], "search");
+ assert_eq!(json["targetId"], "t1");
+ assert_eq!(json["searchCredits"], 2.5);
+ }
+}