firecrawl 4.1.1__py3-none-any.whl → 4.3.0__py3-none-any.whl

firecrawl/__init__.py

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

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/v2/client.py

@@ -727,6 +727,18 @@ 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)
+
     def watcher(
         self,
         job_id: str,

firecrawl/v2/methods/aio/usage.py

@@ -1,6 +1,6 @@
 from ...utils.http_client_async import AsyncHttpClient
 from ...utils.error_handler import handle_response_error
-from ...types import ConcurrencyCheck, CreditUsage, TokenUsage
+from ...types import ConcurrencyCheck, CreditUsage, TokenUsage, CreditUsageHistoricalResponse, TokenUsageHistoricalResponse
 
 
 async def get_concurrency(client: AsyncHttpClient) -> ConcurrencyCheck:
@@ -25,7 +25,12 @@ async def get_credit_usage(client: AsyncHttpClient) -> 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")),
+    )
 
 
 async def get_token_usage(client: AsyncHttpClient) -> TokenUsage:
@@ -37,6 +42,31 @@ async def get_token_usage(client: AsyncHttpClient) -> 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")),
     )
 
+
+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/v2/methods/usage.py

@@ -1,5 +1,5 @@
 from ..utils import HttpClient, handle_response_error
-from ..types import ConcurrencyCheck, CreditUsage, 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,6 +41,44 @@ 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:
+    resp = client.get("/v2/team/queue-status")
+    if not resp.ok:
+        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),
     )
 
+
+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/v2/types.py

@@ -480,10 +480,44 @@ 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."""
+    jobs_in_queue: int
+    active_jobs_in_queue: int
+    waiting_jobs_in_queue: int
+    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):

{firecrawl-4.1.1.dist-info → firecrawl-4.3.0.dist-info}/METADATA

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

{firecrawl-4.1.1.dist-info → firecrawl-4.3.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-firecrawl/__init__.py,sha256=PTxLZcB2UvYQVIzsA-XrGsaQamCdRO4yU96eKWMEwIs,2192
+firecrawl/__init__.py,sha256=Lrk_X9oaNHYEYdzuPTdwX7kjhfoZbVCsyEd4wd9Qi5Q,2192
 firecrawl/client.py,sha256=tp3mUo_3aGPuZ53kpU4bhM-5EtwD_IUWrJ7wm0GMuCc,11159
 firecrawl/firecrawl.backup.py,sha256=v1FEN3jR4g5Aupg4xp6SLkuFvYMQuUKND2YELbYjE6c,200430
 firecrawl/types.py,sha256=W9N2pqQuevEIIjYHN9rbDf31E-nwdCECqIn11Foz2T8,2836
@@ -42,11 +42,11 @@ firecrawl/__tests__/unit/v2/methods/aio/test_ensure_async.py,sha256=pUwuWhRbVUTb
 firecrawl/__tests__/unit/v2/utils/test_validation.py,sha256=E4n4jpBhH_W7E0ikI5r8KMAKiOhbfGD3i_B8-dv3PlI,10803
 firecrawl/__tests__/unit/v2/watcher/test_ws_watcher.py,sha256=87w47n0iOihtu4jTR4-4rw1-xVKWmLg2BOBGxjQPnUk,9517
 firecrawl/v1/__init__.py,sha256=aP1oisPeZVGGZynvENc07JySMOZfv_4zAlxQ0ecMJXA,481
-firecrawl/v1/client.py,sha256=sydurfEFTsXyowyaGryA1lkPxN_r9Nf6iQpM43OwJyM,201672
+firecrawl/v1/client.py,sha256=33o_sPOyPsRfM1j2PUiKTkvbnPCkmL7-Ou54D1sx-rE,207710
 firecrawl/v2/__init__.py,sha256=Jc6a8tBjYG5OPkjDM5pl-notyys-7DEj7PLEfepv3fc,137
-firecrawl/v2/client.py,sha256=AMAHQ8Uz9bsEIy2vmIDNNUIT0FOivhLyj6lesEr1Rbg,31260
+firecrawl/v2/client.py,sha256=aEISMnyKKzh5jcrLdpkC3WCZ7cMWj5vo1Gk7ljc9gwk,31821
 firecrawl/v2/client_async.py,sha256=XyzojIJlWatBGlAMish22H-XHkkH9zHsD6MGtAdtFg8,10487
-firecrawl/v2/types.py,sha256=aD_q4wVUksZKyKifYn1lbNgZeSPAZjAIxa1lPwEKckU,23266
+firecrawl/v2/types.py,sha256=itKhycxDQ9a3wltK28qFLxLVVvsvb5APoS1kOiiS8ac,24341
 firecrawl/v2/watcher.py,sha256=FOU71tqSKxgeuGycu4ye0SLc2dw7clIcoQjPsi-4Csc,14229
 firecrawl/v2/watcher_async.py,sha256=AVjW2mgABniolSsauK4u0FW8ya6WzRUdyEg2R-8vGCw,10278
 firecrawl/v2/methods/batch.py,sha256=jFSIPtvulUrPz3Y3zT1gDNwYEf8Botpfh4GOeYsVYRI,14852
@@ -55,7 +55,7 @@ firecrawl/v2/methods/extract.py,sha256=-Jr4BtraU3b7hd3JIY73V-S69rUclxyXyUpoQb6DC
 firecrawl/v2/methods/map.py,sha256=4SADb0-lkbdOWDmO6k8_TzK0yRti5xsN40N45nUl9uA,2592
 firecrawl/v2/methods/scrape.py,sha256=CSHBwC-P91UfrW3zHirjNAs2h899FKcWvd1DY_4fJdo,1921
 firecrawl/v2/methods/search.py,sha256=6BKiQ1aKJjWBKm9BBtKxFKGD74kCKBeMIp_OgjcDFAw,7673
-firecrawl/v2/methods/usage.py,sha256=OJlkxwaB-AAtgO3WLr9QiqBRmjdh6GVhroCgleegupQ,1460
+firecrawl/v2/methods/usage.py,sha256=NqkmFd-ziw8ijbZxwaxjxZHl85u0LTe_TYqr_NGWFwE,3693
 firecrawl/v2/methods/aio/__init__.py,sha256=RocMJnGwnLIvGu3G8ZvY8INkipC7WHZiu2bE31eSyJs,35
 firecrawl/v2/methods/aio/batch.py,sha256=4Uj05ffpMhQA2J_mkvHYYogdXb0IgbKGbomO43b4m94,6741
 firecrawl/v2/methods/aio/crawl.py,sha256=j2Tb2AcGsT6bCiUbB2yjrfvGZqkinUt0tU-SzWmB7Jw,11551
@@ -63,7 +63,7 @@ firecrawl/v2/methods/aio/extract.py,sha256=IfNr2ETqt4dR73JFzrEYI4kk5vpKnJOG0BmPE
 firecrawl/v2/methods/aio/map.py,sha256=EuT-5A0cQr_e5SBfEZ6pnl8u0JUwEEvSwhyT2N-QoKU,2326
 firecrawl/v2/methods/aio/scrape.py,sha256=ilA9qco8YGwCFpE0PN1XBQUyuHPQwH2QioZ-xsfxhgU,1386
 firecrawl/v2/methods/aio/search.py,sha256=_TqTFGQLlOCCLNdWcOvakTqPGD2r9AOlBg8RasOgmvw,6177
-firecrawl/v2/methods/aio/usage.py,sha256=OtBi6X-aT09MMR2dpm3vBCm9JrJZIJLCQ8jJ3L7vie4,1606
+firecrawl/v2/methods/aio/usage.py,sha256=qM5PsPuA_N1pUTnZF4Raq4VkBf_XCMSQdhOJBFFs17k,3239
 firecrawl/v2/utils/__init__.py,sha256=i1GgxySmqEXpWSBQCu3iZBPIJG7fXj0QXCDWGwerWNs,338
 firecrawl/v2/utils/error_handler.py,sha256=Iuf916dHphDY8ObNNlWy75628DFeJ0Rv8ljRp4LttLE,4199
 firecrawl/v2/utils/get_version.py,sha256=0CxW_41q2hlzIxEWOivUCaYw3GFiSIH32RPUMcIgwAY,492
@@ -71,10 +71,10 @@ firecrawl/v2/utils/http_client.py,sha256=gUrC1CvU5sj03w27Lbq-3-yH38Yi_OXiI01-piw
 firecrawl/v2/utils/http_client_async.py,sha256=iy89_bk2HS3afSRHZ8016eMCa9Fk-5MFTntcOHfbPgE,1936
 firecrawl/v2/utils/normalize.py,sha256=nlTU6QRghT1YKZzNZlIQj4STSRuSUGrS9cCErZIcY5w,3636
 firecrawl/v2/utils/validation.py,sha256=qWWiWaVcvODmVxf9rxIVy1j_dyuJCvdMMUoYhvWUEIU,15269
-firecrawl-4.1.1.dist-info/licenses/LICENSE,sha256=nPCunEDwjRGHlmjvsiDUyIWbkqqyj3Ej84ntnh0g0zA,1084
+firecrawl-4.3.0.dist-info/licenses/LICENSE,sha256=nPCunEDwjRGHlmjvsiDUyIWbkqqyj3Ej84ntnh0g0zA,1084
 tests/test_change_tracking.py,sha256=_IJ5ShLcoj2fHDBaw-nE4I4lHdmDB617ocK_XMHhXps,4177
 tests/test_timeout_conversion.py,sha256=PWlIEMASQNhu4cp1OW_ebklnE9NCiigPnEFCtI5N3w0,3996
-firecrawl-4.1.1.dist-info/METADATA,sha256=D6H49PROhKlcEYd-216G5QQ1DlXLutq6SQv876cKivg,7392
-firecrawl-4.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-firecrawl-4.1.1.dist-info/top_level.txt,sha256=8T3jOaSN5mtLghO-R3MQ8KO290gIX8hmfxQmglBPdLE,16
-firecrawl-4.1.1.dist-info/RECORD,,
+firecrawl-4.3.0.dist-info/METADATA,sha256=xWtTodBOtFYrrFuKAOC7i657fmT45ZtpRXyNWd7i7mU,7392
+firecrawl-4.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+firecrawl-4.3.0.dist-info/top_level.txt,sha256=8T3jOaSN5mtLghO-R3MQ8KO290gIX8hmfxQmglBPdLE,16
+firecrawl-4.3.0.dist-info/RECORD,,