Skip to content

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

Agent: expose incomplete results in status and threads (#4812)

Rakshith Ramprakash2e6f6aa9089c
diff --git a/apps/api/src/controllers/v2/__tests__/agent-status.test.ts b/apps/api/src/controllers/v2/__tests__/agent-status.test.ts
index 8b32257c4..f0a6979ee 100644
--- a/apps/api/src/controllers/v2/__tests__/agent-status.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/agent-status.test.ts
@@ -131,6 +131,9 @@ describe("agentStatusController", () => {
model: "spark-2",
effort: "medium",
data: { result: "ok" },
+ partial: { stale: true },
+ partialSchemaValid: false,
+ stopReason: "credit_limit_reached",
message: "Done",
threadId: "thread-123",
threadTurn: 2,
@@ -152,6 +155,69 @@ describe("agentStatusController", () => {
creditsUsed: 7,
}),
);
+ const body = (res.json as Mock).mock.calls[0][0];
+ expect(body).not.toHaveProperty("partial");
+ expect(body).not.toHaveProperty("partialSchemaValid");
+ expect(body).not.toHaveProperty("stopReason");
+ });
+
+ it("forwards a credit-limited partial without treating it as completed data", async () => {
+ (getAgentJobAccess as Mock).mockResolvedValue({
+ teamId: "team-123",
+ expiresAtMs: Date.now() + 60_000,
+ });
+ (getExtractV3AgentStatus as Mock).mockResolvedValue({
+ id: "job-123",
+ success: true,
+ status: "failed",
+ error: "Agent reached max credits",
+ data: { shouldNotAppear: true },
+ stopReason: "credit_limit_reached",
+ partial: { companies: [{ name: "Acme" }] },
+ partialSchemaValid: false,
+ model: "spark-2",
+ });
+
+ const res = buildRes();
+ await agentStatusController(baseReq, res);
+
+ expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.json).toHaveBeenCalledWith(
+ expect.objectContaining({
+ status: "failed",
+ data: undefined,
+ stopReason: "credit_limit_reached",
+ partial: { companies: [{ name: "Acme" }] },
+ partialSchemaValid: false,
+ }),
+ );
+ });
+
+ it("does not expose a live processing checkpoint", async () => {
+ (getAgentJobAccess as Mock).mockResolvedValue({
+ teamId: "team-123",
+ expiresAtMs: Date.now() + 60_000,
+ });
+ (getExtractV3AgentStatus as Mock).mockResolvedValue({
+ id: "job-123",
+ success: true,
+ status: "processing",
+ data: { companies: [{ name: "Acme" }] },
+ partial: { companies: [{ name: "Acme" }] },
+ partialSchemaValid: false,
+ stopReason: "credit_limit_reached",
+ model: "spark-2",
+ });
+
+ const res = buildRes();
+ await agentStatusController(baseReq, res);
+
+ const body = (res.json as Mock).mock.calls[0][0];
+ expect(body.status).toBe("processing");
+ expect(body.data).toBeUndefined();
+ expect(body).not.toHaveProperty("partial");
+ expect(body).not.toHaveProperty("partialSchemaValid");
+ expect(body).not.toHaveProperty("stopReason");
});
it.each([
diff --git a/apps/api/src/controllers/v2/agent-status.ts b/apps/api/src/controllers/v2/agent-status.ts
index 4c4bb7e84..b260ab77b 100644
--- a/apps/api/src/controllers/v2/agent-status.ts
+++ b/apps/api/src/controllers/v2/agent-status.ts
@@ -98,7 +98,16 @@ export async function agentStatusController(
success: true,
status: agent.status === "success" ? "completed" : agent.status,
error: agent.error,
- data: agent.data,
+ data: agent.status === "success" ? agent.data : undefined,
+ // Checkpoints are internal while a job is running; only expose a partial
+ // when the run has stopped without a completed result.
+ ...(agent.status === "failed"
+ ? {
+ partial: agent.partial,
+ partialSchemaValid: agent.partialSchemaValid,
+ stopReason: agent.stopReason,
+ }
+ : {}),
model,
effort,
threadId: thread.threadId,
diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.ts
index 280d1021b..59cee1425 100644
--- a/apps/api/src/controllers/v2/types.ts
+++ b/apps/api/src/controllers/v2/types.ts
@@ -1812,6 +1812,11 @@ export type AgentStatusResponse =
status: "processing" | "completed" | "failed";
error?: string;
data?: any;
+ /** Best-effort JSON on a failed run; `data` remains completed-only. */
+ partial?: unknown;
+ /** Only present when the caller supplied a JSON Schema. */
+ partialSchemaValid?: boolean;
+ stopReason?: "credit_limit_reached";
model?: "spark-1-pro" | "spark-1-mini" | "spark-2";
effort?: "low" | "medium" | "high";
expiresAt: string;
@@ -1846,6 +1851,9 @@ type AgentThreadRun = {
message: string | null;
// Only present when the request asked for includeData.
data?: unknown;
+ partial?: unknown;
+ partialSchemaValid?: boolean;
+ stopReason?: "credit_limit_reached";
suggestions?: AgentSuggestion[] | null;
pendingApproval?: AgentPendingApproval | null;
exchange?: AgentExchangeSummary | null;
diff --git a/apps/api/src/lib/extract-v3-status.ts b/apps/api/src/lib/extract-v3-status.ts
index edd14bb26..5effc65af 100644
--- a/apps/api/src/lib/extract-v3-status.ts
+++ b/apps/api/src/lib/extract-v3-status.ts
@@ -5,6 +5,10 @@ type ExtractV3AgentStatus = {
id: string;
status: "processing" | "success" | "failed";
data?: unknown;
+ /** Incomplete JSON from an interrupted run; never a completed `data` value. */
+ partial?: unknown;
+ partialSchemaValid?: boolean;
+ stopReason?: "credit_limit_reached";
error?: string;
model?: "spark-1-pro" | "spark-1-mini" | "spark-2";
effort?: "low" | "medium" | "high";
diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.ts
index fb0b6f8fc..b485d9e13 100644
--- a/apps/js-sdk/firecrawl/src/v2/types.ts
+++ b/apps/js-sdk/firecrawl/src/v2/types.ts
@@ -1627,6 +1627,11 @@ export interface AgentStatusResponse {
status: "processing" | "completed" | "failed";
error?: string;
data?: unknown;
+ /** Best-effort result on a failed run; never a completed `data` value. */
+ partial?: unknown;
+ /** Schema validity of `partial`, when a schema was supplied. */
+ partialSchemaValid?: boolean;
+ stopReason?: "credit_limit_reached";
/**
* Server-provided model name. Widened past the request-side union on
* purpose: new models ship without an SDK release, so pinning this to known
@@ -1672,6 +1677,9 @@ export interface AgentThreadRun {
message: string | null;
/** Only present when the request asked for includeData. */
data?: unknown;
+ partial?: unknown;
+ partialSchemaValid?: boolean;
+ stopReason?: "credit_limit_reached";
suggestions?: AgentSuggestion[] | null;
pendingApproval?: PendingApproval | null;
exchange?: AgentExchangeSummary | null;
diff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.py
index 8a2653000..f01591e24 100644
--- a/apps/python-sdk/firecrawl/v2/types.py
+++ b/apps/python-sdk/firecrawl/v2/types.py
@@ -1745,6 +1745,10 @@ class AgentResponse(BaseModel):
id: Optional[str] = None
status: Optional[Literal["processing", "completed", "failed"]] = None
data: Optional[Any] = None
+ # Best-effort result on a failed run; never a completed `data` value.
+ partial: Optional[Any] = None
+ partial_schema_valid: Optional[bool] = Field(default=None, alias="partialSchemaValid")
+ stop_reason: Optional[str] = Field(default=None, alias="stopReason")
error: Optional[str] = None
# Deliberately a plain str, not a Literal: this is server-provided and new
# models ship without an SDK release, so a narrow type turns an unknown
@@ -1838,6 +1842,9 @@ class AgentThreadRun(BaseModel):
message: Optional[str] = None
# Only present when the request asked for include_data.
data: Optional[Any] = None
+ partial: Optional[Any] = None
+ partial_schema_valid: Optional[bool] = Field(default=None, alias="partialSchemaValid")
+ stop_reason: Optional[str] = Field(default=None, alias="stopReason")
suggestions: Optional[List[AgentSuggestion]] = None
pending_approval: Optional[PendingApproval] = Field(
default=None, alias="pendingApproval"
diff --git a/apps/python-sdk/tests/test_agent_partial_types.py b/apps/python-sdk/tests/test_agent_partial_types.py
new file mode 100644
index 000000000..f288ba1ee
--- /dev/null
+++ b/apps/python-sdk/tests/test_agent_partial_types.py
@@ -0,0 +1,34 @@
+from firecrawl.v2.types import AgentResponse, AgentThreadRun
+
+
+def test_agent_status_preserves_credit_limit_partial():
+ response = AgentResponse.model_validate(
+ {
+ "success": True,
+ "status": "failed",
+ "stopReason": "credit_limit_reached",
+ "partial": {"companies": [{"name": "Acme"}]},
+ "partialSchemaValid": False,
+ }
+ )
+
+ assert response.data is None
+ assert response.stop_reason == "credit_limit_reached"
+ assert response.partial == {"companies": [{"name": "Acme"}]}
+ assert response.partial_schema_valid is False
+
+
+def test_agent_thread_run_preserves_partial_for_continuation():
+ run = AgentThreadRun.model_validate(
+ {
+ "id": "job-123",
+ "status": "credit_limit_reached",
+ "stopReason": "credit_limit_reached",
+ "partial": {"companies": [{"name": "Acme"}]},
+ "partialSchemaValid": False,
+ }
+ )
+
+ assert run.partial == {"companies": [{"name": "Acme"}]}
+ assert run.partial_schema_valid is False
+ assert run.stop_reason == "credit_limit_reached"