firecrawl 4.2.0__tar.gz → 4.3.1__tar.gz

{firecrawl-4.2.0 → firecrawl-4.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firecrawl
-Version: 4.2.0
+Version: 4.3.1
 Summary: Python SDK for Firecrawl API
 Home-page: https://github.com/firecrawl/firecrawl
 Author: Mendable.ai

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/__init__.py

@@ -17,7 +17,7 @@ from .v1 import (
     V1ChangeTrackingOptions,
 )
 
-__version__ = "4.2.0"
+__version__ = "4.3.1"
 
 # Define the logger for the Firecrawl project
 logger: logging.Logger = logging.getLogger("firecrawl")

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/__tests__/e2e/v2/aio/test_aio_usage.py

@@ -33,3 +33,10 @@ async def test_async_get_token_usage():
     tokens = await client.get_token_usage()
     assert hasattr(tokens, "remaining_tokens")
 
+
+@pytest.mark.asyncio
+async def test_async_get_queue_status():
+    client = AsyncFirecrawl(api_key=os.getenv("API_KEY"), api_url=os.getenv("API_URL"))
+    status = await client.get_queue_status()
+    assert hasattr(status, "jobs_in_queue")
+

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/client.py

@@ -56,23 +56,34 @@ class V2Proxy:
         self._client = client_instance
 
         if client_instance:
+            self.scrape = client_instance.scrape
             self.search = client_instance.search
             self.crawl = client_instance.crawl
+            self.start_crawl = client_instance.start_crawl
             self.get_crawl_status = client_instance.get_crawl_status
             self.cancel_crawl = client_instance.cancel_crawl
-            self.start_crawl = client_instance.start_crawl
+            self.get_crawl_errors = client_instance.get_crawl_errors
+            self.get_active_crawls = client_instance.get_active_crawls
+            self.active_crawls = client_instance.active_crawls
             self.crawl_params_preview = client_instance.crawl_params_preview
+
             self.extract = client_instance.extract
+            self.start_extract = client_instance.start_extract
+            self.get_extract_status = client_instance.get_extract_status
+
             self.start_batch_scrape = client_instance.start_batch_scrape
             self.get_batch_scrape_status = client_instance.get_batch_scrape_status
             self.cancel_batch_scrape = client_instance.cancel_batch_scrape
             self.batch_scrape = client_instance.batch_scrape
             self.get_batch_scrape_errors = client_instance.get_batch_scrape_errors
-            self.get_extract_status = client_instance.get_extract_status
+
             self.map = client_instance.map
             self.get_concurrency = client_instance.get_concurrency
             self.get_credit_usage = client_instance.get_credit_usage
             self.get_token_usage = client_instance.get_token_usage
+            self.get_queue_status = client_instance.get_queue_status
+
+            self.watcher = client_instance.watcher
     
     def __getattr__(self, name):
         """Forward attribute access to the underlying client."""
@@ -99,9 +110,9 @@ class AsyncV1Proxy:
 
 class AsyncV2Proxy:
     """Proxy class that forwards method calls to the appropriate version client."""
-    _client: Optional[Any] = None
+    _client: Optional[AsyncFirecrawlClient] = None
 
-    def __init__(self, client_instance: Optional[Any] = None):
+    def __init__(self, client_instance: Optional[AsyncFirecrawlClient] = None):
         self._client = client_instance
 
         if client_instance:
@@ -132,6 +143,8 @@ class AsyncV2Proxy:
             self.get_concurrency = client_instance.get_concurrency
             self.get_credit_usage = client_instance.get_credit_usage
             self.get_token_usage = client_instance.get_token_usage
+            self.get_queue_status = client_instance.get_queue_status
+
             self.watcher = client_instance.watcher
 
     def __getattr__(self, name):
@@ -193,7 +206,8 @@ class Firecrawl:
         self.get_concurrency = self._v2_client.get_concurrency
         self.get_credit_usage = self._v2_client.get_credit_usage
         self.get_token_usage = self._v2_client.get_token_usage
-
+        self.get_queue_status = self._v2_client.get_queue_status
+        
         self.watcher = self._v2_client.watcher
         
 class AsyncFirecrawl:
@@ -238,6 +252,7 @@ class AsyncFirecrawl:
         self.get_concurrency = self._v2_client.get_concurrency
         self.get_credit_usage = self._v2_client.get_credit_usage
         self.get_token_usage = self._v2_client.get_token_usage
+        self.get_queue_status = self._v2_client.get_queue_status
 
         self.watcher = self._v2_client.watcher
 

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/types.py

@@ -65,6 +65,9 @@ from .v2.types import (
     ExecuteJavascriptAction,
     PDFAction,
     
+    # Usage types
+    QueueStatusResponse,
+
     # Location and format types
     Location,
     
@@ -142,6 +145,9 @@ __all__ = [
     'ScrapeAction',
     'ExecuteJavascriptAction',
     'PDFAction',
+
+    # Usage types
+    'QueueStatusResponse',
     
     # Location and format types
     'Location',

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/v1/client.py

@@ -358,6 +358,46 @@ class V1SearchResponse(pydantic.BaseModel):
     warning: Optional[str] = None
     error: Optional[str] = None
 
+class V1CreditUsageData(pydantic.BaseModel):
+    remaining_credits: int
+    plan_credits: Optional[int] = None
+    billing_period_start: Optional[str] = None
+    billing_period_end: Optional[str] = None
+
+class V1CreditUsageResponse(pydantic.BaseModel):
+    success: bool
+    data: V1CreditUsageData
+
+class V1TokenUsageData(pydantic.BaseModel):
+    remaining_tokens: int
+    plan_tokens: Optional[int] = None
+    billing_period_start: Optional[str] = None
+    billing_period_end: Optional[str] = None
+
+class V1TokenUsageResponse(pydantic.BaseModel):
+    success: bool
+    data: V1TokenUsageData
+
+class V1CreditUsageHistoricalPeriod(pydantic.BaseModel):
+    startDate: Optional[str] = None
+    endDate: Optional[str] = None
+    apiKey: Optional[str] = None
+    creditsUsed: int
+
+class V1CreditUsageHistoricalResponse(pydantic.BaseModel):
+    success: bool
+    periods: List[V1CreditUsageHistoricalPeriod]
+
+class V1TokenUsageHistoricalPeriod(pydantic.BaseModel):
+    startDate: Optional[str] = None
+    endDate: Optional[str] = None
+    apiKey: Optional[str] = None
+    tokensUsed: int
+
+class V1TokenUsageHistoricalResponse(pydantic.BaseModel):
+    success: bool
+    periods: List[V1TokenUsageHistoricalPeriod]
+
 class V1GenerateLLMsTextParams(pydantic.BaseModel):
     """
     Parameters for the LLMs.txt generation operation.
@@ -722,6 +762,90 @@ class V1FirecrawlApp:
         else:
             self._handle_error(response, 'search')
 
+    def get_credit_usage(self) -> V1CreditUsageResponse:
+        """Get current credit usage and billing period (v1)."""
+        _headers = self._prepare_headers()
+        response = self._get_request(
+            f"{self.api_url}/v1/team/credit-usage",
+            _headers
+        )
+
+        if response.status_code == 200:
+            try:
+                response_json = response.json()
+                if response_json.get('success') and 'data' in response_json:
+                    return V1CreditUsageResponse(**response_json)
+                elif "error" in response_json:
+                    raise Exception(f"Failed to get credit usage. Error: {response_json['error']}")
+                else:
+                    raise Exception(f"Failed to get credit usage. Error: {response_json}")
+            except ValueError:
+                raise Exception('Failed to parse Firecrawl response as JSON.')
+        else:
+            self._handle_error(response, 'get credit usage')
+
+    def get_token_usage(self) -> V1TokenUsageResponse:
+        """Get current token usage and billing period (v1)."""
+        _headers = self._prepare_headers()
+        response = self._get_request(
+            f"{self.api_url}/v1/team/token-usage",
+            _headers
+        )
+
+        if response.status_code == 200:
+            try:
+                response_json = response.json()
+                if response_json.get('success') and 'data' in response_json:
+                    return V1TokenUsageResponse(**response_json)
+                elif "error" in response_json:
+                    raise Exception(f"Failed to get token usage. Error: {response_json['error']}")
+                else:
+                    raise Exception(f"Failed to get token usage. Error: {response_json}")
+            except ValueError:
+                raise Exception('Failed to parse Firecrawl response as JSON.')
+        else:
+            self._handle_error(response, 'get token usage')
+
+    def get_credit_usage_historical(self, by_api_key: bool = False) -> V1CreditUsageHistoricalResponse:
+        """Get historical credit usage (v1)."""
+        _headers = self._prepare_headers()
+        url = f"{self.api_url}/v1/team/credit-usage/historical" + ("?byApiKey=true" if by_api_key else "")
+        response = self._get_request(url, _headers)
+
+        if response.status_code == 200:
+            try:
+                response_json = response.json()
+                if response_json.get('success') and 'periods' in response_json:
+                    return V1CreditUsageHistoricalResponse(**response_json)
+                elif "error" in response_json:
+                    raise Exception(f"Failed to get historical credit usage. Error: {response_json['error']}")
+                else:
+                    raise Exception(f"Failed to get historical credit usage. Error: {response_json}")
+            except ValueError:
+                raise Exception('Failed to parse Firecrawl response as JSON.')
+        else:
+            self._handle_error(response, 'get credit usage historical')
+
+    def get_token_usage_historical(self, by_api_key: bool = False) -> V1TokenUsageHistoricalResponse:
+        """Get historical token usage (v1)."""
+        _headers = self._prepare_headers()
+        url = f"{self.api_url}/v1/team/token-usage/historical" + ("?byApiKey=true" if by_api_key else "")
+        response = self._get_request(url, _headers)
+
+        if response.status_code == 200:
+            try:
+                response_json = response.json()
+                if response_json.get('success') and 'periods' in response_json:
+                    return V1TokenUsageHistoricalResponse(**response_json)
+                elif "error" in response_json:
+                    raise Exception(f"Failed to get historical token usage. Error: {response_json['error']}")
+                else:
+                    raise Exception(f"Failed to get historical token usage. Error: {response_json}")
+            except ValueError:
+                raise Exception('Failed to parse Firecrawl response as JSON.')
+        else:
+            self._handle_error(response, 'get token usage historical')
+
     def crawl_url(
         self,
         url: str,
@@ -2913,6 +3037,24 @@ class AsyncV1FirecrawlApp(V1FirecrawlApp):
         """
         return self._get_error_message(status_code, action, error_message, error_details)
 
+    async def get_credit_usage(self) -> V1CreditUsageResponse:
+        """Get current credit usage and billing period (v1, async)."""
+        headers = self._prepare_headers()
+        resp = await self._async_get_request(
+            f"{self.api_url}/v1/team/credit-usage",
+            headers
+        )
+        return V1CreditUsageResponse(**resp)
+
+    async def get_token_usage(self) -> V1TokenUsageResponse:
+        """Get current token usage and billing period (v1, async)."""
+        headers = self._prepare_headers()
+        resp = await self._async_get_request(
+            f"{self.api_url}/v1/team/token-usage",
+            headers
+        )
+        return V1TokenUsageResponse(**resp)
+
     async def crawl_url_and_watch(
             self,
             url: str,

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/v2/client.py

@@ -727,6 +727,14 @@ class FirecrawlClient:
         """Get recent token usage metrics (v2)."""
         return usage_methods.get_token_usage(self.http_client)
 
+    def get_credit_usage_historical(self, by_api_key: bool = False):
+        """Get historical credit usage (v2)."""
+        return usage_methods.get_credit_usage_historical(self.http_client, by_api_key)
+
+    def get_token_usage_historical(self, by_api_key: bool = False):
+        """Get historical token usage (v2)."""
+        return usage_methods.get_token_usage_historical(self.http_client, by_api_key)
+
     def get_queue_status(self):
         """Get metrics about the team's scrape queue."""
         return usage_methods.get_queue_status(self.http_client)

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/v2/client_async.py

@@ -253,6 +253,18 @@ class AsyncFirecrawlClient:
     async def get_token_usage(self):
         from .methods.aio import usage as async_usage  # type: ignore[attr-defined]
         return await async_usage.get_token_usage(self.async_http_client)
+    
+    async def get_credit_usage_historical(self, by_api_key: bool = False):
+        from .methods.aio import usage as async_usage  # type: ignore[attr-defined]
+        return await async_usage.get_credit_usage_historical(self.async_http_client, by_api_key)
+    
+    async def get_token_usage_historical(self, by_api_key: bool = False):
+        from .methods.aio import usage as async_usage  # type: ignore[attr-defined]
+        return await async_usage.get_token_usage_historical(self.async_http_client, by_api_key)
+
+    async def get_queue_status(self):
+        from .methods.aio import usage as async_usage  # type: ignore[attr-defined]
+        return await async_usage.get_queue_status(self.async_http_client)
 
     # Watcher (sync object usable from async contexts)
     def watcher(

firecrawl-4.3.1/firecrawl/v2/methods/aio/usage.py

@@ -0,0 +1,89 @@
+from ...utils.http_client_async import AsyncHttpClient
+from ...utils.error_handler import handle_response_error
+from ...types import ConcurrencyCheck, CreditUsage, TokenUsage, CreditUsageHistoricalResponse, TokenUsageHistoricalResponse, QueueStatusResponse
+
+
+async def get_concurrency(client: AsyncHttpClient) -> ConcurrencyCheck:
+    resp = await client.get("/v2/concurrency-check")
+    if resp.status_code >= 400:
+        handle_response_error(resp, "get concurrency")
+    body = resp.json()
+    if not body.get("success"):
+        raise Exception(body.get("error", "Unknown error"))
+    data = body.get("data", body)
+    return ConcurrencyCheck(
+        concurrency=data.get("concurrency"),
+        max_concurrency=data.get("maxConcurrency", data.get("max_concurrency")),
+    )
+
+
+async def get_credit_usage(client: AsyncHttpClient) -> CreditUsage:
+    resp = await client.get("/v2/team/credit-usage")
+    if resp.status_code >= 400:
+        handle_response_error(resp, "get credit usage")
+    body = resp.json()
+    if not body.get("success"):
+        raise Exception(body.get("error", "Unknown error"))
+    data = body.get("data", body)
+    return CreditUsage(
+        remaining_credits=data.get("remainingCredits", data.get("remaining_credits", 0)),
+        plan_credits=data.get("planCredits", data.get("plan_credits")),
+        billing_period_start=data.get("billingPeriodStart", data.get("billing_period_start")),
+        billing_period_end=data.get("billingPeriodEnd", data.get("billing_period_end")),
+    )
+
+
+async def get_token_usage(client: AsyncHttpClient) -> TokenUsage:
+    resp = await client.get("/v2/team/token-usage")
+    if resp.status_code >= 400:
+        handle_response_error(resp, "get token usage")
+    body = resp.json()
+    if not body.get("success"):
+        raise Exception(body.get("error", "Unknown error"))
+    data = body.get("data", body)
+    return TokenUsage(
+        remaining_tokens=data.get("remainingTokens", data.get("remaining_tokens", 0)),
+        plan_tokens=data.get("planTokens", data.get("plan_tokens")),
+        billing_period_start=data.get("billingPeriodStart", data.get("billing_period_start")),
+        billing_period_end=data.get("billingPeriodEnd", data.get("billing_period_end")),
+    )
+
+
+async def get_queue_status(client: AsyncHttpClient) -> QueueStatusResponse:
+    resp = await client.get("/v2/team/queue-status")
+    if resp.status_code >= 400:
+        handle_response_error(resp, "get queue status")
+    body = resp.json()
+    if not body.get("success"):
+        raise Exception(body.get("error", "Unknown error"))
+    data = body.get("data", body)
+    return QueueStatusResponse(
+        jobs_in_queue=data.get("jobsInQueue", 0),
+        active_jobs_in_queue=data.get("activeJobsInQueue", 0),
+        waiting_jobs_in_queue=data.get("waitingJobsInQueue", 0),
+        max_concurrency=data.get("maxConcurrency", 0),
+        most_recent_success=data.get("mostRecentSuccess", None),
+    )
+
+
+async def get_credit_usage_historical(client: AsyncHttpClient, by_api_key: bool = False) -> CreditUsageHistoricalResponse:
+    query = "?byApiKey=true" if by_api_key else ""
+    resp = await client.get(f"/v2/team/credit-usage/historical{query}")
+    if resp.status_code >= 400:
+        handle_response_error(resp, "get credit usage historical")
+    body = resp.json()
+    if not body.get("success"):
+        raise Exception(body.get("error", "Unknown error"))
+    return CreditUsageHistoricalResponse(**body)
+
+
+async def get_token_usage_historical(client: AsyncHttpClient, by_api_key: bool = False) -> TokenUsageHistoricalResponse:
+    query = "?byApiKey=true" if by_api_key else ""
+    resp = await client.get(f"/v2/team/token-usage/historical{query}")
+    if resp.status_code >= 400:
+        handle_response_error(resp, "get token usage historical")
+    body = resp.json()
+    if not body.get("success"):
+        raise Exception(body.get("error", "Unknown error"))
+    return TokenUsageHistoricalResponse(**body)
+

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/v2/methods/usage.py

@@ -1,5 +1,5 @@
 from ..utils import HttpClient, handle_response_error
-from ..types import ConcurrencyCheck, CreditUsage, QueueStatusResponse, TokenUsage
+from ..types import ConcurrencyCheck, CreditUsage, QueueStatusResponse, TokenUsage, CreditUsageHistoricalResponse, TokenUsageHistoricalResponse
 
 
 def get_concurrency(client: HttpClient) -> ConcurrencyCheck:
@@ -24,7 +24,12 @@ def get_credit_usage(client: HttpClient) -> CreditUsage:
     if not body.get("success"):
         raise Exception(body.get("error", "Unknown error"))
     data = body.get("data", body)
-    return CreditUsage(remaining_credits=data.get("remainingCredits", data.get("remaining_credits", 0)))
+    return CreditUsage(
+        remaining_credits=data.get("remainingCredits", data.get("remaining_credits", 0)),
+        plan_credits=data.get("planCredits", data.get("plan_credits")),
+        billing_period_start=data.get("billingPeriodStart", data.get("billing_period_start")),
+        billing_period_end=data.get("billingPeriodEnd", data.get("billing_period_end")),
+    )
 
 
 def get_token_usage(client: HttpClient) -> TokenUsage:
@@ -36,7 +41,10 @@ def get_token_usage(client: HttpClient) -> TokenUsage:
         raise Exception(body.get("error", "Unknown error"))
     data = body.get("data", body)
     return TokenUsage(
-        remaining_tokens=data.get("remainingTokens", 0)
+        remaining_tokens=data.get("remainingTokens", data.get("remaining_tokens", 0)),
+        plan_tokens=data.get("planTokens", data.get("plan_tokens")),
+        billing_period_start=data.get("billingPeriodStart", data.get("billing_period_start")),
+        billing_period_end=data.get("billingPeriodEnd", data.get("billing_period_end")),
     )
 
 def get_queue_status(client: HttpClient) -> QueueStatusResponse:
@@ -54,3 +62,23 @@ def get_queue_status(client: HttpClient) -> QueueStatusResponse:
         max_concurrency=data.get("maxConcurrency", 0),
         most_recent_success=data.get("mostRecentSuccess", None),
     )
+
+
+def get_credit_usage_historical(client: HttpClient, by_api_key: bool = False) -> CreditUsageHistoricalResponse:
+    resp = client.get(f"/v2/team/credit-usage/historical{'?byApiKey=true' if by_api_key else ''}")
+    if not resp.ok:
+        handle_response_error(resp, "get credit usage historical")
+    body = resp.json()
+    if not body.get("success"):
+        raise Exception(body.get("error", "Unknown error"))
+    return CreditUsageHistoricalResponse(**body)
+
+
+def get_token_usage_historical(client: HttpClient, by_api_key: bool = False) -> TokenUsageHistoricalResponse:
+    resp = client.get(f"/v2/team/token-usage/historical{'?byApiKey=true' if by_api_key else ''}")
+    if not resp.ok:
+        handle_response_error(resp, "get token usage historical")
+    body = resp.json()
+    if not body.get("success"):
+        raise Exception(body.get("error", "Unknown error"))
+    return TokenUsageHistoricalResponse(**body)

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl/v2/types.py

@@ -480,10 +480,16 @@ class ConcurrencyCheck(BaseModel):
 class CreditUsage(BaseModel):
     """Remaining credits for the team/API key."""
     remaining_credits: int
+    plan_credits: Optional[int] = None
+    billing_period_start: Optional[str] = None
+    billing_period_end: Optional[str] = None
 
 class TokenUsage(BaseModel):
     """Recent token usage metrics (if available)."""
     remaining_tokens: int
+    plan_tokens: Optional[int] = None
+    billing_period_start: Optional[str] = None
+    billing_period_end: Optional[str] = None
 
 class QueueStatusResponse(BaseModel):
     """Metrics about the team's scrape queue."""
@@ -493,6 +499,26 @@ class QueueStatusResponse(BaseModel):
     max_concurrency: int
     most_recent_success: Optional[datetime] = None
 
+class CreditUsageHistoricalPeriod(BaseModel):
+    startDate: Optional[str] = None
+    endDate: Optional[str] = None
+    apiKey: Optional[str] = None
+    creditsUsed: int
+
+class CreditUsageHistoricalResponse(BaseModel):
+    success: bool
+    periods: List[CreditUsageHistoricalPeriod]
+
+class TokenUsageHistoricalPeriod(BaseModel):
+    startDate: Optional[str] = None
+    endDate: Optional[str] = None
+    apiKey: Optional[str] = None
+    tokensUsed: int
+
+class TokenUsageHistoricalResponse(BaseModel):
+    success: bool
+    periods: List[TokenUsageHistoricalPeriod]
+
 # Action types
 class WaitAction(BaseModel):
     """Wait action to perform during scraping."""

{firecrawl-4.2.0 → firecrawl-4.3.1}/firecrawl.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firecrawl
-Version: 4.2.0
+Version: 4.3.1
 Summary: Python SDK for Firecrawl API
 Home-page: https://github.com/firecrawl/firecrawl
 Author: Mendable.ai

firecrawl-4.2.0/firecrawl/v2/methods/aio/usage.py

@@ -1,42 +0,0 @@
-from ...utils.http_client_async import AsyncHttpClient
-from ...utils.error_handler import handle_response_error
-from ...types import ConcurrencyCheck, CreditUsage, TokenUsage
-
-
-async def get_concurrency(client: AsyncHttpClient) -> ConcurrencyCheck:
-    resp = await client.get("/v2/concurrency-check")
-    if resp.status_code >= 400:
-        handle_response_error(resp, "get concurrency")
-    body = resp.json()
-    if not body.get("success"):
-        raise Exception(body.get("error", "Unknown error"))
-    data = body.get("data", body)
-    return ConcurrencyCheck(
-        concurrency=data.get("concurrency"),
-        max_concurrency=data.get("maxConcurrency", data.get("max_concurrency")),
-    )
-
-
-async def get_credit_usage(client: AsyncHttpClient) -> CreditUsage:
-    resp = await client.get("/v2/team/credit-usage")
-    if resp.status_code >= 400:
-        handle_response_error(resp, "get credit usage")
-    body = resp.json()
-    if not body.get("success"):
-        raise Exception(body.get("error", "Unknown error"))
-    data = body.get("data", body)
-    return CreditUsage(remaining_credits=data.get("remainingCredits", data.get("remaining_credits", 0)))
-
-
-async def get_token_usage(client: AsyncHttpClient) -> TokenUsage:
-    resp = await client.get("/v2/team/token-usage")
-    if resp.status_code >= 400:
-        handle_response_error(resp, "get token usage")
-    body = resp.json()
-    if not body.get("success"):
-        raise Exception(body.get("error", "Unknown error"))
-    data = body.get("data", body)
-    return TokenUsage(
-        remaining_tokens=data.get("remainingTokens", 0)
-    )
-