Skip to content

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

Add country option to v2 search in seven SDKs (#4574)

claude[bot]b09eef415506
diff --git a/apps/go-sdk/options.go b/apps/go-sdk/options.go
index b9533aa4c..c1bd481b4 100644
--- a/apps/go-sdk/options.go
+++ b/apps/go-sdk/options.go
@@ -171,6 +171,7 @@ type SearchOptions struct {
Limit *int `json:"limit,omitempty"`
TBS *string `json:"tbs,omitempty"`
Location *string `json:"location,omitempty"`
+ Country *string `json:"country,omitempty"`
IgnoreInvalidURLs *bool `json:"ignoreInvalidURLs,omitempty"`
Timeout *int `json:"timeout,omitempty"`
Highlights *bool `json:"highlights,omitempty"`
diff --git a/apps/go-sdk/options_test.go b/apps/go-sdk/options_test.go
index 40c80df09..5a2774d3e 100644
--- a/apps/go-sdk/options_test.go
+++ b/apps/go-sdk/options_test.go
@@ -173,6 +173,26 @@ func TestSearchOptionsSerializesHighlights(t *testing.T) {
}
}
+func TestSearchOptionsSerializesCountry(t *testing.T) {
+ payload, err := json.Marshal(SearchOptions{Country: String("de")})
+ if err != nil {
+ t.Fatalf("Marshal SearchOptions: %v", err)
+ }
+
+ if !strings.Contains(string(payload), `"country":"de"`) {
+ t.Fatalf("serialized search options = %s", payload)
+ }
+
+ payload, err = json.Marshal(SearchOptions{})
+ if err != nil {
+ t.Fatalf("Marshal SearchOptions: %v", err)
+ }
+
+ if strings.Contains(string(payload), `"country"`) {
+ t.Fatalf("serialized search options without country = %s", payload)
+ }
+}
+
func TestAuditMetadataSerializesAcrossRequestOptions(t *testing.T) {
metadata := &AuditMetadata{Username: "[email protected]"}
for name, options := range map[string]interface{}{
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.java b/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.java
index 1553d4f65..585203b8b 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/SearchOptions.java
@@ -16,6 +16,7 @@ public class SearchOptions {
private Integer limit;
private String tbs;
private String location;
+ private String country;
private Boolean ignoreInvalidURLs;
private Integer timeout;
private Boolean highlights;
@@ -31,6 +32,7 @@ public class SearchOptions {
public Integer getLimit() { return limit; }
public String getTbs() { return tbs; }
public String getLocation() { return location; }
+ public String getCountry() { return country; }
public Boolean getIgnoreInvalidURLs() { return ignoreInvalidURLs; }
public Integer getTimeout() { return timeout; }
public Boolean getHighlights() { return highlights; }
@@ -47,6 +49,7 @@ public class SearchOptions {
private Integer limit;
private String tbs;
private String location;
+ private String country;
private Boolean ignoreInvalidURLs;
private Integer timeout;
private Boolean highlights;
@@ -69,6 +72,8 @@ public class SearchOptions {
public Builder tbs(String tbs) { this.tbs = tbs; return this; }
/** Location for search results (e.g., "US"). */
public Builder location(String location) { this.location = location; return this; }
+ /** Country code to geo-target search results (e.g., "us"). */
+ public Builder country(String country) { this.country = country; return this; }
/** Ignore invalid URLs in results. */
public Builder ignoreInvalidURLs(Boolean ignoreInvalidURLs) { this.ignoreInvalidURLs = ignoreInvalidURLs; return this; }
/** Timeout in milliseconds. */
@@ -89,6 +94,7 @@ public class SearchOptions {
o.limit = this.limit;
o.tbs = this.tbs;
o.location = this.location;
+ o.country = this.country;
o.ignoreInvalidURLs = this.ignoreInvalidURLs;
o.timeout = this.timeout;
o.highlights = this.highlights;
diff --git a/apps/java-sdk/src/test/java/com/firecrawl/SearchOptionsTest.java b/apps/java-sdk/src/test/java/com/firecrawl/SearchOptionsTest.java
index 7b8f1dc54..0e991dc76 100644
--- a/apps/java-sdk/src/test/java/com/firecrawl/SearchOptionsTest.java
+++ b/apps/java-sdk/src/test/java/com/firecrawl/SearchOptionsTest.java
@@ -5,6 +5,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
import com.firecrawl.models.SearchOptions;
import org.junit.jupiter.api.Test;
+import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -22,4 +23,15 @@ class SearchOptionsTest {
assertFalse(disabled.get("highlights").asBoolean());
assertFalse(omitted.has("highlights"));
}
+
+ @Test
+ void serializesCountryOption() {
+ ObjectMapper mapper = new ObjectMapper();
+ JsonNode set = mapper.valueToTree(
+ SearchOptions.builder().country("de").build());
+ JsonNode omitted = mapper.valueToTree(SearchOptions.builder().build());
+
+ assertEquals("de", set.get("country").asText());
+ assertFalse(omitted.has("country"));
+ }
}
diff --git a/apps/java-sdk/src/test/java/com/firecrawl/SearchTest.java b/apps/java-sdk/src/test/java/com/firecrawl/SearchTest.java
index 46c977f79..dfb0d5ade 100644
--- a/apps/java-sdk/src/test/java/com/firecrawl/SearchTest.java
+++ b/apps/java-sdk/src/test/java/com/firecrawl/SearchTest.java
@@ -153,6 +153,24 @@ class SearchTest {
System.out.println(" Results: " + results.getWeb().size());
}
+ @Test
+ @EnabledIfEnvironmentVariable(named = "FIRECRAWL_API_KEY", matches = ".*\\S.*")
+ void testSearchWithCountry() {
+ System.out.println("\n=== Test: Search with Country ===");
+
+ SearchData results = client.search("best coffee shops",
+ SearchOptions.builder()
+ .country("de")
+ .limit(5)
+ .build());
+
+ assertNotNull(results.getWeb(), "Web results should not be null");
+
+ System.out.println("✓ Search with country completed");
+ System.out.println(" Country: de");
+ System.out.println(" Results: " + results.getWeb().size());
+ }
+
@Test
@EnabledIfEnvironmentVariable(named = "FIRECRAWL_API_KEY", matches = ".*\\S.*")
void testSearchWithTimeFilter() {
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/batch.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/batch.test.ts
index df09e1746..ffc07eaec 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/batch.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/batch.test.ts
@@ -4,6 +4,7 @@
import Firecrawl from "../../../index";
import { config } from "dotenv";
import { getIdentity, getApiUrl } from "./utils/idmux";
+import { testTimeoutMs, waitForJob, withRateLimitRetry } from "./utils/rateLimit";
import { describe, test, expect, beforeAll } from "@jest/globals";
config();
@@ -13,7 +14,7 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-batch" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
describe("v2.batch e2e", () => {
@@ -22,19 +23,21 @@ describe("v2.batch e2e", () => {
"https://docs.firecrawl.dev",
"https://firecrawl.dev",
];
- const job = await client.batchScrape(urls, { options: { formats: ["markdown"] }, pollInterval: 1, timeout: 180 });
+ const start = await client.startBatchScrape(urls, { options: { formats: ["markdown"] } });
+ const job = await waitForJob(() => client.getBatchScrapeStatus(start.id), { pollInterval: 1, timeout: 210 });
expect(["completed", "failed"]).toContain(job.status);
expect(job.completed).toBeGreaterThanOrEqual(0);
expect(job.total).toBeGreaterThanOrEqual(0);
expect(Array.isArray(job.data)).toBe(true);
- }, 240_000);
+ }, testTimeoutMs(362_000));
test("batch scrape with wait returns job id for error retrieval", async () => {
const urls = [
"https://docs.firecrawl.dev",
"https://firecrawl.dev",
];
- const job = await client.batchScrape(urls, { options: { formats: ["markdown"] }, pollInterval: 1, timeout: 180 });
+ const start = await client.startBatchScrape(urls, { options: { formats: ["markdown"] } });
+ const job = await waitForJob(() => client.getBatchScrapeStatus(start.id), { pollInterval: 1, timeout: 210 });
// Verify job has id field
expect(job.id).toBeDefined();
expect(typeof job.id).toBe("string");
@@ -44,7 +47,7 @@ describe("v2.batch e2e", () => {
expect(errors).toHaveProperty("robotsBlocked");
expect(Array.isArray(errors.errors)).toBe(true);
expect(Array.isArray(errors.robotsBlocked)).toBe(true);
- }, 240_000);
+ }, testTimeoutMs(512_000));
test("start batch minimal and status", async () => {
const urls = ["https://docs.firecrawl.dev", "https://firecrawl.dev"];
@@ -57,11 +60,11 @@ describe("v2.batch e2e", () => {
// Verify status includes id field
expect(status.id).toBeDefined();
expect(status.id).toBe(start.id);
- }, 120_000);
+ }, testTimeoutMs(151_000));
test("wait batch with all params", async () => {
const urls = ["https://docs.firecrawl.dev", "https://firecrawl.dev"];
- const job = await client.batchScrape(urls, {
+ const start = await client.startBatchScrape(urls, {
options: {
formats: [
"markdown",
@@ -74,14 +77,13 @@ describe("v2.batch e2e", () => {
ignoreInvalidURLs: true,
maxConcurrency: 2,
zeroDataRetention: false,
- pollInterval: 1,
- timeout: 180,
});
+ const job = await waitForJob(() => client.getBatchScrapeStatus(start.id), { pollInterval: 1, timeout: 210 });
expect(["completed", "failed", "cancelled"]).toContain(job.status);
expect(job.completed).toBeGreaterThanOrEqual(0);
expect(job.total).toBeGreaterThanOrEqual(0);
expect(Array.isArray(job.data)).toBe(true);
- }, 300_000);
+ }, testTimeoutMs(362_000));
test("cancel batch", async () => {
const urls = ["https://docs.firecrawl.dev", "https://firecrawl.dev"];
@@ -89,6 +91,6 @@ describe("v2.batch e2e", () => {
expect(typeof start.id).toBe("string");
const cancelled = await client.cancelBatchScrape(start.id);
expect(cancelled).toBe(true);
- }, 120_000);
+ }, testTimeoutMs(151_000));
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/crawl.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/crawl.test.ts
index 97f36b5d8..4be07ed3f 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/crawl.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/crawl.test.ts
@@ -4,6 +4,7 @@
import Firecrawl from "../../../index";
import { config } from "dotenv";
import { getIdentity, getApiUrl } from "./utils/idmux";
+import { testTimeoutMs, waitForJob, withRateLimitRetry } from "./utils/rateLimit";
import { describe, test, expect, beforeAll } from "@jest/globals";
config();
@@ -13,7 +14,7 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-crawl" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
describe("v2.crawl e2e", () => {
@@ -23,21 +24,21 @@ describe("v2.crawl e2e", () => {
const job = await client.startCrawl("https://docs.firecrawl.dev", { limit: 3 });
expect(typeof job.id).toBe("string");
expect(typeof job.url).toBe("string");
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("start crawl with options", async () => {
if (!client) throw new Error();
const job = await client.startCrawl("https://docs.firecrawl.dev", { limit: 5, maxDiscoveryDepth: 2 });
expect(typeof job.id).toBe("string");
expect(typeof job.url).toBe("string");
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("start crawl with prompt", async () => {
if (!client) throw new Error();
const job = await client.startCrawl("https://firecrawl.dev", { prompt: "Extract all blog posts", limit: 3 });
expect(typeof job.id).toBe("string");
expect(typeof job.url).toBe("string");
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("get crawl status", async () => {
if (!client) throw new Error();
@@ -50,14 +51,14 @@ describe("v2.crawl e2e", () => {
expect(status.id).toBe(start.id);
// next/expiresAt may be null/undefined depending on state; check shape
expect(Array.isArray(status.data)).toBe(true);
- }, 120_000);
+ }, testTimeoutMs(151_000));
test("cancel crawl", async () => {
if (!client) throw new Error();
const start = await client.startCrawl("https://docs.firecrawl.dev", { limit: 3 });
const ok = await client.cancelCrawl(start.id);
expect(ok).toBe(true);
- }, 120_000);
+ }, testTimeoutMs(151_000));
test("get crawl errors", async () => {
if (!client) throw new Error();
@@ -73,12 +74,12 @@ describe("v2.crawl e2e", () => {
expect(typeof e.url === "string" || e.url == null).toBe(true);
expect(typeof e.error === "string" || e.error == null).toBe(true);
}
- }, 120_000);
+ }, testTimeoutMs(151_000));
test("get crawl errors with invalid id should throw", async () => {
if (!client) throw new Error();
await expect(client.getCrawlErrors("invalid-job-id-12345")).rejects.toThrow();
- }, 60_000);
+ }, testTimeoutMs(60_000));
test("get active crawls", async () => {
if (!client) throw new Error();
@@ -93,7 +94,7 @@ describe("v2.crawl e2e", () => {
expect(typeof c.options === "object").toBe(true);
}
}
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("get active crawls with running crawl", async () => {
if (!client) throw new Error();
@@ -104,20 +105,22 @@ describe("v2.crawl e2e", () => {
const ids = active.crawls.map(c => c.id);
expect(ids.includes(start.id)).toBe(true);
await client.cancelCrawl(start.id);
- }, 120_000);
+ }, testTimeoutMs(301_000));
test("crawl with wait", async () => {
if (!client) throw new Error();
- const job = await client.crawl("https://docs.firecrawl.dev", { limit: 3, maxDiscoveryDepth: 2, pollInterval: 1, timeout: 120 });
+ const start = await client.startCrawl("https://docs.firecrawl.dev", { limit: 3, maxDiscoveryDepth: 2 });
+ const job = await waitForJob(() => client.getCrawlStatus(start.id), { pollInterval: 1, timeout: 120 });
expect(["completed", "failed"]).toContain(job.status);
expect(job.completed).toBeGreaterThanOrEqual(0);
expect(job.total).toBeGreaterThanOrEqual(0);
expect(Array.isArray(job.data)).toBe(true);
- }, 180_000);
+ }, testTimeoutMs(272_000));
test("crawl with wait returns job id for error retrieval", async () => {
if (!client) throw new Error();
- const job = await client.crawl("https://docs.firecrawl.dev", { limit: 3, maxDiscoveryDepth: 2, pollInterval: 1, timeout: 120 });
+ const start = await client.startCrawl("https://docs.firecrawl.dev", { limit: 3, maxDiscoveryDepth: 2 });
+ const job = await waitForJob(() => client.getCrawlStatus(start.id), { pollInterval: 1, timeout: 120 });
// Verify job has id field
expect(job.id).toBeDefined();
expect(typeof job.id).toBe("string");
@@ -127,16 +130,17 @@ describe("v2.crawl e2e", () => {
expect(errors).toHaveProperty("robotsBlocked");
expect(Array.isArray(errors.errors)).toBe(true);
expect(Array.isArray(errors.robotsBlocked)).toBe(true);
- }, 180_000);
+ }, testTimeoutMs(422_000));
test("crawl with prompt and wait", async () => {
if (!client) throw new Error();
- const job = await client.crawl("https://docs.firecrawl.dev", { prompt: "Extract all blog posts", limit: 3, pollInterval: 1, timeout: 120 });
+ const start = await client.startCrawl("https://docs.firecrawl.dev", { prompt: "Extract all blog posts", limit: 3 });
+ const job = await waitForJob(() => client.getCrawlStatus(start.id), { pollInterval: 1, timeout: 120 });
expect(["completed", "failed"]).toContain(job.status);
expect(job.completed).toBeGreaterThanOrEqual(0);
expect(job.total).toBeGreaterThanOrEqual(0);
expect(Array.isArray(job.data)).toBe(true);
- }, 180_000);
+ }, testTimeoutMs(272_000));
test("crawl with scrape options", async () => {
if (!client) throw new Error();
@@ -145,7 +149,7 @@ describe("v2.crawl e2e", () => {
scrapeOptions: { formats: ["markdown", "links"], onlyMainContent: false, mobile: true },
});
expect(typeof job.id).toBe("string");
- }, 120_000);
+ }, testTimeoutMs(120_000));
test("crawl with json format object", async () => {
if (!client) throw new Error();
@@ -154,7 +158,7 @@ describe("v2.crawl e2e", () => {
scrapeOptions: { formats: [{ type: "json", prompt: "Extract page title", schema: { type: "object", properties: { title: { type: "string" } }, required: ["title"] } }] },
});
expect(typeof job.id).toBe("string");
- }, 120_000);
+ }, testTimeoutMs(120_000));
test("crawl all parameters", async () => {
if (!client) throw new Error();
@@ -187,13 +191,13 @@ describe("v2.crawl e2e", () => {
zeroDataRetention: false,
});
expect(typeof job.id).toBe("string");
- }, 180_000);
+ }, testTimeoutMs(180_000));
test("crawl params preview", async () => {
if (!client) throw new Error();
const params = await client.crawlParamsPreview("https://docs.firecrawl.dev", "Extract all blog posts and documentation");
expect(params && typeof params === "object").toBe(true);
// Optional fields may or may not be present; just assert object shape
- }, 60_000);
+ }, testTimeoutMs(60_000));
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/extract.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/extract.test.ts
index 2ad2d0424..3ff4279bc 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/extract.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/extract.test.ts
@@ -4,6 +4,7 @@
import Firecrawl from "../../../index";
import { config } from "dotenv";
import { getIdentity, getApiUrl } from "./utils/idmux";
+import { testTimeoutMs, waitForJob, withRateLimitRetry } from "./utils/rateLimit";
import { describe, test, expect, beforeAll } from "@jest/globals";
import { z } from "zod";
@@ -14,14 +15,38 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-extract" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
describe("v2.extract e2e", () => {
+ /**
+ * Starts an extract, then polls it. Mirrors client.extract, but keeps every
+ * request retryable: the wrapper cannot run client.extract again, because a
+ * second run would start a second job.
+ *
+ * The bound is 180s, the time an extract needs, and the same bound batch
+ * uses.
+ *
+ * The bound is not the whole cost of the test. startExtract goes through
+ * the wrapper too, so it can spend the retry budget before the poll starts:
+ * 150s for the start, plus 180 + 2 + 150 = 332s for the poll, so 482s. Each
+ * test below therefore carries a 333_000 ms base, which gives 483s. The
+ * unit test "every wrapped call in a test fits its budget" holds that sum.
+ */
+ async function extractAndWait(
+ args: Parameters<typeof client.startExtract>[0],
+ ) {
+ const started = await client.startExtract(args);
+ if (!started.id) return started;
+ return waitForJob(() => client.getExtractStatus(started.id!), {
+ timeout: 180,
+ });
+ }
+
test("extract minimal with prompt", async () => {
- const resp = await client.extract({ urls: ["https://docs.firecrawl.dev"], prompt: "Extract the main page title" });
+ const resp = await extractAndWait({ urls: ["https://docs.firecrawl.dev"], prompt: "Extract the main page title" });
expect(typeof resp.success === "boolean" || resp.success == null).toBe(true);
- }, 120_000);
+ }, testTimeoutMs(333_000));
test("extract with schema", async () => {
const schema = {
@@ -29,7 +54,7 @@ describe("v2.extract e2e", () => {
properties: { title: { type: "string" } },
required: ["title"],
} as const;
- const resp = await client.extract({
+ const resp = await extractAndWait({
urls: ["https://docs.firecrawl.dev"],
schema,
prompt: "Extract the main page title",
@@ -44,13 +69,13 @@ describe("v2.extract e2e", () => {
expect(typeof resp.data).toBe("object");
expect((resp.data as any).title).toBeTruthy();
}
- }, 180_000);
+ }, testTimeoutMs(333_000));
test("extract with zod schema", async () => {
const schema = z.object({
title: z.string(),
});
- const resp = await client.extract({
+ const resp = await extractAndWait({
urls: ["https://docs.firecrawl.dev"],
schema: schema,
prompt: "Extract the main page title",
@@ -65,6 +90,6 @@ describe("v2.extract e2e", () => {
expect(typeof resp.data).toBe("object");
expect(schema.safeParse(resp.data).success).toBe(true);
}
- }, 180_000);
+ }, testTimeoutMs(333_000));
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/map.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/map.test.ts
index 560b4e16f..2845b5cdc 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/map.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/map.test.ts
@@ -4,6 +4,7 @@
import Firecrawl from "../../../index";
import { config } from "dotenv";
import { getIdentity, getApiUrl } from "./utils/idmux";
+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";
import { describe, test, expect, beforeAll } from "@jest/globals";
config();
@@ -13,7 +14,7 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-map" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
describe("v2.map e2e", () => {
@@ -30,7 +31,7 @@ describe("v2.map e2e", () => {
expect(typeof first.url).toBe("string");
expect(first.url.startsWith("http")).toBe(true);
}
- }, 90_000);
+ }, testTimeoutMs(90_000));
test.each(["only", "skip", "include"]) ("with options sitemap=%s", async (sitemap) => {
if (!client) throw new Error();
@@ -50,6 +51,6 @@ describe("v2.map e2e", () => {
expect(typeof link.url).toBe("string");
expect(link.url.startsWith("http")).toBe(true);
}
- }, 120_000);
+ }, testTimeoutMs(120_000));
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/parse.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/parse.test.ts
index 11c327356..21d54e199 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/parse.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/parse.test.ts
@@ -1,6 +1,7 @@
import Firecrawl from "../../../index";
import { config } from "dotenv";
import { getIdentity, getApiUrl } from "./utils/idmux";
+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";
import { describe, test, expect, beforeAll } from "@jest/globals";
config();
@@ -10,7 +11,7 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-parse" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
describe("v2.parse e2e", () => {
@@ -41,7 +42,7 @@ describe("v2.parse e2e", () => {
expect(doc.markdown).toContain("JS SDK Parse E2E");
expect(doc.metadata?.creditsUsed).toBe(1);
},
- 60_000,
+ testTimeoutMs(60_000),
);
test(
@@ -62,6 +63,6 @@ describe("v2.parse e2e", () => {
),
).rejects.toThrow();
},
- 60_000,
+ testTimeoutMs(60_000),
);
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/scrape.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/scrape.test.ts
index e44663768..2edb21f83 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/scrape.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/scrape.test.ts
@@ -5,6 +5,7 @@ import Firecrawl from "../../../index";
import { z } from "zod";
import { config } from "dotenv";
import { getIdentity, getApiUrl } from "./utils/idmux";
+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";
import { describe, test, expect, beforeAll } from "@jest/globals";
config();
@@ -14,7 +15,7 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-scrape" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
describe("v2.scrape e2e", () => {
@@ -30,7 +31,7 @@ describe("v2.scrape e2e", () => {
if (!client) throw new Error();
const doc = await client.scrape("https://docs.firecrawl.dev");
assertValidDocument(doc);
- }, 60_000);
+ }, testTimeoutMs(60_000));
test("maximal: scrape with all options", async () => {
if (!client) throw new Error();
@@ -71,7 +72,7 @@ describe("v2.scrape e2e", () => {
maxAge: 60_000,
});
assertValidDocument(doc);
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("json format with zod schema (auto-converted internally)", async () => {
if (!client) throw new Error();
@@ -90,14 +91,14 @@ describe("v2.scrape e2e", () => {
],
});
expect(doc).toBeTruthy();
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("summary format returns summary string", async () => {
if (!client) throw new Error();
const doc = await client.scrape("https://firecrawl.dev", { formats: ["summary"] });
expect(typeof doc.summary).toBe("string");
expect((doc.summary || "").length).toBeGreaterThan(10);
- }, 90_000);
+ }, testTimeoutMs(90_000));
test.each([
["markdown", "markdown"],
@@ -119,7 +120,7 @@ describe("v2.scrape e2e", () => {
expect(Array.isArray(doc.links)).toBe(true);
expect((doc.links || []).length).toBeGreaterThan(0);
}
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("images format: extract all images from webpage", async () => {
if (!client) throw new Error();
@@ -131,7 +132,7 @@ describe("v2.scrape e2e", () => {
expect(doc.images?.length).toBeGreaterThan(0);
// Should find firecrawl logo/branding images
expect(doc.images?.some(img => img.includes("firecrawl") || img.includes("logo"))).toBe(true);
- }, 60_000);
+ }, testTimeoutMs(60_000));
test("images format: works with multiple formats", async () => {
if (!client) throw new Error();
@@ -152,12 +153,12 @@ describe("v2.scrape e2e", () => {
// Should discover additional images beyond those with obvious extensions
expect(doc.images?.length).toBeGreaterThanOrEqual(linkImages.length);
- }, 60_000);
+ }, testTimeoutMs(60_000));
test("invalid url should throw", async () => {
if (!client) throw new Error();
await expect(client.scrape("")).rejects.toThrow("URL cannot be empty");
await expect(client.scrape(" ")).rejects.toThrow("URL cannot be empty");
- });
+ }, testTimeoutMs(151_000));
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/search.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/search.test.ts
index b1b31ffd2..68e9becc3 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/search.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/search.test.ts
@@ -5,6 +5,7 @@ import Firecrawl from "../../../index";
import type { Document, SearchResultWeb, SearchResultNews, SearchResultImages } from "../../../index";
import { config } from "dotenv";
import { getIdentity, getApiUrl } from "./utils/idmux";
+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";
import { describe, test, expect, beforeAll } from "@jest/globals";
config();
@@ -14,7 +15,7 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-search" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
function collectTexts(entries: any[] | undefined): string[] {
@@ -72,7 +73,7 @@ describe("v2.search e2e", () => {
expect(results.news == null).toBe(true);
expect(results.images == null).toBe(true);
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("with sources web+news and limit", async () => {
if (!client) throw new Error();
@@ -93,7 +94,7 @@ describe("v2.search e2e", () => {
.map(r => (r.description || "").toString().toLowerCase());
const allWebText = (webTitles.concat(webDescriptions)).join(" ");
expect(allWebText.includes("firecrawl")).toBe(true);
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("result structure", async () => {
if (!client) throw new Error();
@@ -108,7 +109,7 @@ describe("v2.search e2e", () => {
expect(typeof result.description === "string" || result.description == null).toBe(true);
expect(result.url.startsWith("http")).toBe(true);
}
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("all parameters (comprehensive)", async () => {
if (!client) throw new Error();
@@ -196,7 +197,7 @@ describe("v2.search e2e", () => {
expect(result.url?.startsWith("http")).toBe(true);
}
}
- }, 120_000);
+ }, testTimeoutMs(120_000));
test("formats flexibility: list vs object", async () => {
if (!client) throw new Error();
@@ -212,7 +213,7 @@ describe("v2.search e2e", () => {
expect(results2).toBeTruthy();
expect(results1.web).toBeTruthy();
expect(results2.web).toBeTruthy();
- }, 90_000);
+ }, testTimeoutMs(151_000));
test("with json format object", async () => {
if (!client) throw new Error();
@@ -229,7 +230,7 @@ describe("v2.search e2e", () => {
});
expect(results).toBeTruthy();
expect(Array.isArray(results.web) || results.web == null).toBe(true);
- }, 90_000);
+ }, testTimeoutMs(90_000));
test("with summary format, documents include summary when present", async () => {
if (!client) throw new Error();
@@ -242,6 +243,6 @@ describe("v2.search e2e", () => {
expect(typeof docs[0].summary).toBe("string");
expect((docs[0].summary || "").length).toBeGreaterThan(5);
}
- }, 90_000);
+ }, testTimeoutMs(90_000));
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/usage.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/usage.test.ts
index e11d7527e..0d1a7e1b7 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/usage.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/usage.test.ts
@@ -4,6 +4,7 @@
import Firecrawl from "../../../index";
import { config } from "dotenv";
import { getIdentity, getApiUrl } from "./utils/idmux";
+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";
import { describe, test, expect, beforeAll } from "@jest/globals";
config();
@@ -13,7 +14,7 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-usage" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
describe("v2.usage e2e", () => {
@@ -21,17 +22,17 @@ describe("v2.usage e2e", () => {
const resp = await client.getConcurrency();
expect(typeof resp.concurrency).toBe("number");
expect(typeof resp.maxConcurrency).toBe("number");
- }, 60_000);
+ }, testTimeoutMs(60_000));
test("get_credit_usage", async () => {
const resp = await client.getCreditUsage();
expect(typeof resp.remainingCredits).toBe("number");
- }, 60_000);
+ }, testTimeoutMs(60_000));
test("get_token_usage", async () => {
const resp = await client.getTokenUsage();
expect(typeof resp.remainingTokens).toBe("number");
- }, 60_000);
+ }, testTimeoutMs(60_000));
test("get_queue_status", async () => {
const resp = await client.getQueueStatus();
@@ -39,6 +40,6 @@ describe("v2.usage e2e", () => {
expect(typeof resp.activeJobsInQueue).toBe("number");
expect(typeof resp.waitingJobsInQueue).toBe("number");
expect(typeof resp.maxConcurrency).toBe("number");
- }, 60_000);
+ }, testTimeoutMs(60_000));
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/utils/rateLimit.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/utils/rateLimit.ts
new file mode 100644
index 000000000..979ec8279
--- /dev/null
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/utils/rateLimit.ts
@@ -0,0 +1,257 @@
+/**
+ * Rate-limit retry for the v2 e2e suites.
+ *
+ * The e2e suites run against a live API. Each suite mints a CI identity through
+ * idmux, and that identity gets the base per-minute limits: 2/min for crawl and
+ * extract, 10/min for scrape, search and map, 500/min for job status. Several
+ * suites send more calls than that in one minute, so the API answers 429 and the
+ * suite fails.
+ *
+ * This helper wraps a client so every call waits for the limit window to reset
+ * and then runs again. It is test-only code. The shipped SDK keeps its own retry
+ * behaviour.
+ *
+ * Batch scrape creation counts against the scrape limit, not a limit of its
+ * own. Job status reads use the 500/min limit, so they almost never wait.
+ *
+ * The wrapper only runs a call again when the refused request created nothing.
+ * A single request is safe: the API rejected it, so no job exists. A composite
+ * method is not safe. It starts a job, then polls that job. The poll can hit
+ * the limit after the job exists, and a second run of the method would start a
+ * second job. The wrapper passes these methods straight through, so they get no
+ * retry. See COMPOSITE_METHODS.
+ *
+ * A suite that needs a job therefore does the two steps itself: it calls the
+ * start method, then waitForJob. Both calls go through the wrapper, so both
+ * retry, and the job starts once.
+ */
+
+/** Attempts per call, including the first one. */
+const MAX_ATTEMPTS = 3;
+
+/** Wait used when the error carries no reset time. */
+const FALLBACK_WAIT_MS = 30_000;
+
+/** Upper bound for one wait. The API window is 60 seconds. */
+const MAX_WAIT_MS = 75_000;
+
+/** Added to the reset time so the retry lands after the window, not on it. */
+const WAIT_BUFFER_MS = 1_000;
+
+/**
+ * Worst-case time the retry adds to one call.
+ *
+ * The first attempt does not wait. Every later attempt waits first, and one
+ * wait is never longer than MAX_WAIT_MS. The value comes from the two bounds
+ * above, so it cannot drift from them.
+ */
+export const RETRY_BUDGET_MS = (MAX_ATTEMPTS - 1) * MAX_WAIT_MS;
+
+/**
+ * Time waitForJob allows when the caller passes no timeout.
+ *
+ * Every caller now passes its own timeout, sized to the work it waits for.
+ * This value is only a backstop for a new caller that forgets one. Without a
+ * bound the poll loop runs until the jest timeout, which hides the reason.
+ *
+ * The value stays short because it cannot know the work. It fits the smallest
+ * base any suite passes to testTimeoutMs, which is 60_000 ms:
+ * 45_000 + 2_000 + RETRY_BUDGET_MS = 197_000 ms, inside the 210_000 ms of
+ * testTimeoutMs(60_000). So a forgotten timeout still reports "job did not
+ * finish" in every test the suites have today.
+ *
+ * A caller that waits for real work must pass a timeout. Size it to the work,
+ * not to the budget, then set the budget from the sum of the calls the test
+ * makes. The unit test "every wrapped call in a test fits its budget" holds
+ * that rule: it counts this bound, one poll interval, and the retry budget of
+ * every wrapped call in the test, and requires the sum to fit.
+ */
+export const DEFAULT_JOB_TIMEOUT_MS = 45_000;
+
+/**
+ * Jest timeout for a test that calls a wrapped client.
+ *
+ * Pass the base: the time the test needs when the API answers at once. The
+ * result adds one retry budget on top, so a test whose single call hits the
+ * limit still finishes inside its own timeout instead of failing on it.
+ *
+ * One retry budget covers one call. A test that makes several wrapped calls
+ * can spend the budget once per call, so the base must carry the rest. Do not
+ * pick the base by hand: take the number the unit test "every wrapped call in
+ * a test fits its budget" computes, which sums every call in the test.
+ */
+export function testTimeoutMs(baseMs: number): number {
+ return baseMs + RETRY_BUDGET_MS;
+}
+
+/**
+ * Client methods that start a job and then poll it.
+ *
+ * These never run again after a rate-limit error. A retry would call the whole
+ * method, which starts a second job. The single-request methods that the job
+ * waiters use inside, such as startCrawl and getCrawlStatus, keep their retry
+ * when a test calls them directly.
+ */
+export const COMPOSITE_METHODS: ReadonlySet<string> = new Set([
+ "crawl",
+ "crawlUrl",
+ "batchScrape",
+ "batchScrapeUrls",
+ "extract",
+ "agent",
+]);
+
+function sleep(ms: number): Promise<void> {
+ return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/** States a job stops in. Matches the waiters in src/v2/methods. */
+const TERMINAL_STATES = ["completed", "failed", "cancelled"];
+
+/** The part of a job snapshot this module reads. */
+interface JobSnapshot {
+ status?: string;
+}
+
+/**
+ * Polls a job that a test already started.
+ *
+ * The composite client methods, such as crawl, start a job and then poll it in
+ * one call, so the wrapper cannot run them again. A test uses this instead: it
+ * starts the job with the start method, then polls with the status method. Both
+ * calls go through the wrapper, so both keep their retry, and the job starts
+ * once. Compare waitForCrawlCompletion in src/v2/methods/crawl.ts, which this
+ * mirrors.
+ *
+ * @param getStatus Reads the job state. Call the wrapped client here.
+ * @param opts.pollInterval Seconds between reads. Least value is 1.
+ * @param opts.timeout Seconds to allow. Throws when the job runs longer.
+ * Defaults to DEFAULT_JOB_TIMEOUT_MS, so the loop always has a bound.
+ */
+export async function waitForJob<T extends JobSnapshot>(
+ getStatus: () => Promise<T>,
+ opts: { pollInterval?: number; timeout?: number } = {},
+): Promise<T> {
+ const pollIntervalMs = Math.max(1000, (opts.pollInterval ?? 2) * 1000);
+ const timeoutMs =
+ opts.timeout != null ? opts.timeout * 1000 : DEFAULT_JOB_TIMEOUT_MS;
+ const startedAt = Date.now();
+
+ let snapshot = await getStatus();
+ while (!TERMINAL_STATES.includes(snapshot.status ?? "")) {
+ if (Date.now() - startedAt > timeoutMs) {
+ throw new Error(
+ `job did not finish in ${timeoutMs / 1000}s. Last status: ${
+ snapshot.status
+ }`,
+ );
+ }
+ await sleep(pollIntervalMs);
+ snapshot = await getStatus();
+ }
+ return snapshot;
+}
+
+function isPromiseLike(value: unknown): value is Promise<unknown> {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ typeof (value as { then?: unknown }).then === "function"
+ );
+}
+
+/** True when the API refused the call because the per-minute limit is spent. */
+export function isRateLimitError(err: unknown): boolean {
+ if (typeof err !== "object" || err === null) return false;
+ const candidate = err as { status?: unknown; message?: unknown };
+ if (candidate.status === 429) return true;
+ return (
+ typeof candidate.message === "string" &&
+ /rate limit exceeded/i.test(candidate.message)
+ );
+}
+
+/** Milliseconds to wait before the next attempt. */
+export function rateLimitWaitMs(err: unknown): number {
+ let seconds: number | undefined;
+
+ const details = (err as { details?: Record<string, unknown> })?.details;
+ for (const key of ["retryAfter", "retryAfterSeconds"]) {
+ const value = details?.[key];
+ if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+ seconds = value;
+ break;
+ }
+ }
+
+ if (seconds === undefined) {
+ const message = (err as { message?: unknown })?.message;
+ const match =
+ typeof message === "string"
+ ? message.match(/retry after (\d+)\s*s/i)
+ : null;
+ if (match) seconds = Number(match[1]);
+ }
+
+ const waitMs =
+ seconds !== undefined && seconds > 0
+ ? seconds * 1000 + WAIT_BUFFER_MS
+ : FALLBACK_WAIT_MS;
+ return Math.min(waitMs, MAX_WAIT_MS);
+}
+
+async function runWithRetry<T>(
+ first: Promise<T>,
+ again: () => Promise<T>,
+ label: string,
+): Promise<T> {
+ let pending = first;
+
+ for (let attempt = 1; ; attempt++) {
+ try {
+ return await pending;
+ } catch (err) {
+ if (attempt >= MAX_ATTEMPTS || !isRateLimitError(err)) throw err;
+ const waitMs = rateLimitWaitMs(err);
+ console.warn(
+ `[e2e] ${label} hit the API rate limit. Waiting ${Math.round(
+ waitMs / 1000,
+ )}s, then attempt ${attempt + 1} of ${MAX_ATTEMPTS}.`,
+ );
+ await sleep(waitMs);
+ pending = again();
+ }
+ }
+}
+
+/**
+ * Wraps a client so each method call retries after a rate-limit error.
+ *
+ * The wrapper only covers the calls the test makes. Methods that return a value
+ * other than a promise pass through unchanged, and so do the composite methods
+ * listed in COMPOSITE_METHODS.
+ */
+export function withRateLimitRetry<T extends object>(client: T): T {
+ return new Proxy(client, {
+ get(target, prop) {
+ const value = (target as Record<string | symbol, unknown>)[prop];
+ if (typeof value !== "function") return value;
+
+ const name = String(prop);
+
+ return (...args: unknown[]) => {
+ const call = () =>
+ (value as (...a: unknown[]) => unknown).apply(target, args);
+ const result = call();
+ // A composite method already created a job, so never run it again.
+ if (COMPOSITE_METHODS.has(name)) return result;
+ if (!isPromiseLike(result)) return result;
+ return runWithRetry(
+ result,
+ call as () => Promise<unknown>,
+ name,
+ );
+ };
+ },
+ });
+}
diff --git a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/watcher.test.ts b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/watcher.test.ts
index cb55f21bc..9bb9ea7f7 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/watcher.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/e2e/v2/watcher.test.ts
@@ -2,6 +2,7 @@ import Firecrawl from "../../../index";
import { config } from "dotenv";
import { describe, test, expect, beforeAll } from "@jest/globals";
import { getIdentity } from "./utils/idmux";
+import { testTimeoutMs, withRateLimitRetry } from "./utils/rateLimit";
config();
@@ -10,7 +11,7 @@ let client: Firecrawl;
beforeAll(async () => {
const { apiKey } = await getIdentity({ name: "js-e2e-watcher" });
- client = new Firecrawl({ apiKey, apiUrl: API_URL });
+ client = withRateLimitRetry(new Firecrawl({ apiKey, apiUrl: API_URL }));
});
describe("v2.watcher e2e", () => {
@@ -52,7 +53,7 @@ describe("v2.watcher e2e", () => {
expect(snapshots).toBeGreaterThanOrEqual(1);
expect(documents).toBeGreaterThanOrEqual(0);
watcher.close();
- }, 240_000);
+ }, testTimeoutMs(240_000));
test("batch watcher with options (kind, pollInterval, timeout)", async () => {
// client is initialized in beforeAll
@@ -91,6 +92,6 @@ describe("v2.watcher e2e", () => {
expect(snapshots).toBeGreaterThanOrEqual(1);
expect(gotCompleted || final.status !== "completed").toBe(true);
watcher.close();
- }, 300_000);
+ }, testTimeoutMs(300_000));
});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/e2eRateLimitRetry.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/e2eRateLimitRetry.test.ts
new file mode 100644
index 000000000..900f8668a
--- /dev/null
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/e2eRateLimitRetry.test.ts
@@ -0,0 +1,501 @@
+import { describe, expect, jest, test } from "@jest/globals";
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import Firecrawl from "../../../index";
+import {
+ COMPOSITE_METHODS,
+ DEFAULT_JOB_TIMEOUT_MS,
+ RETRY_BUDGET_MS,
+ isRateLimitError,
+ rateLimitWaitMs,
+ testTimeoutMs,
+ waitForJob,
+ withRateLimitRetry,
+} from "../../e2e/v2/utils/rateLimit";
+
+type AsyncCall = () => Promise<string>;
+
+/** Reproduces the error the API returns when the per-minute limit is spent. */
+function rateLimitError(seconds: number): Error & { status: number } {
+ const err = new Error(
+ `Rate limit exceeded. Consumed (req/min): 3, Remaining (req/min): 0. ` +
+ `Upgrade your plan at https://firecrawl.dev/pricing for increased rate ` +
+ `limits or please retry after ${seconds}s, resets at Tue Sep 08 2026`,
+ ) as Error & { status: number };
+ err.status = 429;
+ return err;
+}
+
+/**
+ * Source with comments blanked out, newlines kept.
+ *
+ * The scans below count brackets and calls. A comment holding `waitForJob(`,
+ * a client call or a lone brace would corrupt both, so drop comments first.
+ * Strings are not comments: a suite passes paths such as "/blog/*", and a
+ * scan that took that for a comment would swallow the rest of the file.
+ */
+function stripComments(source: string): string {
+ let out = "";
+ let quote: string | undefined;
+
+ for (let i = 0; i < source.length; i++) {
+ const c = source[i];
+
+ if (quote !== undefined) {
+ out += c;
+ if (c === "\\") {
+ out += source[i + 1] ?? "";
+ i += 1;
+ } else if (c === quote) {
+ quote = undefined;
+ }
+ continue;
+ }
+
+ if (c === "'" || c === '"' || c === "`") {
+ quote = c;
+ out += c;
+ continue;
+ }
+
+ if (source.startsWith("/*", i)) {
+ const close = source.indexOf("*/", i + 2);
+ const end = close < 0 ? source.length : close + 2;
+ // Keep the newlines so line structure survives.
+ out += source.slice(i, end).replace(/[^\n]/g, "");
+ i = end - 1;
+ continue;
+ }
+
+ if (source.startsWith("//", i)) {
+ const line = source.indexOf("\n", i);
+ if (line < 0) break;
+ i = line - 1;
+ continue;
+ }
+
+ out += c;
+ }
+
+ return out;
+}
+
+/**
+ * Text of each `name(...)` call in source, by matching parentheses.
+ *
+ * A regex cannot do this. The calls hold arrow functions, objects and
+ * template strings, so the closing bracket is not the first one.
+ *
+ * Pass source that stripComments has already cleaned.
+ */
+function callsOf(source: string, name: string): string[] {
+ const found: string[] = [];
+
+ for (const match of source.matchAll(new RegExp(`\\b${name}\\(`, "g"))) {
+ const from = match.index!;
+ let i = from + match[0].length - 1;
+ let depth = 0;
+ let quote: string | undefined;
+
+ for (; i < source.length; i++) {
+ const c = source[i];
+ if (quote !== undefined) {
+ if (c === "\\") i += 1;
+ else if (c === quote) quote = undefined;
+ continue;
+ }
+ if (c === "'" || c === '"' || c === "`") {
+ quote = c;
+ continue;
+ }
+ if (c === "(" || c === "[" || c === "{") depth += 1;
+ else if (c === ")" || c === "]" || c === "}") {
+ depth -= 1;
+ if (depth === 0) break;
+ }
+ }
+ found.push(source.slice(from, i + 1));
+ }
+
+ return found;
+}
+
+/**
+ * Body of each test in a suite, including the test.each form.
+ *
+ * test.each takes the cases first and the test second, so the test body is
+ * the group after the cases.
+ */
+function testBodies(source: string): string[] {
+ const found: string[] = [];
+
+ for (const match of source.matchAll(/\btest(\.each)?\s*\(/g)) {
+ if (!match[1]) {
+ found.push(callsOf(source.slice(match.index!), "test")[0]);
+ continue;
+ }
+ const cases = callsOf(source.slice(match.index!), "test.each")[0];
+ const rest = source.slice(match.index! + cases.length);
+ const open = rest.indexOf("(");
+ // Reuse the matcher by giving it a name to anchor on.
+ const group = callsOf(`each${rest.slice(open)}`, "each")[0];
+ found.push(group);
+ }
+
+ return found;
+}
+
+/** Local async helpers in a suite, by name, with the body each one runs. */
+function localHelpers(source: string): Map<string, string> {
+ const found = new Map<string, string>();
+
+ for (const match of source.matchAll(/\n(\s*)async function (\w+)\(/g)) {
+ const start = match.index! + 1;
+ const close = source.indexOf(`\n${match[1]}}`, start);
+ found.set(match[2], source.slice(start, close < 0 ? undefined : close));
+ }
+
+ return found;
+}
+
+/**
+ * Worst case of one test body, and the wrapped calls it counts.
+ *
+ * Each waitForJob costs its bound, one poll interval and the retry budget of
+ * the status read. Each other wrapped client call costs the retry budget on
+ * its own. A local helper runs inside the test, so its calls count too.
+ */
+function worstCaseMs(
+ body: string,
+ helpers: Map<string, string>,
+): { calls: number; ms: number } {
+ let calls = 0;
+ let ms = 0;
+
+ const waits = callsOf(body, "waitForJob");
+ for (const wait of waits) {
+ const timeout = wait.match(/timeout:\s*(\d+)/);
+ const poll = wait.match(/pollInterval:\s*(\d+)/);
+ const bound = timeout
+ ? Number(timeout[1]) * 1000
+ : DEFAULT_JOB_TIMEOUT_MS;
+ ms +=
+ bound +
+ Math.max(1000, (poll ? Number(poll[1]) : 2) * 1000) +
+ RETRY_BUDGET_MS;
+ calls += 1;
+ }
+
+ // The status read sits inside waitForJob, so drop those calls before
+ // counting the rest. Longest first, so a shorter call is not cut twice.
+ let rest = body;
+ for (const wait of [...waits].sort((a, b) => b.length - a.length)) {
+ rest = rest.split(wait).join("");
+ }
+
+ const direct = rest.match(/client\.\w+\s*\(/g) ?? [];
+ ms += direct.length * RETRY_BUDGET_MS;
+ calls += direct.length;
+
+ for (const [name, helperBody] of helpers) {
+ const uses = rest.match(new RegExp(`\\b${name}\\s*\\(`, "g")) ?? [];
+ if (uses.length === 0) continue;
+ const inner = worstCaseMs(helperBody, new Map());
+ ms += uses.length * inner.ms;
+ calls += uses.length * inner.calls;
+ }
+
+ return { calls, ms };
+}
+
+describe("e2e rate-limit retry helper", () => {
+ test("recognises the rate-limit error and reads its reset time", () => {
+ expect(isRateLimitError(rateLimitError(1))).toBe(true);
+ expect(isRateLimitError({ status: 429 })).toBe(true);
+ expect(isRateLimitError(new Error("Bad request"))).toBe(false);
+ expect(isRateLimitError(undefined)).toBe(false);
+
+ // 1s reset plus the 1s buffer.
+ expect(rateLimitWaitMs(rateLimitError(1))).toBe(2000);
+ // A reset longer than the window is capped.
+ expect(rateLimitWaitMs(rateLimitError(600))).toBe(75_000);
+ // No reset time in the error, so the fallback applies.
+ expect(rateLimitWaitMs(new Error("Rate limit exceeded."))).toBe(30_000);
+ expect(rateLimitWaitMs({ details: { retryAfter: 2 } })).toBe(3000);
+ });
+
+ test("runs the call again after a rate-limit error", async () => {
+ const scrape = jest
+ .fn<() => Promise<string>>()
+ .mockRejectedValueOnce(rateLimitError(1))
+ .mockResolvedValueOnce("ok");
+ const client = withRateLimitRetry({ scrape });
+
+ await expect(client.scrape()).resolves.toBe("ok");
+ expect(scrape).toHaveBeenCalledTimes(2);
+ }, 30_000);
+
+ test("stops after the attempt bound and surfaces the error", async () => {
+ const scrape = jest
+ .fn<() => Promise<string>>()
+ .mockRejectedValue(rateLimitError(1));
+ const client = withRateLimitRetry({ scrape });
+
+ await expect(client.scrape()).rejects.toThrow(/Rate limit exceeded/);
+ expect(scrape).toHaveBeenCalledTimes(3);
+ }, 30_000);
+
+ test("passes other errors through without waiting", async () => {
+ const scrape = jest
+ .fn<() => Promise<string>>()
+ .mockRejectedValue(new Error("invalid url"));
+ const client = withRateLimitRetry({ scrape });
+
+ await expect(client.scrape()).rejects.toThrow("invalid url");
+ expect(scrape).toHaveBeenCalledTimes(1);
+ });
+
+ test("never runs a composite method again after a rate-limit error", async () => {
+ for (const name of COMPOSITE_METHODS) {
+ const method = jest.fn<AsyncCall>().mockRejectedValue(rateLimitError(1));
+ const client = withRateLimitRetry<Record<string, AsyncCall>>({
+ [name]: method,
+ });
+
+ const startedAt = Date.now();
+ await expect(client[name]()).rejects.toThrow(/Rate limit exceeded/);
+
+ // One call only. A second call would start a second job.
+ expect(method).toHaveBeenCalledTimes(1);
+ // The error surfaces at once, so no wait ran either.
+ expect(Date.now() - startedAt).toBeLessThan(1_000);
+ }
+ });
+
+ test("returns the result of a composite method that succeeds", async () => {
+ const crawl = jest.fn<AsyncCall>().mockResolvedValue("job");
+ const client = withRateLimitRetry({ crawl });
+
+ await expect(client.crawl()).resolves.toBe("job");
+ expect(crawl).toHaveBeenCalledTimes(1);
+ });
+
+ test("every composite name is a method on the client", () => {
+ const client = new Firecrawl({ apiKey: "test-key" }) as unknown as Record<
+ string,
+ unknown
+ >;
+
+ for (const name of COMPOSITE_METHODS) {
+ expect(typeof client[name]).toBe("function");
+ }
+ });
+
+ test("the client has no composite method the list misses", () => {
+ // Guard for a new waiter method. A composite starts a job through a
+ // *Waiter call, or forwards to another composite on this.
+ const source = readFileSync(
+ path.resolve(process.cwd(), "src/v2/client.ts"),
+ "utf-8",
+ );
+
+ const found = new Set<string>();
+ let current: string | undefined;
+ for (const line of source.split("\n")) {
+ const signature = line.match(/^\s{2}(?:async\s+)?([A-Za-z_$][\w$]*)\s*\(/);
+ if (signature) current = signature[1];
+ if (!current) continue;
+ const startsJob =
+ /\b\w+Waiter\s*\(/.test(line) ||
+ new RegExp(`this\\.(${[...COMPOSITE_METHODS].join("|")})\\s*\\(`).test(
+ line,
+ );
+ if (startsJob) found.add(current);
+ }
+
+ // The scan must see the known composites, or it stopped working.
+ expect([...found].sort()).toEqual([...COMPOSITE_METHODS].sort());
+ });
+
+ test("no e2e suite calls a composite method", () => {
+ // A composite call in a suite has no retry, so a rate limit fails the test
+ // at once. The suites start the job and poll it instead.
+ const dir = path.resolve(process.cwd(), "src/__tests__/e2e/v2");
+ const suites = readdirSync(dir).filter(name => name.endsWith(".test.ts"));
+ expect(suites.length).toBeGreaterThan(0);
+
+ const calls = new RegExp(
+ `client\\.(${[...COMPOSITE_METHODS].join("|")})\\s*\\(`,
+ );
+ const offenders = suites.filter(name =>
+ calls.test(readFileSync(path.join(dir, name), "utf-8")),
+ );
+
+ expect(offenders).toEqual([]);
+ });
+
+ test("waitForJob polls until the job reaches a terminal state", async () => {
+ const getStatus = jest
+ .fn<() => Promise<{ status: string }>>()
+ .mockResolvedValueOnce({ status: "scraping" })
+ .mockResolvedValueOnce({ status: "scraping" })
+ .mockResolvedValueOnce({ status: "completed" });
+
+ // pollInterval floors at 1s, so three reads take about two seconds.
+ await expect(
+ waitForJob(getStatus, { pollInterval: 1, timeout: 30 }),
+ ).resolves.toEqual({ status: "completed" });
+ expect(getStatus).toHaveBeenCalledTimes(3);
+ }, 30_000);
+
+ test("waitForJob gives up when the job outlives its timeout", async () => {
+ const getStatus = jest
+ .fn<() => Promise<{ status: string }>>()
+ .mockResolvedValue({ status: "scraping" });
+
+ await expect(
+ waitForJob(getStatus, { pollInterval: 1, timeout: 1 }),
+ ).rejects.toThrow(/did not finish in 1s/);
+ }, 30_000);
+
+ test("waitForJob bounds a caller that passes no timeout", async () => {
+ const getStatus = jest
+ .fn<() => Promise<{ status: string }>>()
+ .mockResolvedValue({ status: "scraping" });
+
+ // The default is a backstop for a caller that forgets a timeout, not a
+ // work allowance. A caller that waits for real work passes its own bound.
+ // So the default only has to fit the smallest base any suite uses, which
+ // is 60_000 ms. The last read can start just inside the bound and then
+ // spend the whole retry budget, so count both.
+ expect(DEFAULT_JOB_TIMEOUT_MS + 2_000 + RETRY_BUDGET_MS).toBeLessThan(
+ testTimeoutMs(60_000),
+ );
+
+ // Fake timers run the whole bound without waiting for it.
+ jest.useFakeTimers();
+ try {
+ const settled = expect(waitForJob(getStatus)).rejects.toThrow(
+ new RegExp(`did not finish in ${DEFAULT_JOB_TIMEOUT_MS / 1000}s`),
+ );
+ await jest.advanceTimersByTimeAsync(DEFAULT_JOB_TIMEOUT_MS + 5_000);
+ await settled;
+ } finally {
+ jest.useRealTimers();
+ }
+
+ expect(getStatus).toHaveBeenCalled();
+ }, 30_000);
+
+ test("the scan reads past comments and strings", () => {
+ // The guard is only as good as its parser, so hold the parser too. Each
+ // trap below broke an earlier version: a block comment with a call and a
+ // lone brace, a commented-out call, and a path that starts with "/*".
+ const suite = [
+ 'describe("fixture", () => {',
+ ' test("one start and one wait", async () => {',
+ ' /* waitForJob( here, with an unbalanced { brace */',
+ ' // client.notCounted(',
+ ' const started = await client.startThing({',
+ ' includePaths: ["/blog/*", "/docs/*"],',
+ ' });',
+ ' const job = await waitForJob(() => client.getThing(started.id), {',
+ ' pollInterval: 1,',
+ ' timeout: 60,',
+ ' });',
+ ' expect(job.status).toBe("completed");',
+ ' }, testTimeoutMs(220_000));',
+ "});",
+ ].join("\n");
+
+ const source = stripComments(suite);
+
+ // The traps are gone, and the code around them survived.
+ expect(source).not.toMatch(/waitForJob\( here/);
+ expect(source).not.toMatch(/notCounted/);
+ expect(source).toContain('includePaths: ["/blog/*", "/docs/*"]');
+ expect(source).toContain("timeout: 60,");
+
+ const bodies = testBodies(source);
+ expect(bodies).toHaveLength(1);
+
+ // One start call at the retry budget, and one wait at bound plus poll
+ // plus the retry budget of its status read.
+ const { calls, ms } = worstCaseMs(bodies[0], new Map());
+ expect(calls).toBe(2);
+ expect(ms).toBe(RETRY_BUDGET_MS + 60_000 + 1_000 + RETRY_BUDGET_MS);
+ expect(ms).toBeLessThan(testTimeoutMs(220_000));
+ });
+
+ test("every wrapped call in a test fits its budget", () => {
+ // Guard for the whole class of budget faults. A test spends the retry
+ // budget once per wrapped call, not once in total, so the budget has to
+ // cover the sum. Otherwise jest fires first and hides the specific
+ // message this helper exists to surface.
+ const dir = path.resolve(process.cwd(), "src/__tests__/e2e/v2");
+ const suites = readdirSync(dir).filter(name => name.endsWith(".test.ts"));
+ expect(suites.length).toBeGreaterThan(0);
+
+ let checked = 0;
+ let widest = 0;
+
+ for (const name of suites) {
+ const source = stripComments(
+ readFileSync(path.join(dir, name), "utf-8"),
+ );
+ const helpers = localHelpers(source);
+
+ // A helper that calls another helper would hide calls from the sum.
+ for (const [self, body] of helpers) {
+ for (const other of helpers.keys()) {
+ if (other === self) continue;
+ expect(body).not.toMatch(new RegExp(`\\b${other}\\s*\\(`));
+ }
+ }
+
+ const bodies = testBodies(source);
+ // The scan must see every test, or a budget goes unchecked.
+ expect(bodies.length).toBe(
+ (source.match(/\btest(?:\.each)?\s*\(/g) ?? []).length,
+ );
+
+ for (const body of bodies) {
+ const { calls, ms } = worstCaseMs(body, helpers);
+ if (calls === 0) continue;
+
+ // A test that calls the wrapped client needs a budget of its own.
+ // Without one jest allows 5s, which any single wait outlasts.
+ const budgets = body.match(/testTimeoutMs\((\d[\d_]*)\)/g);
+ expect(budgets).not.toBeNull();
+
+ const base = Number(budgets![budgets!.length - 1].replace(/\D/g, ""));
+ expect(ms).toBeLessThan(testTimeoutMs(base));
+
+ checked += 1;
+ widest = Math.max(widest, calls);
+ }
+ }
+
+ // The scan must see the known tests, or it stopped working.
+ expect(checked).toBeGreaterThanOrEqual(45);
+ expect(widest).toBeGreaterThanOrEqual(3);
+ });
+
+ test("the test timeout fits the worst-case serial retry", () => {
+ // Two waits at the 75s cap follow the first attempt.
+ expect(RETRY_BUDGET_MS).toBe(150_000);
+ expect(testTimeoutMs(60_000)).toBe(210_000);
+
+ // No pair of waits the helper can ask for exceeds the budget.
+ const longestWait = rateLimitWaitMs(rateLimitError(600));
+ expect(longestWait * 2).toBeLessThanOrEqual(RETRY_BUDGET_MS);
+ });
+
+ test("leaves values that are not promises alone", () => {
+ const watcher = jest.fn(() => ({ kind: "crawl" }));
+ const client = withRateLimitRetry({ watcher, apiUrl: "https://example.com" });
+
+ expect(client.watcher()).toEqual({ kind: "crawl" });
+ expect(client.apiUrl).toBe("https://example.com");
+ });
+});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/extract.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/extract.unit.test.ts
index d292c3e4a..95be255e6 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/extract.unit.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/extract.unit.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, test } from "@jest/globals";
+import { describe, expect, jest, test } from "@jest/globals";
import { startExtract } from "../../../v2/methods/extract";
import type { WebhookConfig } from "../../../v2/types";
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrapeAutoResume.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrapeAutoResume.test.ts
index 6ca30ba46..3c48f9b8b 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrapeAutoResume.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrapeAutoResume.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, test } from "@jest/globals";
+import { describe, expect, jest, test } from "@jest/globals";
import {
processingContinuesDelayMs,
scrape,
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-country.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-country.unit.test.ts
new file mode 100644
index 000000000..c206175e9
--- /dev/null
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-country.unit.test.ts
@@ -0,0 +1,32 @@
+import { describe, expect, jest, test } from "@jest/globals";
+import { search } from "../../../v2/methods/search";
+
+function httpMock() {
+ return {
+ post: jest.fn(async () => ({ status: 200, data: { success: true } })),
+ } as any;
+}
+
+describe("v2 search country", () => {
+ test("forwards the country option", async () => {
+ const http = httpMock();
+
+ await search(http, { query: "firecrawl", country: "de" });
+
+ expect(http.post).toHaveBeenCalledWith(
+ "/v2/search",
+ { query: "firecrawl", country: "de" },
+ {},
+ );
+ });
+
+ test("omits country when the caller does not set it", async () => {
+ const http = httpMock();
+
+ await search(http, { query: "firecrawl" });
+
+ expect(http.post).toHaveBeenCalledWith("/v2/search", { query: "firecrawl" }, {});
+ const payload = http.post.mock.calls[0][1] as Record<string, unknown>;
+ expect(payload).not.toHaveProperty("country");
+ });
+});
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts
index 966728b6c..f1a280b89 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/search-data-property.test.ts
@@ -1,3 +1,4 @@
+import { jest } from "@jest/globals";
import { search } from "../../../v2/methods/search";
const fakeHttp = {
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/v1-aliases.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/v1-aliases.test.ts
index 3747d9031..9212d479a 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/v1-aliases.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/v1-aliases.test.ts
@@ -1,3 +1,4 @@
+import { jest } from "@jest/globals";
import { FirecrawlClient } from "../../../v2/client";
const ALIAS_MAP: Record<string, string> = {
diff --git a/apps/js-sdk/firecrawl/src/v2/methods/search.ts b/apps/js-sdk/firecrawl/src/v2/methods/search.ts
index 9dc82c4c4..76a3c0e31 100644
--- a/apps/js-sdk/firecrawl/src/v2/methods/search.ts
+++ b/apps/js-sdk/firecrawl/src/v2/methods/search.ts
@@ -34,6 +34,7 @@ function prepareSearchPayload(req: SearchRequest): Record<string, unknown> {
if (req.limit != null) payload.limit = req.limit;
if (req.tbs != null) payload.tbs = req.tbs;
if (req.location != null) payload.location = req.location;
+ if (req.country != null) payload.country = req.country;
if (req.ignoreInvalidURLs != null)
payload.ignoreInvalidURLs = req.ignoreInvalidURLs;
if (req.timeout != null) payload.timeout = req.timeout;
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index a7d16d490..375269d45 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -849,6 +849,8 @@ export interface SearchRequest {
limit?: number;
tbs?: string;
location?: string;
+ /** ISO 3166-1 alpha-2 country code used to geo-target the search results. */
+ country?: string;
ignoreInvalidURLs?: boolean;
timeout?: number; // ms
/** Generate query-relevant highlights for search results. Defaults to true. */
diff --git a/apps/php-sdk/src/Models/SearchOptions.php b/apps/php-sdk/src/Models/SearchOptions.php
index bc413f3a7..b08340aa4 100644
--- a/apps/php-sdk/src/Models/SearchOptions.php
+++ b/apps/php-sdk/src/Models/SearchOptions.php
@@ -25,6 +25,7 @@ final class SearchOptions
private readonly ?array $includeDomains = null,
private readonly ?array $excludeDomains = null,
private readonly ?bool $highlights = null,
+ private readonly ?string $country = null,
) {}
/**
@@ -46,11 +47,12 @@ final class SearchOptions
?array $includeDomains = null,
?array $excludeDomains = null,
?bool $highlights = null,
+ ?string $country = null,
): self {
return new self(
$sources, $categories, $limit, $tbs, $location, $ignoreInvalidURLs,
$timeout, $scrapeOptions, $integration, $includeDomains, $excludeDomains,
- $highlights,
+ $highlights, $country,
);
}
@@ -65,6 +67,7 @@ final class SearchOptions
'limit' => $this->limit,
'tbs' => $this->tbs,
'location' => $this->location,
+ 'country' => $this->country,
'ignoreInvalidURLs' => $this->ignoreInvalidURLs,
'timeout' => $this->timeout,
'highlights' => $this->highlights,
diff --git a/apps/php-sdk/tests/Unit/SearchCountryTest.php b/apps/php-sdk/tests/Unit/SearchCountryTest.php
new file mode 100644
index 000000000..8d8cbf1c8
--- /dev/null
+++ b/apps/php-sdk/tests/Unit/SearchCountryTest.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+use Firecrawl\Models\SearchOptions;
+use GuzzleHttp\Psr7\Response;
+
+it('sends the search country option in the request body', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode(['success' => true, 'data' => ['web' => []]])),
+ ], $history);
+
+ $client->search('firecrawl', SearchOptions::with(country: 'de'));
+
+ $body = json_decode((string) $history[0]['request']->getBody(), true);
+ expect($body['query'])->toBe('firecrawl');
+ expect($body['country'])->toBe('de');
+});
+
+it('omits the search country option when it is unset', function (): void {
+ $history = new ArrayObject();
+ $client = fakeFirecrawlClient([
+ new Response(200, [], json_encode(['success' => true, 'data' => ['web' => []]])),
+ ], $history);
+
+ $client->search('firecrawl', SearchOptions::with(limit: 5));
+
+ $body = json_decode((string) $history[0]['request']->getBody(), true);
+ expect($body['limit'])->toBe(5);
+ expect(array_key_exists('country', $body))->toBeFalse();
+});
+
+it('serializes the search country option', function (): void {
+ $options = SearchOptions::with(country: 'de');
+
+ expect($options->toArray())->toBe(['country' => 'de']);
+});
diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_search_request_preparation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_search_request_preparation.py
index bddf6dc23..e429c810c 100644
--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_search_request_preparation.py
+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_search_request_preparation.py
@@ -1,6 +1,10 @@
+from unittest.mock import AsyncMock, Mock
+
import pytest
+from firecrawl.v2.client_async import AsyncFirecrawlClient
from firecrawl.v2.types import SearchRequest, ScrapeOptions
from firecrawl.v2.methods.aio.search import _prepare_search_request
+from firecrawl.v2.methods.aio.search import search as search_async
class TestAsyncSearchRequestPreparation:
@@ -31,6 +35,7 @@ class TestAsyncSearchRequestPreparation:
limit=10,
tbs="qdr:w",
location="US",
+ country="de",
ignore_invalid_urls=False,
timeout=30000,
scrape_options=scrape_opts,
@@ -38,6 +43,7 @@ class TestAsyncSearchRequestPreparation:
)
data = _prepare_search_request(request)
assert data["ignoreInvalidURLs"] is False
+ assert data["country"] == "de"
assert data["excludeDomains"] == ["example.com"]
assert "exclude_domains" not in data
assert "scrapeOptions" in data
@@ -58,6 +64,18 @@ class TestAsyncSearchRequestPreparation:
assert "query" in data
assert len(data) == 1
+ def test_country_is_included_when_set(self):
+ """Test that country reaches the prepared body."""
+ request = SearchRequest(query="test", country="de")
+ data = _prepare_search_request(request)
+ assert data["country"] == "de"
+
+ def test_country_is_omitted_when_unset(self):
+ """Test that the body omits country when it is not set."""
+ request = SearchRequest(query="test")
+ data = _prepare_search_request(request)
+ assert "country" not in data
+
def test_domain_filters_are_mutually_exclusive(self):
with pytest.raises(
ValueError,
@@ -75,4 +93,54 @@ class TestAsyncSearchRequestPreparation:
assert "scrapeOptions" in data
scrape_data = data["scrapeOptions"]
assert "onlyMainContent" in scrape_data
- assert "mobile" in scrape_data
\ No newline at end of file
+ assert "mobile" in scrape_data
+
+
+def _ok_response():
+ """Minimal successful search response."""
+ response = Mock()
+ response.status_code = 200
+ response.json.return_value = {"success": True, "data": {}}
+ return response
+
+
+def _mock_client():
+ client = Mock()
+ client.post = AsyncMock(return_value=_ok_response())
+ return client
+
+
+class TestAsyncSearchPostsCountry:
+ """The async client accepted country and dropped it. Pin the body."""
+
+ @pytest.mark.asyncio
+ async def test_country_reaches_the_posted_body(self):
+ """Test that the async search posts country."""
+ client = _mock_client()
+
+ await search_async(client, SearchRequest(query="test", country="de"))
+
+ path, body = client.post.call_args[0]
+ assert path == "/v2/search"
+ assert body["country"] == "de"
+
+ @pytest.mark.asyncio
+ async def test_posted_body_omits_country_when_unset(self):
+ """Test that the async search omits country when it is not set."""
+ client = _mock_client()
+
+ await search_async(client, SearchRequest(query="test"))
+
+ _path, body = client.post.call_args[0]
+ assert "country" not in body
+
+ @pytest.mark.asyncio
+ async def test_async_client_forwards_country_kwarg(self):
+ """AsyncFirecrawlClient.search takes **kwargs. Pin the passthrough."""
+ client = AsyncFirecrawlClient(api_key="fc-test")
+ client.async_http_client.post = AsyncMock(return_value=_ok_response())
+
+ await client.search("test", country="de")
+
+ _path, body = client.async_http_client.post.call_args[0]
+ assert body["country"] == "de"
diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_search_request_preparation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_search_request_preparation.py
index 221f2e2d0..0a7bcfe8f 100644
--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_search_request_preparation.py
+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_search_request_preparation.py
@@ -1,4 +1,7 @@
+from unittest.mock import Mock
+
import pytest
+from firecrawl.v2.client import FirecrawlClient
from firecrawl.v2.types import SearchRequest, ScrapeOptions, Source
from firecrawl.v2.methods.search import _prepare_search_request
@@ -42,6 +45,7 @@ class TestSearchRequestPreparation:
limit=10,
tbs="qdr:w",
location="US",
+ country="de",
ignore_invalid_urls=False,
timeout=30000,
highlights=False,
@@ -56,6 +60,7 @@ class TestSearchRequestPreparation:
assert data["limit"] == 10
assert data["tbs"] == "qdr:w"
assert data["location"] == "US"
+ assert data["country"] == "de"
assert data["timeout"] == 30000
assert data["highlights"] is False
@@ -110,6 +115,35 @@ class TestSearchRequestPreparation:
assert "query" in data
assert len(data) == 1 # Only query should be present
+ def test_country_is_included_when_set(self):
+ """Test that country reaches the prepared body."""
+ request = SearchRequest(query="test", country="de")
+ data = _prepare_search_request(request)
+
+ assert data["country"] == "de"
+
+ def test_country_is_omitted_when_unset(self):
+ """Test that the body omits country when it is not set."""
+ request = SearchRequest(query="test")
+ data = _prepare_search_request(request)
+
+ assert "country" not in data
+
+ def test_client_search_forwards_country(self):
+ """Test that the sync client puts country in the posted body."""
+ response = Mock()
+ response.status_code = 200
+ response.json.return_value = {"success": True, "data": {}}
+
+ client = FirecrawlClient(api_key="fc-test")
+ client.http_client.post = Mock(return_value=response)
+
+ client.search("test", country="de")
+
+ path, body = client.http_client.post.call_args[0]
+ assert path == "/v2/search"
+ assert body["country"] == "de"
+
def test_domain_filters_are_mutually_exclusive(self):
"""Test that include_domains and exclude_domains cannot both be set."""
with pytest.raises(
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index a975f05c6..f0e82a5d9 100644
--- a/apps/python-sdk/firecrawl/v2/client.py
+++ b/apps/python-sdk/firecrawl/v2/client.py
@@ -416,6 +416,7 @@ class FirecrawlClient:
limit: Optional[int] = None,
tbs: Optional[str] = None,
location: Optional[str] = None,
+ country: Optional[str] = None,
ignore_invalid_urls: Optional[bool] = None,
timeout: Optional[int] = None,
highlights: Optional[bool] = None,
@@ -432,6 +433,7 @@ class FirecrawlClient:
limit: Maximum number of results to return (default: 5)
tbs: Time-based search filter
location: Location string for search
+ country: Country code that geo-targets the search results
timeout: Request timeout in milliseconds (default: 300000)
highlights: Generate query-relevant highlights for search results
(default: true)
@@ -454,6 +456,7 @@ class FirecrawlClient:
limit=limit,
tbs=tbs,
location=location,
+ country=country,
ignore_invalid_urls=ignore_invalid_urls,
timeout=timeout,
highlights=highlights,
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 6f101c2bb..8d0af50ee 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -2175,6 +2175,7 @@ class SearchRequest(BaseModel):
limit: Optional[int] = 5
tbs: Optional[str] = None
location: Optional[str] = None
+ country: Optional[str] = None
ignore_invalid_urls: Optional[bool] = None
timeout: Optional[int] = 300000
highlights: Optional[bool] = None
diff --git a/apps/ruby-sdk/lib/firecrawl/models/search_options.rb b/apps/ruby-sdk/lib/firecrawl/models/search_options.rb
index 4df9bb4ad..c8070d7e1 100644
--- a/apps/ruby-sdk/lib/firecrawl/models/search_options.rb
+++ b/apps/ruby-sdk/lib/firecrawl/models/search_options.rb
@@ -5,7 +5,7 @@ module Firecrawl
# Options for a web search request.
class SearchOptions
FIELDS = %i[
- sources categories include_domains exclude_domains limit tbs location
+ sources categories include_domains exclude_domains limit tbs location country
ignore_invalid_urls timeout highlights scrape_options integration enterprise
].freeze
@@ -24,6 +24,7 @@ module Firecrawl
"limit" => limit,
"tbs" => tbs,
"location" => location,
+ "country" => country,
"ignoreInvalidURLs" => ignore_invalid_urls,
"timeout" => timeout,
"highlights" => highlights,
diff --git a/apps/ruby-sdk/test/firecrawl/client_test.rb b/apps/ruby-sdk/test/firecrawl/client_test.rb
index dca97e9ed..eda8d3630 100644
--- a/apps/ruby-sdk/test/firecrawl/client_test.rb
+++ b/apps/ruby-sdk/test/firecrawl/client_test.rb
@@ -592,6 +592,34 @@ class ClientTest < Minitest::Test
assert_equal 0, result.web.size
end
+ def test_search_with_country
+ stub_request(:post, "#{BASE_URL}/v2/search")
+ .with { |req| body = JSON.parse(req.body); body["country"] == "de" }
+ .to_return(
+ status: 200,
+ body: JSON.generate(data: { web: [], news: [], images: [] }),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ options = Firecrawl::Models::SearchOptions.new(limit: 5, country: "de")
+ result = @client.search("test query", options)
+ assert_equal 0, result.web.size
+ end
+
+ def test_search_omits_country_when_unset
+ stub_request(:post, "#{BASE_URL}/v2/search")
+ .with { |req| body = JSON.parse(req.body); !body.key?("country") }
+ .to_return(
+ status: 200,
+ body: JSON.generate(data: { web: [], news: [], images: [] }),
+ headers: { "Content-Type" => "application/json" }
+ )
+
+ options = Firecrawl::Models::SearchOptions.new(limit: 5)
+ result = @client.search("test query", options)
+ assert_equal 0, result.web.size
+ end
+
# ================================================================
# AGENT
# ================================================================
diff --git a/apps/rust-sdk/src/search.rs b/apps/rust-sdk/src/search.rs
index 9a7a328b9..001f4ac0d 100644
--- a/apps/rust-sdk/src/search.rs
+++ b/apps/rust-sdk/src/search.rs
@@ -35,6 +35,9 @@ pub struct SearchOptions {
/// Geographic location string for local search results.
pub location: Option<String>,
+ /// Country code to geo-target search results (e.g., "de").
+ pub country: Option<String>,
+
/// Whether to ignore invalid URLs in results.
pub ignore_invalid_urls: Option<bool>,
@@ -281,6 +284,22 @@ mod tests {
);
}
+ #[test]
+ fn serializes_country_option() {
+ let options = SearchOptions {
+ country: Some("de".to_string()),
+ ..Default::default()
+ };
+
+ assert_eq!(
+ serde_json::to_value(options).unwrap(),
+ json!({ "country": "de" })
+ );
+
+ let default_value = serde_json::to_value(SearchOptions::default()).unwrap();
+ assert!(default_value.get("country").is_none());
+ }
+
#[tokio::test]
async fn test_search_with_mock() {
let mut server = mockito::Server::new_async().await;