Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

feat(research): add paper search sort and row dates to the API proxy and SDKs (#5571)

Karan Lokchandani830fb0fb06c3
diff --git a/apps/api/src/controllers/v2/__tests__/research-proxy-zdr.test.ts b/apps/api/src/controllers/v2/__tests__/research-proxy-zdr.test.ts
index cf165b45a..24c5d22cc 100644
--- a/apps/api/src/controllers/v2/__tests__/research-proxy-zdr.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/research-proxy-zdr.test.ts
@@ -166,6 +166,28 @@ describe.each([
});
});
+describe("paper search sort", () => {
+ it("forwards sort=date_desc upstream", async () => {
+ await callRoute(
+ createResearchRouter(),
+ "/papers",
+ { query: "graph databases", sort: "date_desc" },
+ {},
+ );
+
+ expect(mocks.fetchResearchUpstream).toHaveBeenCalledWith(
+ expect.objectContaining({
+ path: "/v2/research/papers",
+ params: expect.objectContaining({
+ query: "graph databases",
+ sort: "date_desc",
+ }),
+ queryKeys: expect.arrayContaining(["sort"]),
+ }),
+ );
+ });
+});
+
describe("legacy research mount notice", () => {
function logNotice(flags: Record<string, unknown>) {
const req = makeReq({ query: "private research query" }, flags);
diff --git a/apps/api/src/controllers/v2/research-proxy.ts b/apps/api/src/controllers/v2/research-proxy.ts
index b38f03cb1..6c1033474 100644
--- a/apps/api/src/controllers/v2/research-proxy.ts
+++ b/apps/api/src/controllers/v2/research-proxy.ts
@@ -89,6 +89,7 @@ const searchPapersSchema = z.strictObject({
categories: multiString,
from: dateSchema,
to: dateSchema,
+ sort: z.enum(["relevance", "date_desc"]).optional(),
...commonQuery,
});
@@ -577,7 +578,7 @@ export function createResearchRouter(options: { legacy?: boolean } = {}) {
wrap(
createResearchController(
searchPapersSchema,
- ["query", "k", "authors", "categories", "from", "to"],
+ ["query", "k", "authors", "categories", "from", "to", "sort"],
{
kind: "research_paper_search",
table: "research_paper_searches",
diff --git a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj b/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj
index a72366b1e..ffdc857c8 100644
--- a/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj
+++ b/apps/dot-net-sdk/Firecrawl/Firecrawl.csproj
@@ -8,7 +8,7 @@
<!-- NuGet package metadata -->
<PackageId>firecrawl-sdk</PackageId>
- <Version>1.15.2</Version>
+ <Version>1.15.3</Version>
<Authors>Firecrawl</Authors>
<Company>Firecrawl</Company>
<Description>.NET SDK for Firecrawl, the context API for AI agents: search, scrape, parse, crawl, and map the web, and run Monitor jobs.</Description>
diff --git a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs
index b4cb4865c..d9ba6d299 100644
--- a/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs
+++ b/apps/dot-net-sdk/Firecrawl/FirecrawlClient.cs
@@ -555,7 +555,8 @@ public class FirecrawlClient
["authors"] = options?.Authors,
["categories"] = options?.Categories,
["from"] = options?.From,
- ["to"] = options?.To
+ ["to"] = options?.To,
+ ["sort"] = options?.Sort
}),
cancellationToken);
}
@@ -921,7 +922,7 @@ public class FirecrawlClient
// INTERNAL UTILITIES
// ================================================================
- private const string SdkOrigin = "[email protected]";
+ private const string SdkOrigin = "[email protected]";
private static Dictionary<string, object> BuildBody(object? options)
{
diff --git a/apps/dot-net-sdk/Firecrawl/Models/ResearchModels.cs b/apps/dot-net-sdk/Firecrawl/Models/ResearchModels.cs
index 38d00d717..188dcca72 100644
--- a/apps/dot-net-sdk/Firecrawl/Models/ResearchModels.cs
+++ b/apps/dot-net-sdk/Firecrawl/Models/ResearchModels.cs
@@ -17,6 +17,13 @@ public class PaperResult
public double? Score { get; set; }
public int? Year { get; set; }
public List<string>? Authors { get; set; }
+
+ [JsonPropertyName("createdDate")]
+ public string? CreatedDate { get; set; }
+
+ [JsonPropertyName("updateDate")]
+ public string? UpdateDate { get; set; }
+
public string? Venue { get; set; }
public string? Url { get; set; }
public Dictionary<string, object>? Signals { get; set; }
@@ -175,6 +182,13 @@ public class SearchPapersOptions
public List<string>? Categories { get; set; }
public string? From { get; set; }
public string? To { get; set; }
+
+ /// <summary>
+ /// "relevance" is the default. "date_desc" returns the newest of the most relevant
+ /// matches, newest first by created date. It does not list every paper in a date
+ /// range. Set <see cref="From"/> and optionally <see cref="To"/> to filter dates.
+ /// </summary>
+ public string? Sort { get; set; }
}
public class ReadPaperOptions
diff --git a/apps/elixir-sdk/lib/firecrawl.ex b/apps/elixir-sdk/lib/firecrawl.ex
index 477cebafd..55a15ae6d 100644
--- a/apps/elixir-sdk/lib/firecrawl.ex
+++ b/apps/elixir-sdk/lib/firecrawl.ex
@@ -257,14 +257,19 @@ defmodule Firecrawl do
from: [type: :string],
k: [type: :integer],
query: [type: :string, required: true],
+ sort: [type: {:in, [:relevance, :date_desc, "relevance", "date_desc"]}],
to: [type: :string]
])
- @research_search_papers_key_mapping %{authors: "authors", categories: "categories", from: "from", k: "k", query: "query", to: "to"}
+ @research_search_papers_key_mapping %{authors: "authors", categories: "categories", from: "from", k: "k", query: "query", sort: "sort", to: "to"}
@doc """
Search research papers.
+ `sort` accepts `relevance` (default) or `date_desc`, which returns the newest
+ of the most relevant matches, newest first by created date. It does not list
+ every paper in a date range; add `from` (and `to`) for that.
+
`GET /search/research/papers`
"""
@spec search_papers(keyword(), keyword()) :: response()
diff --git a/apps/elixir-sdk/mix.exs b/apps/elixir-sdk/mix.exs
index 437ae1116..bebb6f56b 100644
--- a/apps/elixir-sdk/mix.exs
+++ b/apps/elixir-sdk/mix.exs
@@ -1,7 +1,7 @@
defmodule Firecrawl.MixProject do
use Mix.Project
- @version "1.12.7"
+ @version "1.12.8"
@source_url "https://github.com/firecrawl/firecrawl/tree/main/apps/elixir-sdk"
def project do
diff --git a/apps/go-sdk/firecrawl.go b/apps/go-sdk/firecrawl.go
index f998b96be..162117f6c 100644
--- a/apps/go-sdk/firecrawl.go
+++ b/apps/go-sdk/firecrawl.go
@@ -675,6 +675,9 @@ func (c *Client) SearchPapers(ctx context.Context, query string, opts *SearchPap
if opts.To != "" {
values.Set("to", opts.To)
}
+ if opts.Sort != "" {
+ values.Set("sort", opts.Sort)
+ }
}
raw, err := c.http.get(ctx, "/v2/search/research/papers?"+values.Encode())
diff --git a/apps/go-sdk/models.go b/apps/go-sdk/models.go
index c66cb2d4d..f459de117 100644
--- a/apps/go-sdk/models.go
+++ b/apps/go-sdk/models.go
@@ -196,17 +196,19 @@ type MenuItemIdentifiers struct {
// PaperResult represents a ranked research paper result.
type PaperResult struct {
- PaperID string `json:"paperId"`
- PrimaryID string `json:"primaryId,omitempty"`
- IDs map[string]interface{} `json:"ids,omitempty"`
- Title string `json:"title,omitempty"`
- Abstract string `json:"abstract,omitempty"`
- Score *float64 `json:"score,omitempty"`
- Year *int `json:"year,omitempty"`
- Authors []string `json:"authors,omitempty"`
- Venue string `json:"venue,omitempty"`
- URL string `json:"url,omitempty"`
- Signals map[string]interface{} `json:"signals,omitempty"`
+ PaperID string `json:"paperId"`
+ PrimaryID string `json:"primaryId,omitempty"`
+ IDs map[string]interface{} `json:"ids,omitempty"`
+ Title string `json:"title,omitempty"`
+ Abstract string `json:"abstract,omitempty"`
+ Score *float64 `json:"score,omitempty"`
+ Year *int `json:"year,omitempty"`
+ Authors []string `json:"authors,omitempty"`
+ CreatedDate string `json:"createdDate,omitempty"`
+ UpdateDate string `json:"updateDate,omitempty"`
+ Venue string `json:"venue,omitempty"`
+ URL string `json:"url,omitempty"`
+ Signals map[string]interface{} `json:"signals,omitempty"`
}
// PaperMetadata represents paper metadata returned by inspect/read endpoints.
@@ -288,6 +290,10 @@ type SearchPapersOptions struct {
Categories []string `json:"categories,omitempty"`
From string `json:"from,omitempty"`
To string `json:"to,omitempty"`
+ // Sort is "relevance" (default) or "date_desc", which returns the newest of
+ // the most relevant matches, newest first by created date. It does not list
+ // every paper in a date range. Set From (and To) for that.
+ Sort string `json:"sort,omitempty"`
}
// ReadPaperOptions configures ReadPaper.
diff --git a/apps/go-sdk/version.go b/apps/go-sdk/version.go
index 3ee5d3ab3..3cdb1d859 100644
--- a/apps/go-sdk/version.go
+++ b/apps/go-sdk/version.go
@@ -9,4 +9,4 @@ package firecrawl
// Bump this when preparing a new release. The publish-go-sdk GitHub workflow
// reads this value and creates the corresponding monorepo-prefixed tag on
// merge to main.
-const Version = "1.16.10"
+const Version = "1.16.11"
diff --git a/apps/java-sdk/README.md b/apps/java-sdk/README.md
index c0fa033ee..18810a8be 100644
--- a/apps/java-sdk/README.md
+++ b/apps/java-sdk/README.md
@@ -82,13 +82,13 @@ Before using the Java SDK, ensure you have the following installed:
### Gradle (Kotlin DSL)
```kotlin
-implementation("com.firecrawl:firecrawl-java:1.18.8")
+implementation("com.firecrawl:firecrawl-java:1.18.9")
```
### Gradle (Groovy)
```groovy
-implementation 'com.firecrawl:firecrawl-java:1.18.8'
+implementation 'com.firecrawl:firecrawl-java:1.18.9'
```
### Maven
@@ -97,7 +97,7 @@ implementation 'com.firecrawl:firecrawl-java:1.18.8'
<dependency>
<groupId>com.firecrawl</groupId>
<artifactId>firecrawl-java</artifactId>
- <version>1.18.8</version>
+ <version>1.18.9</version>
</dependency>
```
@@ -478,14 +478,14 @@ gradle build
```bash
gradle jar
-# Output: build/libs/firecrawl-java-1.18.8.jar
+# Output: build/libs/firecrawl-java-1.18.9.jar
```
### Install Locally
```bash
gradle publishToMavenLocal
-# Now available as: com.firecrawl:firecrawl-java:1.18.8 in local Maven repository
+# Now available as: com.firecrawl:firecrawl-java:1.18.9 in local Maven repository
```
## Running Tests
diff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.kts
index e798d3a35..5b3aef931 100644
--- a/apps/java-sdk/build.gradle.kts
+++ b/apps/java-sdk/build.gradle.kts
@@ -4,7 +4,7 @@ plugins {
}
group = "com.firecrawl"
-version = "1.18.8"
+version = "1.18.9"
java {
sourceCompatibility = JavaVersion.VERSION_11
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java
index 49c324652..260343ed9 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java
@@ -37,7 +37,7 @@ import java.util.concurrent.ForkJoinPool;
public class FirecrawlClient {
private static final String DEFAULT_API_URL = "https://api.firecrawl.dev";
- private static final String SDK_ORIGIN = "[email protected]";
+ private static final String SDK_ORIGIN = "[email protected]";
private static final long DEFAULT_TIMEOUT_MS = 300_000; // 5 minutes
private static final int DEFAULT_MAX_RETRIES = 3;
private static final double DEFAULT_BACKOFF_FACTOR = 0.5;
diff --git a/apps/java-sdk/src/main/java/com/firecrawl/models/ResearchModels.java b/apps/java-sdk/src/main/java/com/firecrawl/models/ResearchModels.java
index 5b19645d4..b36814cf2 100644
--- a/apps/java-sdk/src/main/java/com/firecrawl/models/ResearchModels.java
+++ b/apps/java-sdk/src/main/java/com/firecrawl/models/ResearchModels.java
@@ -20,6 +20,10 @@ public final class ResearchModels {
public Double score;
public Integer year;
public List<String> authors;
+ @JsonProperty("createdDate")
+ public String createdDate;
+ @JsonProperty("updateDate")
+ public String updateDate;
public String venue;
public String url;
public Map<String, Object> signals;
@@ -101,6 +105,12 @@ public final class ResearchModels {
public List<String> categories;
public String from;
public String to;
+ /**
+ * "relevance" (default) or "date_desc", which returns the newest of the most
+ * relevant matches, newest first by created date. It does not list every paper
+ * in a date range. Set {@code from} (and {@code to}) for that.
+ */
+ public String sort;
}
public static class ReadPaperOptions {
diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.json
index d1102ced6..e29b28d09 100644
--- a/apps/js-sdk/firecrawl/package.json
+++ b/apps/js-sdk/firecrawl/package.json
@@ -1,6 +1,6 @@
{
"name": "@mendable/firecrawl-js",
- "version": "4.51.1",
+ "version": "4.52.0",
"description": "JavaScript SDK for Firecrawl, the context API for AI agents: search, scrape, parse, crawl, map, and interact with the web, run Agent and Monitor jobs, and search scientific papers (PubMed, bioRxiv, medRxiv, arXiv)",
"main": "dist/index.js",
"types": "dist/index.d.ts",
diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/research.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/research.test.ts
index 5dbc7cbe1..5f93bc18c 100644
--- a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/research.test.ts
+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/research.test.ts
@@ -38,6 +38,7 @@ describe("research.searchPapers", () => {
categories: ["cs.LG", "stat.ML"],
from: "2020-01-01",
to: "2024-12-31",
+ sort: "date_desc",
});
const url = calls[0];
expect(url.startsWith("/v2/search/research/papers?")).toBe(true);
@@ -48,6 +49,7 @@ describe("research.searchPapers", () => {
expect(qs.getAll("categories")).toEqual(["cs.LG", "stat.ML"]);
expect(qs.get("from")).toBe("2020-01-01");
expect(qs.get("to")).toBe("2024-12-31");
+ expect(qs.get("sort")).toBe("date_desc");
});
test("omits absent options", async () => {
diff --git a/apps/js-sdk/firecrawl/src/v2/methods/research.ts b/apps/js-sdk/firecrawl/src/v2/methods/research.ts
index 39e1fde6d..4738398e4 100644
--- a/apps/js-sdk/firecrawl/src/v2/methods/research.ts
+++ b/apps/js-sdk/firecrawl/src/v2/methods/research.ts
@@ -93,7 +93,7 @@ export class ResearchClient {
constructor(private readonly http: HttpClient) {}
/**
- * Search the research paper index by abstract relevance.
+ * Search the research paper index.
*
* Queries ~43M paper abstracts: PubMed, bioRxiv and medRxiv (about 90% of the
* corpus β€” biomedical and life sciences) plus arXiv (physics, mathematics,
@@ -104,7 +104,10 @@ export class ResearchClient {
*
* @param query Natural-language search query, e.g. `"CRISPR base editing
* off-target effects in primary human T cells"`.
- * @param options Optional filters (k, authors, categories, from, to). Note
+ * @param options Optional filters (k, authors, categories, from, to) and sort
+ * (`relevance` by default or `date_desc`). Date sorting returns the newest
+ * of the most relevant matches, newest first by created date. It does not
+ * list every paper in a date range; add `from` (and `to`) for that.
* `categories` here filters *paper* subject categories (e.g. `"q-bio.GN"`)
* and is unrelated to the `categories` option of `search()`.
*/
@@ -122,6 +125,7 @@ export class ResearchClient {
appendParam(params, "categories", options.categories);
appendParam(params, "from", options.from);
appendParam(params, "to", options.to);
+ appendParam(params, "sort", options.sort);
try {
const res = await this.http.get<SearchPapersResponse>(
withQuery(this.http.getOrigin(), `${BASE}/papers`, params),
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index ef9f3f09d..9ad1e9a74 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -2266,6 +2266,9 @@ export interface PaperResult {
ids?: IdMap;
title: string;
abstract: string;
+ authors?: string[];
+ createdDate?: string;
+ updateDate?: string;
/** Final ranking score (post-rerank when enabled). Not normalized. */
score: number;
/** Present on similarity results. */
@@ -2395,6 +2398,7 @@ export interface SearchPapersOptions {
from?: string;
/** Inclusive upper bound on created/updated date (lexicographic). */
to?: string;
+ sort?: "relevance" | "date_desc";
}
/** Options for `research.getPaper`. */
diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.py
index dea7075f6..58246c7fb 100644
--- a/apps/python-sdk/firecrawl/__init__.py
+++ b/apps/python-sdk/firecrawl/__init__.py
@@ -42,7 +42,7 @@ from .v1 import (
V1ChangeTrackingOptions,
)
-__version__ = "4.54.1"
+__version__ = "4.55.0"
# Define the logger for the Firecrawl project
logger: logging.Logger = logging.getLogger("firecrawl")
diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_research.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_research.py
index 2e23065e9..101aab225 100644
--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_research.py
+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_research.py
@@ -59,6 +59,7 @@ async def test_search_papers_builds_query_string_with_exploded_arrays():
categories=["cs.LG", "stat.ML"],
from_date="2020-01-01",
to_date="2024-12-31",
+ sort="date_desc",
)
path, qs = split(client.last_path)
assert path == "/v2/search/research/papers"
@@ -68,6 +69,7 @@ async def test_search_papers_builds_query_string_with_exploded_arrays():
assert qs["categories"] == ["cs.LG", "stat.ML"]
assert qs["from"] == ["2020-01-01"]
assert qs["to"] == ["2024-12-31"]
+ assert qs["sort"] == ["date_desc"]
@pytest.mark.asyncio
@@ -200,10 +202,11 @@ async def test_async_client_exposes_research_methods():
client.async_http_client = FakeAsyncHttpClient(
FakeResponse(200, {"success": True, "results": []})
)
- await client.search_papers("tau aggregation inhibitors", k=5)
+ await client.search_papers("tau aggregation inhibitors", k=5, sort="date_desc")
path, qs = split(client.async_http_client.last_path)
assert path == "/v2/search/research/papers"
assert qs["k"] == ["5"]
+ assert qs["sort"] == ["date_desc"]
@pytest.mark.asyncio
@@ -254,10 +257,11 @@ async def test_unified_async_client_delegates_all_research_methods():
client = _unified_client(FakeResponse(200, {"success": True, "results": []}))
http = client._v2_client.async_http_client
- await client.search_papers("tau aggregation inhibitors", k=5)
+ await client.search_papers("tau aggregation inhibitors", k=5, sort="date_desc")
path, qs = split(http.last_path)
assert path == "/v2/search/research/papers"
assert qs["k"] == ["5"]
+ assert qs["sort"] == ["date_desc"]
await client.inspect_paper("pmid:12345678")
path, _ = split(http.last_path)
diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_research.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_research.py
index 322a1c7ba..9ce5f9200 100644
--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_research.py
+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_research.py
@@ -68,6 +68,7 @@ class TestSearchPapers:
categories=["cs.LG", "stat.ML"],
from_date="2020-01-01",
to_date="2024-12-31",
+ sort="date_desc",
)
path, qs = split(client.last_path)
assert path == "/v2/search/research/papers"
@@ -79,6 +80,7 @@ class TestSearchPapers:
# from_date/to_date are sent as the wire names `from`/`to`
assert qs["from"] == ["2020-01-01"]
assert qs["to"] == ["2024-12-31"]
+ assert qs["sort"] == ["date_desc"]
def test_biomedical_query_is_passed_through_percent_encoded(self):
client = FakeHttpClient(FakeResponse(200, {"success": True, "results": []}))
@@ -281,10 +283,11 @@ class TestClientWiring:
def test_search_papers_routes_to_the_paper_index(self):
client = self._client(FakeResponse(200, {"success": True, "results": []}))
- client.search_papers("tau aggregation inhibitors", k=5)
+ client.search_papers("tau aggregation inhibitors", k=5, sort="date_desc")
path, qs = split(client.http_client.last_path)
assert path == "/v2/search/research/papers"
assert qs["k"] == ["5"]
+ assert qs["sort"] == ["date_desc"]
def test_read_paper_routes_to_the_paper_id_path(self):
client = self._client(FakeResponse(200, {"success": True, "paper": {}}))
@@ -343,11 +346,12 @@ class TestUnifiedClientWiring:
def test_search_papers_delegates_to_the_paper_index(self):
client = self._client(FakeResponse(200, {"success": True, "results": []}))
- client.search_papers("tau aggregation inhibitors", k=5)
+ client.search_papers("tau aggregation inhibitors", k=5, sort="date_desc")
path, qs = split(client._v2_client.http_client.last_path)
assert path == "/v2/search/research/papers"
assert qs["query"] == ["tau aggregation inhibitors"]
assert qs["k"] == ["5"]
+ assert qs["sort"] == ["date_desc"]
def test_inspect_paper_delegates(self):
client = self._client(FakeResponse(200, {"success": True, "paper": {}}))
diff --git a/apps/python-sdk/firecrawl/client.py b/apps/python-sdk/firecrawl/client.py
index 6b2b60616..e8cb558e7 100644
--- a/apps/python-sdk/firecrawl/client.py
+++ b/apps/python-sdk/firecrawl/client.py
@@ -19,7 +19,7 @@ Check example.py for other usage examples.
"""
from pathlib import Path
-from typing import Any, Dict, Optional, List, Union, BinaryIO
+from typing import Any, Dict, Optional, List, Union, BinaryIO, Literal
import logging
@@ -391,8 +391,14 @@ class Firecrawl:
# Research paper index (/v2/search/research) β€” delegates to the v2 client.
@doc(CLIENT_SEARCH_PAPERS_DOC)
- def search_papers(self, query: str, **kwargs):
- return self._v2_client.search_papers(query, **kwargs)
+ def search_papers(
+ self,
+ query: str,
+ *,
+ sort: Optional[Literal["relevance", "date_desc"]] = None,
+ **kwargs,
+ ):
+ return self._v2_client.search_papers(query, sort=sort, **kwargs)
@doc(CLIENT_INSPECT_PAPER_DOC)
def inspect_paper(self, paper_id: str):
@@ -545,8 +551,14 @@ class AsyncFirecrawl:
# Research paper index (/v2/search/research) β€” delegates to the v2 client.
@doc(ASYNC_CLIENT_SEARCH_PAPERS_DOC)
- async def search_papers(self, query: str, **kwargs):
- return await self._v2_client.search_papers(query, **kwargs)
+ async def search_papers(
+ self,
+ query: str,
+ *,
+ sort: Optional[Literal["relevance", "date_desc"]] = None,
+ **kwargs,
+ ):
+ return await self._v2_client.search_papers(query, sort=sort, **kwargs)
@doc(ASYNC_CLIENT_INSPECT_PAPER_DOC)
async def inspect_paper(self, paper_id: str):
diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.py
index 95d85164c..5d28b8cce 100644
--- a/apps/python-sdk/firecrawl/v2/client.py
+++ b/apps/python-sdk/firecrawl/v2/client.py
@@ -316,8 +316,14 @@ class FirecrawlClient:
# Research paper index (/v2/search/research)
@doc(CLIENT_SEARCH_PAPERS_DOC)
- def search_papers(self, query: str, **kwargs):
- return research_module.search_papers(self.http_client, query, **kwargs)
+ def search_papers(
+ self,
+ query: str,
+ *,
+ sort: Optional[Literal["relevance", "date_desc"]] = None,
+ **kwargs,
+ ):
+ return research_module.search_papers(self.http_client, query, sort=sort, **kwargs)
@doc(CLIENT_INSPECT_PAPER_DOC)
def inspect_paper(self, paper_id: str):
diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.py
index 0db2e7c8b..53babc234 100644
--- a/apps/python-sdk/firecrawl/v2/client_async.py
+++ b/apps/python-sdk/firecrawl/v2/client_async.py
@@ -185,8 +185,16 @@ class AsyncFirecrawlClient:
# Research paper index (/v2/search/research)
@doc(ASYNC_CLIENT_SEARCH_PAPERS_DOC)
- async def search_papers(self, query: str, **kwargs):
- return await async_research.search_papers(self.async_http_client, query, **kwargs)
+ async def search_papers(
+ self,
+ query: str,
+ *,
+ sort: Optional[Literal["relevance", "date_desc"]] = None,
+ **kwargs,
+ ):
+ return await async_research.search_papers(
+ self.async_http_client, query, sort=sort, **kwargs
+ )
@doc(ASYNC_CLIENT_INSPECT_PAPER_DOC)
async def inspect_paper(self, paper_id: str):
diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/research.py b/apps/python-sdk/firecrawl/v2/methods/aio/research.py
index f71cd1265..9cdda58d0 100644
--- a/apps/python-sdk/firecrawl/v2/methods/aio/research.py
+++ b/apps/python-sdk/firecrawl/v2/methods/aio/research.py
@@ -27,7 +27,7 @@ covering physics, mathematics and computer science.
``articleRank``, ``seedOverlap``, ``poolSize`` and so on.
"""
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Literal, Optional
from urllib.parse import quote
import warnings
@@ -82,6 +82,7 @@ async def search_papers(
categories: Optional[List[str]] = None,
from_date: Optional[str] = None,
to_date: Optional[str] = None,
+ sort: Optional[Literal["relevance", "date_desc"]] = None,
) -> Dict[str, Any]:
return await _get(
client,
@@ -95,6 +96,7 @@ async def search_papers(
"categories": categories,
"from": from_date,
"to": to_date,
+ "sort": sort,
"origin": _origin(client),
}
),
diff --git a/apps/python-sdk/firecrawl/v2/methods/research.py b/apps/python-sdk/firecrawl/v2/methods/research.py
index f44eb012b..164b191a0 100644
--- a/apps/python-sdk/firecrawl/v2/methods/research.py
+++ b/apps/python-sdk/firecrawl/v2/methods/research.py
@@ -27,7 +27,7 @@ covering physics, mathematics and computer science.
``articleRank``, ``seedOverlap``, ``poolSize`` and so on.
"""
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Literal, Optional
from urllib.parse import quote
import warnings
@@ -81,6 +81,7 @@ def search_papers(
categories: Optional[List[str]] = None,
from_date: Optional[str] = None,
to_date: Optional[str] = None,
+ sort: Optional[Literal["relevance", "date_desc"]] = None,
) -> Dict[str, Any]:
return _get(
client,
@@ -94,6 +95,7 @@ def search_papers(
"categories": categories,
"from": from_date,
"to": to_date,
+ "sort": sort,
"origin": _origin(client),
}
),
diff --git a/apps/python-sdk/firecrawl/v2/methods/research_docs.py b/apps/python-sdk/firecrawl/v2/methods/research_docs.py
index ca2c65b3c..4596829f7 100644
--- a/apps/python-sdk/firecrawl/v2/methods/research_docs.py
+++ b/apps/python-sdk/firecrawl/v2/methods/research_docs.py
@@ -63,7 +63,7 @@ GITHUB_SEARCH_DEPRECATION_MSG = (
_SEARCH_PAPERS_TEMPLATE = """
-Search the research paper index by abstract relevance.
+Search the research paper index.
Queries ~43M paper abstracts: PubMed, bioRxiv and medRxiv (about 90% of the
corpus β€” biomedical and life sciences) plus arXiv (physics, mathematics,
@@ -84,6 +84,10 @@ Args:
``categories`` argument of ``search()``.
from_date: Inclusive lower bound on publication date (``YYYY-MM-DD``).
to_date: Inclusive upper bound on publication date (``YYYY-MM-DD``).
+ sort: ``relevance`` (default) or ``date_desc``, which returns the newest
+ of the most relevant matches, newest first by created date. It does
+ not list every paper in a date range; add ``from_date`` (and
+ ``to_date``) for that.
Returns:
Raw API ``dict`` with ``success`` and ``results``. Keys are camelCase
@@ -211,7 +215,7 @@ AIO_SEARCH_GITHUB_DOC = _SEARCH_GITHUB_TEMPLATE.replace(_CLIENT_ARG, _ASYNC_CLIE
# ---------------------------------------------------------------------------
_CLIENT_SEARCH_PAPERS_TEMPLATE = """
-Search the research paper index by abstract relevance.
+Search the research paper index.
Queries ~43M paper abstracts: PubMed, bioRxiv and medRxiv (about 90% of
the corpus β€” biomedical and life sciences) plus arXiv (physics,
@@ -225,6 +229,10 @@ searches the paper index itself and returns ranked paper records.
Args:
query: Natural-language query, e.g. ``"CRISPR base editing
off-target effects in primary human T cells"``.
+ sort: ``relevance`` (default) or ``date_desc``, which returns the newest
+ of the most relevant matches, newest first by created date. It does
+ not list every paper in a date range; add ``from_date`` (and
+ ``to_date``) for that.
**kwargs: ``k``, ``authors``, ``categories``, ``from_date``,
``to_date``.
diff --git a/apps/rust-sdk/CHANGELOG.md b/apps/rust-sdk/CHANGELOG.md
index 33ebf681f..ac93fc0d0 100644
--- a/apps/rust-sdk/CHANGELOG.md
+++ b/apps/rust-sdk/CHANGELOG.md
@@ -1,5 +1,13 @@
## CHANGELOG
+## [2.21.10] - 2026-11-04
+
+### Added
+
+- `SearchPapersOptions::sort` accepts `relevance` or `date_desc`.
+- `PaperResult` includes optional `created_date` and `update_date` strings
+ in `YYYY-MM-DD` format for search and related-paper results.
+
## [2.21.9] - 2026-11-04
### Changed
diff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lock
index fd284ab34..2391e8323 100644
--- a/apps/rust-sdk/Cargo.lock
+++ b/apps/rust-sdk/Cargo.lock
@@ -258,7 +258,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
[[package]]
name = "firecrawl"
-version = "2.21.9"
+version = "2.21.10"
dependencies = [
"mockito",
"reqwest",
diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.toml
index 873491fb0..5e1fc5048 100644
--- a/apps/rust-sdk/Cargo.toml
+++ b/apps/rust-sdk/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "firecrawl"
-version = "2.21.9"
+version = "2.21.10"
edition = "2021"
license = "MIT"
homepage = "https://www.firecrawl.dev/"
diff --git a/apps/rust-sdk/src/research.rs b/apps/rust-sdk/src/research.rs
index f0cb6be0b..02cc51966 100644
--- a/apps/rust-sdk/src/research.rs
+++ b/apps/rust-sdk/src/research.rs
@@ -20,6 +20,8 @@ pub struct PaperResult {
pub score: Option<f64>,
pub year: Option<i32>,
pub authors: Option<Vec<String>>,
+ pub created_date: Option<String>,
+ pub update_date: Option<String>,
pub venue: Option<String>,
pub url: Option<String>,
pub signals: Option<HashMap<String, Value>>,
@@ -112,6 +114,10 @@ pub struct SearchPapersOptions {
pub categories: Option<Vec<String>>,
pub from: Option<String>,
pub to: Option<String>,
+ /// `relevance` (default) or `date_desc`, which returns the newest of the most
+ /// relevant matches, newest first by created date. It does not list every
+ /// paper in a date range; add `from` (and `to`) for that.
+ pub sort: Option<String>,
}
#[derive(Debug, Default, Clone)]
@@ -268,6 +274,9 @@ impl Client {
if let Some(to) = options.to {
push_query(&mut query, "to", to);
}
+ if let Some(sort) = options.sort {
+ push_query(&mut query, "sort", sort);
+ }
}
let response = self