
    _j                        S r SSKrSSKJr  SSKJrJrJrJrJ	r	J
r
JrJr  SSKJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJrJ r J!r!J"r"J#r#J$r$J%r%J&r&J'r'J(r(J)r)J*r*J+r+J,r,J-r-J.r.J/r/J0r0J1r1J2r2J3r3J4r4J5r5J6r6  SSK7J8r8  SSK9J:r:  SS	K;J<r=  SS
K;J>r?  SSK;J@rA  SSK;JBrC  SSK;JDrE  SSK;JFrG  SSK;JBrH  SSK;JIrJ  SSK;JKrL  SSK;JMrN  SSK;JOrP  SSK;JQrR  SSKSJTrT   " S S5      rUg)zs
Main Firecrawl v2 API client.

This module provides the main client class that orchestrates all v2 functionality.
    N)Path)OptionalListDictAnyCallableUnionLiteralBinaryIO   ))ClientConfigParseOptionsScrapeOptionsDocumentSearchRequest
SearchDataSourceOptionCategoryOptionCrawlRequestCrawlResponseCrawlJobCrawlParamsRequest	PDFParserCrawlParamsDataWebhookConfigAgentWebhookConfigCrawlErrorsResponseActiveCrawlsResponse
MapOptionsMapDataFormatOption
WaitActionScreenshotActionClickActionWriteActionPressActionScrollActionScrapeActionExecuteJavascriptAction	PDFActionLocationPaginationConfigAgentOptionsMonitorMonitorCheckMonitorCheckDetailMonitorCreateRequestMonitorNotificationMonitorScheduleMonitorTargetMonitorUpdateRequest)
HttpClient)FirecrawlError)scrape)parse)crawl)batch)search)map)usage)extract)agent)browser)monitorWatcherc            >       z   \ rS rSrSr\S\S\4S j5       r     SS\	\   S\S	\	\
   S
\S\
4
S jjrSSSSSSSSSSSSSSSSSSSSSSS.S\S\	\S      S\	\\\4      S\	\\      S\	\\      S\	\   S	\	\   S\	\   S\	\   S\	\\\   \\\\4      4      S\	\\S         S\	S   S\	\   S\	\   S\	\   S\	\   S\	\   S \	\   S!\	\   S"\	\   S#\	\   S$\	\\\4      S%\	\   S\40S& jjr SSS'SSS(.S)\S*\	\   S+\	\   S,\S-   S	\	\   S.\	\   4S/ jjjrS)\4S0 jrS)\4S1 jr SSS'SSS(.S)\S*\	\   S+\	\   S,\S-   S	\	\   S.\	\   4S2 jjjrS)\4S3 jrSSSS4.S5\\\\\\4   S6\	\   S7\	\   S8\	\   S\4
S9 jjrSSSSSSSSSS:.	S;\S<\	\\       S=\	\\!      S>\	\   S?\	\   S\	\   S@\	\   S	\	\   SA\	\"   S%\	\   S\#4SB jjr$SSSSSSSCSSCSCSCSCSSSSSCSDSCSESSSSF.S\S+\	\   SG\	\\      SH\	\\      SI\	\   SJ\	\SK      SL\	\   SM\S>\	\   SN\SO\SP\SQ\SR\	\   SS\	\   ST\	\\\%4      SA\	\"   SU\SV\SW\SX\S	\	\   SY\	\
   S%\	\   S\&42SZ jjr'SSSSSSSCSSCSCSCSCSSSSSCSDSCSS[.S\S+\	\   SG\	\\      SH\	\\      SI\	\   SJ\	\SK      SL\	\   SM\S>\	\   SN\SO\SP\SQ\SR\	\   SS\	\   ST\	\\\%4      SA\	\"   SU\SV\SW\S%\	\   S\(4,S\ jjr) SSS].S)\S^\	\*   SY\	\
   S\&4S_ jjjr+SS].S`\SY\	\
   S\&4Sa jjr,Sb\S\-4Sc jr.S\/4Sd jr0S\/4Se jr1SSSSSSSSSf.S\Sg\	\   Sh\	\   SM\	\   S>\	\   SJ\	\SK      S	\	\   S%\	\   S\	\2   S\34Si jjr4SSSSj.Sk\Sl\\5\\\4   4   Sm\\\6\\\4   4      ST\	\%   Sn\	\7   So\	\   S\84Sp jjr9SSSq.S>\	\   Sr\	\   S\\8   4Ss jjr:St\S\84Su jr;SSSSSSSSv.St\Sk\	\   Sw\	\Sx      Sl\	\\5\\\4   4      ST\	\\%\\\4   4      Sn\	\\7\\\4   4      Sm\	\\\6\\\4   4         So\	\   S\84Sy jjr<St\S\4Sz jr=St\S\>4S{ jr?SSSq.St\S>\	\   Sr\	\   S\\>   4S| jjr@SSSSS}.St\S~\S>\	\   S\	\   Sw\	\S      S^\	\*   S\A4S jjrBSb\S\4S jrCS\S+\S\D4S jrE SSSSSSSSSSSS.
S\	\\      S+\	\   S\	\\\4      S\	\   SO\	\   S\	\   S\	\   SA\	S   S@\	\   S%\	\   S\	\F   4S jjjrG SSSSSSSSSSESSSS.S\	\\      S+\	\   S\	\\\4      S\	\   SO\	\   S\	\   S\	\   SA\	S   S@\	\   SX\S	\	\   S%\	\   S\	\F   4S jjjrHSSSSSSSSSSSSSSSSSSSSSSSSSSSS.S\\   S\	\S      S\	\\\4      S\	\\      S\	\\      S\	\   S	\	\   S\	\   S\	\   S\	\\\   \\\\4      4      S\	\\S         S\	S   S\	\   S\	\   S\	\   S\	\   S\	\   S \	\   S!\	\   S"\	\   S#\	\   ST\	\\\%4      S\	\   S@\	\   SS\	\   SW\	\   S%\	\   S\	\   48S jjrI SS)\S^\	\*   4S jjrJSS].S`\SY\	\
   4S jjrKS)\S\4S jrLS)\4S jrMS)\4S jrN SSSSSSSS.S\	\\      S+\S\	\   S%\	\   S\	\   S\	\   S\	\S      ST\	\\\O4      4S jjjrP SSSSESSSSSS.S\	\\      S+\S\	\   S%\	\   SX\S	\	\   S\	\   S\	\   S\	\S      ST\	\\\O4      4S jjjrQS)\4S jrRS)\S\4S jrSS rTS rUS rVSS\4S jjrWSS\4S jjrXS rYSSSSS.S\	\   S\	\   S\	\   S$\	\\\4      4S jjrZSSS.S\S*\S,\S-   S	\	\   4S jjr[S\4S jr\SS.Sw\	\S      4S jjr]SSESS.S)\S\S   SX\S	\	\   S\^4
S jjr_SSSSSSSSSSSSSSSSSSSSSSSSSSSSESS.S\\   S\	\S      S\	\\\4      S\	\\      S\	\\      S\	\   S	\	\   S\	\   S\	\   S\	\\\   \\\\4      4      S\	\\S         S\	S   S\	\   S\	\   S\	\   S\	\   S\	\   S \	\   S!\	\   S"\	\   S#\	\   ST\	\\\%4      S\	\   S@\	\   SS\	\   SW\	\   S%\	\   S\	\   SX\S\	\   4<S jjr`Srag)FirecrawlClientE   zp
Main Firecrawl v2 API client.

This client provides a clean, modular interface to all Firecrawl functionality.
urlreturnc                 (    SU R                  5       ;   $ )Nzapi.firecrawl.dev)lower)rH   s    H/home/rurouni/.local/lib/python3.13/site-packages/firecrawl/v2/client.py_is_cloud_service!FirecrawlClient._is_cloud_serviceL   s    "ciik11    Napi_keyapi_urltimeoutmax_retriesbackoff_factorc                     Uc  [         R                  " S5      nU R                  U5      (       a  U(       d  [        S5      e[	        UUUUUS9U l        [        UUUUUS9U l        g)av  
Initialize the Firecrawl client.

Args:
    api_key: Firecrawl API key (or set FIRECRAWL_API_KEY env var)
    api_url: Base URL for the Firecrawl API
    timeout: Request timeout in seconds
    max_retries: Maximum number of retries for failed requests
    backoff_factor: Exponential backoff factor for retries (e.g. 0.5 means wait 0.5s, then 1s, then 2s between retries)
NFIRECRAWL_API_KEYzlAPI key is required for the cloud API. Set FIRECRAWL_API_KEY environment variable or pass api_key parameter.)rP   rQ   rR   rS   rT   )rR   rS   rT   )osgetenvrM   
ValueErrorr   configr6   http_client)selfrP   rQ   rR   rS   rT   s         rL   __init__FirecrawlClient.__init__P   sx    $ ?ii 34G!!'**7- 
 ##)
 &#)
rO   )formatsheadersinclude_tagsexclude_tagsonly_main_contentrR   wait_formobileparsersactionslocationskip_tls_verificationremove_base64_images	fast_modeuse_mock	block_adsproxymax_agestore_in_cachelockdownprofileintegrationr_   r!   r`   ra   rb   rc   rd   re   rf   rg   )	r"   r#   r$   r%   r&   r'   r(   r)   r*   rh   r+   ri   rj   rk   rl   rm   rn   ro   rp   rq   rr   rs   c                   [        S X#XEXgXXXXUUUUUUUU4 5       5      (       a~  [        S0 [        S0 SU_SU_SU_SU_SU_SU_SU_S	U	_S
U
_SU_SU_SU_SU_SU_SU_SU_SU_SU_SU_SU_SU_SU_6R                  5        VVs0 s H  u  nnUc  M  UU_M     snnD6OSn[        R
                  " U R                  UU5      $ s  snnf )a  
Scrape a single URL and return the document.
Args:
    url: URL to scrape
    formats: List of formats to scrape
    headers: Dictionary of headers to use
    include_tags: List of tags to include
    exclude_tags: List of tags to exclude
    only_main_content: Whether to only scrape the main content
    timeout: Timeout in milliseconds
    wait_for: Wait for a specific element to be present
    mobile: Whether to use mobile mode
    parsers: List of parsers to use
    actions: List of actions to perform
    location: Location to scrape
    skip_tls_verification: Whether to skip TLS verification
    remove_base64_images: Whether to remove base64 images
    fast_mode: Whether to use fast mode
    use_mock: Whether to use mock mode
    block_ads: Whether to block ads
    proxy: Proxy to use
    max_age: Maximum age of the cache
    store_in_cache: Whether to store the result in the cache
    lockdown: Serve only previously cached results; never make outbound requests. Returns 404 SCRAPE_LOCKDOWN_CACHE_MISS on cache miss.
    profile: Browser profile for persistent state (e.g. {"name": "my-profile", "saveChanges": True})
Returns:
    Document
c              3   (   #    U  H  oS Lv   M
     g 7fN .0vs     rL   	<genexpr>)FirecrawlClient.scrape.<locals>.<genexpr>   s       o  )n1$  )n   r_   r`   ra   rb   rc   rR   rd   re   rf   rg   rh   ri   rj   rk   rl   rm   rn   ro   rp   rq   rr   rs   Nrw   )anyr   dictitemsscrape_moduler8   r[   )r\   rH   r_   r`   ra   rb   rc   rR   rd   re   rf   rg   rh   ri   rj   rk   rl   rm   rn   ro   rp   rq   rr   rs   krz   optionss                              rL   r8   FirecrawlClient.scrape{   s   `   o<Whs{  FM  X`  yM  Zb  dm  ot  v}  M  OW  Y`  bm  )n  o  o  o3   
 $ !!! *! *	!
 #4!  ! "! !  !  ! "! '<! &:! $! "!  $!!" #!$  %!&  .'!( ")!*  +!, (-!. eg/! ( !1. / q!t ! (
2 uy3 	4 ##D$4$4c7CC3(s   

C	C	nodepromptlanguagerR   originjob_idcoder   r   )pythonr   bashr   c          
      J    [         R                  " U R                  UUUUUUS9$ )a  
Interact with the browser session associated with a scrape job.

Either ``code`` or ``prompt`` must be provided.

Args:
    job_id: Scrape job ID
    code: Code to execute (optional if prompt is provided)
    prompt: Natural-language instruction for the browser agent (optional if code is provided)
    language: Programming language ("python", "node", or "bash")
    timeout: Execution timeout in seconds (1-300)
    origin: Optional request origin tag

Returns:
    BrowserExecuteResponse with execution result
r   )r   interactr[   r\   r   r   r   r   rR   r   s          rL   r   FirecrawlClient.interact   s2    4 %%
 	
rO   c                 D    [         R                  " U R                  U5      $ )z
Stop the interaction session associated with a scrape job.

Args:
    job_id: Scrape job ID

Returns:
    BrowserDeleteResponse
)r   stop_interactionr[   r\   r   s     rL   r    FirecrawlClient.stop_interaction   s     --d.>.>GGrO   c                 $    U R                  U5      $ z(Deprecated alias for stop_interaction().r   r   s     rL   stop_interactive_browser(FirecrawlClient.stop_interactive_browser       $$V,,rO   c          	      *    U R                  UUUUUUS9$ )z Deprecated alias for interact().r   )r   r   s          rL   scrape_executeFirecrawlClient.scrape_execute  s,     }}  
 	
rO   c                 $    U R                  U5      $ r   r   r   s     rL   delete_scrape_browser%FirecrawlClient.delete_scrape_browser  r   rO   )filenamecontent_typer   filer   r   r   c                F    [         R                  " U R                  UUUUS9$ )a  
Parse an uploaded file using the v2 parse endpoint.

Args:
    file: File path, bytes, bytearray, or binary file-like object
    filename: Optional explicit filename (required for raw bytes without extension)
    content_type: Optional explicit MIME type
    options: Parse-compatible options. Parse rejects change tracking and
        browser-only options such as actions, wait_for, location, and mobile.

Returns:
    Document
)r   r   r   )parse_moduler9   r[   )r\   r   r   r   r   s        rL   r9   FirecrawlClient.parse  s,    * !!%
 	
rO   )	sources
categorieslimittbsrh   ignore_invalid_urlsrR   scrape_optionsrs   queryr   r   r   r   r   r   c       	         h    [        UUUUUUUUU	U
S9
n[        R                  " U R                  U5      $ )av  
Search for documents.

Args:
    query: Search query string
    limit: Maximum number of results to return (default: 5)
    tbs: Time-based search filter
    location: Location string for search
    timeout: Request timeout in milliseconds (default: 300000)
    page_options: Options for scraping individual pages
    
Returns:
    SearchData containing the search results
)
r   r   r   r   r   rh   r   rR   r   rs   )r   search_moduler<   r[   )r\   r   r   r   r   r   rh   r   rR   r   rs   requests               rL   r<   FirecrawlClient.search8  sG    8  ! 3)#
 ##D$4$4g>>rO   FT   )r   exclude_pathsinclude_pathsmax_discovery_depthsitemapignore_sitemapignore_query_parametersr   crawl_entire_domainallow_external_linksallow_subdomainsignore_robots_txtdelaymax_concurrencywebhookr   regex_on_full_urldeduplicate_similar_urlszero_data_retentionpoll_intervalrR   request_timeoutrs   r   r   r   r   )onlyincludeskipr   r   r   r   r   r   r   r   r   r   r   r   r   r   c                   UnUc  Ub  U(       a  SOSn0 SU_SU_SU_SU_SU_SU_S	U	_S
U
_SU_SU_SU_SU_SU_SU_SU_SU_SU_UUS.EnUb  UUS'   [        S0 UD6n[        R                  " U R                  UUUUS9$ )a  
Start a crawl job and wait for it to complete.

Args:
    url: Target URL to start crawling from
    prompt: Optional prompt to guide the crawl
    exclude_paths: Patterns of URLs to exclude
    include_paths: Patterns of URLs to include
    max_discovery_depth: Maximum depth for finding new URLs
    sitemap: Sitemap usage mode ("only" | "include" | "skip")
    ignore_sitemap: Deprecated alias for sitemap ("skip" when true, "include" when false)
    ignore_query_parameters: Ignore URL parameters
    limit: Maximum pages to crawl
    crawl_entire_domain: Follow parent directory links
    allow_external_links: Follow external domain links
    allow_subdomains: Follow subdomains
    ignore_robots_txt: Whether to ignore robots.txt rules
    delay: Delay in seconds between scrapes
    max_concurrency: Maximum number of concurrent scrapes
    webhook: Webhook configuration for notifications
    scrape_options: Page scraping configuration
    regex_on_full_url: Apply includePaths/excludePaths regex to the full URL (including query parameters) instead of just the pathname
    deduplicate_similar_urls: Whether to deduplicate similar URLs during crawl (default: True)
    zero_data_retention: Whether to delete data after 24 hours
    poll_interval: Seconds between status checks
    timeout: Maximum seconds to wait for the entire crawl job to complete (None for no timeout)
    request_timeout: Timeout (in seconds) for each individual HTTP request, including pagination requests when fetching results. If there are multiple pages, each page request gets this timeout
    
Returns:
    CrawlJob when job completes
    
Raises:
    ValueError: If request is invalid
    Exception: If the crawl fails to start or complete
    TimeoutError: If timeout is reached
r   r   rH   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   rs   r   )r   rR   r   rw   )r   crawl_moduler:   r[   )r\   rH   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   rR   r   rs   resolved_sitemaprequest_kwargsr   s                               rL   r:   FirecrawlClient.crawlc  sK   @ ##(B)7vY
3
f
 ]
 ]	

 "#6
 &'>
 U
 "#6
 #$8
  0
  !2
 U
 
 w
 n
   !2!
" '(@#
$ $7&'
* '(8N9%00!!'+
 	
rO   )r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   rs   c                   UnUc  Ub  U(       a  SOSn0 SU_SU_SU_SU_SU_SU_S	U	_S
U
_SU_SU_SU_SU_SU_SU_SU_SU_SU_UUS.EnUb  UUS'   [        S0 UD6n[        R                  " U R                  U5      $ )ac  
Start an asynchronous crawl job.

Args:
    url: Target URL to start crawling from
    prompt: Optional prompt to guide the crawl
    exclude_paths: Patterns of URLs to exclude
    include_paths: Patterns of URLs to include
    max_discovery_depth: Maximum depth for finding new URLs
    sitemap: Sitemap usage mode ("only" | "include" | "skip")
    ignore_sitemap: Deprecated alias for sitemap ("skip" when true, "include" when false)
    ignore_query_parameters: Ignore URL parameters
    limit: Maximum pages to crawl
    crawl_entire_domain: Follow parent directory links
    allow_external_links: Follow external domain links
    allow_subdomains: Follow subdomains
    ignore_robots_txt: Whether to ignore robots.txt rules
    delay: Delay in seconds between scrapes
    max_concurrency: Maximum number of concurrent scrapes
    webhook: Webhook configuration for notifications
    scrape_options: Page scraping configuration
    regex_on_full_url: Apply includePaths/excludePaths regex to the full URL (including query parameters) instead of just the pathname
    deduplicate_similar_urls: Whether to deduplicate similar URLs during crawl (default: True)
    zero_data_retention: Whether to delete data after 24 hours

Returns:
    CrawlResponse with job information
    
Raises:
    ValueError: If request is invalid
    Exception: If the crawl operation fails to start
r   r   rH   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   rw   )r   r   start_crawlr[   )r\   rH   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   rs   r   r   r   s                            rL   r   FirecrawlClient.start_crawl  s<   r ##(B)7vY
3
f
 ]
 ]	

 "#6
 &'>
 U
 "#6
 #$8
  0
  !2
 U
 
 w
 n
   !2!
" '(@#
$ $7&'
* '(8N9%00''(8(8'BBrO   r   pagination_configc                D    [         R                  " U R                  UUUS9$ )a  
Get the status of a crawl job.

Args:
    job_id: ID of the crawl job
    pagination_config: Optional configuration for pagination behavior
    request_timeout: Timeout (in seconds) for each individual HTTP request. When auto-pagination 
        is enabled (default) and there are multiple pages of results, this timeout applies to 
        each page request separately, not to the entire operation
    
Returns:
    CrawlJob with current status and data
    
Raises:
    Exception: If the status check fails
)r   r   )r   get_crawl_statusr[   )r\   r   r   r   s       rL   r    FirecrawlClient.get_crawl_status"  s)    . ,,/+	
 	
rO   next_urlc                B    [         R                  " U R                  UUS9$ )z
Fetch a single page of crawl results using a next URL.

Args:
    next_url: Opaque next URL from a prior crawl status response
    request_timeout: Timeout (in seconds) for the HTTP request

Returns:
    CrawlJob with the page data and next URL (if any)
r   )r   get_crawl_status_pager[   r\   r   r   s      rL   r   %FirecrawlClient.get_crawl_status_page@  s&      11+
 	
rO   crawl_idc                 D    [         R                  " U R                  U5      $ )z
Retrieve error details and robots.txt blocks for a given crawl job.

Args:
    crawl_id: The ID of the crawl job

Returns:
    CrawlErrorsResponse containing per-URL errors and robots-blocked URLs
)r   get_crawl_errorsr[   r\   r   s     rL   r    FirecrawlClient.get_crawl_errorsV  s     ,,T-=-=xHHrO   c                 B    [         R                  " U R                  5      $ )zw
Get a list of currently active crawl jobs.

Returns:
    ActiveCrawlsResponse containing a list of active crawl jobs.
)r   get_active_crawlsr[   r\   s    rL   r   !FirecrawlClient.get_active_crawlsb  s     --d.>.>??rO   c                 "    U R                  5       $ )z
List currently active crawl jobs for the authenticated team.

Returns:
    ActiveCrawlsResponse containing the list of active crawl jobs
)r   r   s    rL   active_crawlsFirecrawlClient.active_crawlsk  s     %%''rO   r<   include_subdomainsr   r   r   rR   rs   rh   r<   r   c                    [        S X#XEXgX4 5       5      (       a  [        UUUUUb  UOSUUU	S9OSn
[        R                  " U R                  X5      $ )a  Map a URL and return discovered links.

Args:
    url: Root URL to explore
    search: Optional substring filter for discovered links
    include_subdomains: Whether to include subdomains
    ignore_query_parameters: Whether to ignore query parameters when mapping
    limit: Maximum number of links to return
    sitemap: Sitemap usage mode ("only" | "include" | "skip")
    timeout: Request timeout in milliseconds

Returns:
    MapData containing the discovered links
c              3   (   #    U  H  oS Lv   M
     g 7frv   rw   rx   s     rL   r{   &FirecrawlClient.map.<locals>.<genexpr>  s       O  )N1$  )Nr}   Nr   r   )r~   r   
map_moduler=   r[   )r\   rH   r<   r   r   r   r   rR   rs   rh   r   s              rL   r=   FirecrawlClient.mapt  s    H   OE\el  xC  )N  O  O  O 1$;&2G	#	
 UY 	 ~~d..==rO   )r   notificationretention_daysnamescheduletargetsr   r   c          	          [        U[        5      (       a  [        S0 UD6n[        UUUUUUS9n[        R
                  " U R                  U5      $ )zCreate a scheduled monitor.)r   r   r   r   r   r   rw   )
isinstancer   r3   r1   monitor_modulecreate_monitorr[   )r\   r   r   r   r   r   r   r   s           rL   r   FirecrawlClient.create_monitor  sU     h%%&22H&%)
 ,,T-=-=wGGrO   r   offsetr   c                @    [         R                  " U R                  XS9$ )z)List monitors for the authenticated team.r   )r   list_monitorsr[   )r\   r   r   s      rL   r   FirecrawlClient.list_monitors  s     ++D,<,<EYYrO   
monitor_idc                 D    [         R                  " U R                  U5      $ )zGet a monitor by ID.)r   get_monitorr[   r\   r   s     rL   r   FirecrawlClient.get_monitor      ))$*:*:JGGrO   r   statusr   r   r   r   r   r  )activepausedc          
          [        U[        5      (       a  [        S0 UD6n[        UUUUUUUS9n	[        R
                  " U R                  X5      $ )zUpdate a monitor.r  rw   )r   r   r3   r5   r   update_monitorr[   )
r\   r   r   r  r   r   r   r   r   r   s
             rL   r	  FirecrawlClient.update_monitor  sX     h%%&22H&%)
 ,,T-=-=zSSrO   c                 D    [         R                  " U R                  U5      $ )zDelete a monitor.)r   delete_monitorr[   r  s     rL   r  FirecrawlClient.delete_monitor  s    ,,T-=-=zJJrO   c                 D    [         R                  " U R                  U5      $ )zRun a monitor manually.)r   run_monitorr[   r  s     rL   r  FirecrawlClient.run_monitor  r  rO   c                D    [         R                  " U R                  UUUS9$ )zList checks for a monitor.r   )r   list_monitor_checksr[   )r\   r   r   r   s       rL   r  #FirecrawlClient.list_monitor_checks  s)     11	
 	
rO   r   r   r  r   check_idr   )samenewchangedremovederrorc          
      J    [         R                  " U R                  UUUUUUS9$ )zAGet a monitor check with page results, auto-paginated by default.r  )r   get_monitor_checkr[   )r\   r   r  r   r   r  r   s          rL   r  !FirecrawlClient.get_monitor_check  s2     ///
 	
rO   c                 D    [         R                  " U R                  U5      $ )z
Cancel a crawl job.

Args:
    crawl_id: The ID of the crawl job to cancel
    
Returns:
    bool: True if the crawl was cancelled, False otherwise
)r   cancel_crawlr[   r   s     rL   r  FirecrawlClient.cancel_crawl  s     (()9)98DDrO   c                 V    [        XS9n[        R                  " U R                  U5      $ )zDerive crawl parameters from natural-language prompt.

Args:
    url: Root URL
    prompt: Instruction describing how to crawl

Returns:
    CrawlParamsData with normalized crawl configuration
)rH   r   )r   r   crawl_params_previewr[   )r\   rH   r   r   s       rL   r"  $FirecrawlClient.crawl_params_preview  s'     %<001A1A7KKrO   
r   schemasystem_promptr   enable_web_searchshow_sourcesr   r   rs   r@   urlsr%  r&  r'  r(  r   r@   c       
         T    [         R                  " U R                  UUUUUUUUU	U
US9$ )a  Start an extract job (non-blocking).

.. deprecated::
    The extract endpoint is in maintenance mode and its use is discouraged.
    Review https://docs.firecrawl.dev/developer-guides/usage-guides/choosing-the-data-extractor
    to find a replacement.

Args:
    urls: URLs to extract from (optional)
    prompt: Natural-language instruction for extraction
    schema: Target JSON schema for the output
    system_prompt: Optional system instruction
    allow_external_links: Allow hyperlinks in output
    enable_web_search: Whether to augment with web search
    show_sources: Include per-field/source mapping when available
    scrape_options: Scrape options applied prior to extraction
    ignore_invalid_urls: Skip invalid URLs instead of failing
    integration: Integration tag/name
    agent: Agent configuration
Returns:
    Response payload with job id/status (poll with get_extract_status)
r$  )extract_modulestart_extractr[   )r\   r)  r   r%  r&  r   r'  r(  r   r   rs   r@   s               rL   r,  FirecrawlClient.start_extract  sB    J ++'!5/%) 3#
 	
rO   r   r%  r&  r   r'  r(  r   r   r   rR   rs   r@   c                X    [         R                  " U R                  UUUUUUUUU	U
UUUS9$ )a  Extract structured data and wait until completion.

.. deprecated::
    The extract endpoint is in maintenance mode and its use is discouraged.
    Review https://docs.firecrawl.dev/developer-guides/usage-guides/choosing-the-data-extractor
    to find a replacement.

Args:
    urls: URLs to extract from (optional)
    prompt: Natural-language instruction for extraction
    schema: Target JSON schema for the output
    system_prompt: Optional system instruction
    allow_external_links: Allow hyperlinks in output
    enable_web_search: Whether to augment with web search
    show_sources: Include per-field/source mapping when available
    scrape_options: Scrape options applied prior to extraction
    ignore_invalid_urls: Skip invalid URLs instead of failing
    poll_interval: Seconds between status checks
    timeout: Maximum seconds to wait (None for no timeout)
    integration: Integration tag/name
    agent: Agent configuration
Returns:
    Final extract response when completed
r.  )r+  r?   r[   )r\   r)  r   r%  r&  r   r'  r(  r   r   r   rR   rs   r@   s                 rL   r?   FirecrawlClient.extractS  sH    R %%'!5/%) 3'#
 	
rO   )r_   r`   ra   rb   rc   rR   rd   re   rf   rg   rh   ri   rj   rk   rl   rm   rn   ro   rp   rq   r   append_to_idr   r   r   rs   idempotency_keyr1  r2  c                   [        S X#XEXgXXXXUUUUUU4 5       5      (       ax  [        S0 [        S0 SU_SU_SU_SU_SU_SU_SU_S	U	_S
U
_SU_SU_SU_SU_SU_SU_SU_SU_SU_SU_SU_6R                  5        VVs0 s H  u  nnUc  M  UU_M     snnD6OSn[        R
                  " U R                  UUUUUUUUUS9
$ s  snnf )ax  Start a batch scrape job over multiple URLs (non-blocking).

Args:
    urls: List of URLs to scrape
    formats: Output formats to collect per URL
    headers: HTTP headers
    include_tags: HTML tags to include
    exclude_tags: HTML tags to exclude
    only_main_content: Restrict scraping to main content
    timeout: Per-request timeout in milliseconds
    wait_for: Wait condition in milliseconds
    mobile: Emulate mobile viewport
    parsers: Parser list (e.g., ["pdf"])
    actions: Browser actions to perform
    location: Location settings
    skip_tls_verification: Skip TLS verification
    remove_base64_images: Remove base64 images from output
    fast_mode: Prefer faster scraping modes
    use_mock: Use a mock data source (internal/testing)
    block_ads: Block ads during scraping
    proxy: Proxy setting
    max_age: Cache max age
    store_in_cache: Whether to store results in cache
    lockdown: Serve only previously cached results; never make outbound requests.
    webhook: Webhook configuration
    append_to_id: Append to an existing batch job
    ignore_invalid_urls: Skip invalid URLs without failing
    max_concurrency: Max concurrent scrapes
    zero_data_retention: Delete data after 24 hours
    integration: Integration tag/name
    idempotency_key: Header used to deduplicate starts

Returns:
    Response payload with job id (poll with get_batch_scrape_status)
c              3   (   #    U  H  oS Lv   M
     g 7frv   rw   rx   s     rL   r{   5FirecrawlClient.start_batch_scrape.<locals>.<genexpr>         Y  )X1$  )Xr}   r_   r`   ra   rb   rc   rR   rd   re   rf   rg   rh   ri   rj   rk   rl   rm   rn   ro   rp   rq   N)r   r   r1  r   r   r   rs   r2  rw   )r~   r   r   r   batch_modulestart_batch_scraper[   ) r\   r)  r_   r`   ra   rb   rc   rR   rd   re   rf   rg   rh   ri   rj   rk   rl   rm   rn   ro   rp   rq   r   r1  r   r   r   rs   r2  r   rz   r   s                                    rL   r8  "FirecrawlClient.start_batch_scrape  s   t   Y<Whs{  FM  X`  yM  Zb  dm  ot  v}  M  OW  )X  Y  Y  Y/   
 $ !!! *! *	!
 #4!  ! "! !  !  ! "! '<! &:! $! "!  $!!" #!$  %!&  .'!( ")!* eg+! ( !1* + q!t ! (
. _c/ 	2 ..% 3+ 3#+
 	
1(s   
CCc                 B    [         R                  " U R                  UUS9$ )zGet current status and any scraped data for a batch job.

Args:
    job_id: Batch job ID
    pagination_config: Optional configuration for pagination behavior

Returns:
    Status payload including counts and partial data
)r   )r7  get_batch_scrape_statusr[   )r\   r   r   s      rL   r;  'FirecrawlClient.get_batch_scrape_status  s&     33/
 	
rO   c                B    [         R                  " U R                  UUS9$ )a  Fetch a single page of batch scrape results using a next URL.

Args:
    next_url: Opaque next URL from a prior batch scrape status response
    request_timeout: Timeout (in seconds) for the HTTP request

Returns:
    BatchScrapeJob with the page data and next URL (if any)
r   )r7  get_batch_scrape_status_pager[   r   s      rL   r>  ,FirecrawlClient.get_batch_scrape_status_page
  s&     88+
 	
rO   c                 D    [         R                  " U R                  U5      $ )zoCancel a running batch scrape job.

Args:
    job_id: Batch job ID

Returns:
    True if the job was cancelled
)r7  cancel_batch_scraper[   r   s     rL   rA  #FirecrawlClient.cancel_batch_scrape  s     //0@0@&IIrO   c                 D    [         R                  " U R                  U5      $ )zRetrieve error details for a batch scrape job.

Args:
    job_id: Batch job ID

Returns:
    Errors and robots-blocked URLs for the job
)batch_methodsget_batch_scrape_errorsr[   r   s     rL   rE  'FirecrawlClient.get_batch_scrape_errors*  s     44T5E5EvNNrO   c                 D    [         R                  " U R                  U5      $ )a  Get the current status (and data if completed) of an extract job.

.. deprecated::
    The extract endpoint is in maintenance mode and its use is discouraged.
    Review https://docs.firecrawl.dev/developer-guides/usage-guides/choosing-the-data-extractor
    to find a replacement.

Args:
    job_id: Extract job ID

Returns:
    Extract response payload with status and optional data
)r+  get_extract_statusr[   r   s     rL   rH  "FirecrawlClient.get_extract_status5  s     001A1A6JJrO   )r%  rs   max_creditsstrict_constrain_to_urlsmodelr   rJ  rK  rL  )zspark-1-prozspark-1-minic                N    [         R                  " U R                  UUUUUUUUS9	$ )a  Start an agent job (non-blocking).

Args:
    urls: URLs to process (optional)
    prompt: Natural-language instruction for the agent
    schema: Target JSON schema for the output (dict or Pydantic BaseModel)
    integration: Integration tag/name
    max_credits: Maximum credits to use (optional)
    model: Model to use for the agent ("spark-1-pro" or "spark-1-mini")
    webhook: Webhook URL or configuration for notifications
Returns:
    Response payload with job id/status (poll with get_agent_status)
)r   r%  rs   rJ  rK  rL  r   )agent_modulestart_agentr[   )	r\   r)  r   r%  rs   rJ  rK  rL  r   s	            rL   rO  FirecrawlClient.start_agentE  s8    2 ''##%=

 
	
rO   )r%  rs   r   rR   rJ  rK  rL  r   c       	         R    [         R                  " U R                  UUUUUUUUU	U
S9$ )aP  Run an agent and wait until completion.

Args:
    urls: URLs to process (optional)
    prompt: Natural-language instruction for the agent
    schema: Target JSON schema for the output (dict or Pydantic BaseModel)
    integration: Integration tag/name
    poll_interval: Seconds between status checks
    timeout: Maximum seconds to wait (None for no timeout)
    max_credits: Maximum credits to use (optional)
    model: Model to use for the agent ("spark-1-pro" or "spark-1-mini")
    webhook: Webhook URL or configuration for notifications
Returns:
    Final agent response when completed
)	r   r%  rs   r   rR   rJ  rK  rL  r   )rN  r@   r[   )r\   r)  r   r%  rs   r   rR   rJ  rK  rL  r   s              rL   r@   FirecrawlClient.agentj  s>    : !!#'#%=
 	
rO   c                 D    [         R                  " U R                  U5      $ )zGet the current status (and data if completed) of an agent job.

Args:
    job_id: Agent job ID

Returns:
    Agent response payload with status and optional data
)rN  get_agent_statusr[   r   s     rL   rT   FirecrawlClient.get_agent_status  s     ,,T-=-=vFFrO   c                 D    [         R                  " U R                  U5      $ )zjCancel a running agent job.

Args:
    job_id: Agent job ID

Returns:
    True if the agent was cancelled
)rN  cancel_agentr[   r   s     rL   rW  FirecrawlClient.cancel_agent  s     (()9)96BBrO   c                 B    [         R                  " U R                  5      $ )zCGet current concurrency and maximum allowed for this team/key (v2).)usage_methodsget_concurrencyr[   r   s    rL   r[  FirecrawlClient.get_concurrency      ,,T-=-=>>rO   c                 B    [         R                  " U R                  5      $ )z-Get remaining credits for this team/key (v2).)rZ  get_credit_usager[   r   s    rL   r_   FirecrawlClient.get_credit_usage      --d.>.>??rO   c                 B    [         R                  " U R                  5      $ )z$Get recent token usage metrics (v2).)rZ  get_token_usager[   r   s    rL   rc  FirecrawlClient.get_token_usage  r]  rO   
by_api_keyc                 D    [         R                  " U R                  U5      $ )z!Get historical credit usage (v2).)rZ  get_credit_usage_historicalr[   r\   re  s     rL   rg  +FirecrawlClient.get_credit_usage_historical  s    889I9I:VVrO   c                 D    [         R                  " U R                  U5      $ )z Get historical token usage (v2).)rZ  get_token_usage_historicalr[   rh  s     rL   rk  *FirecrawlClient.get_token_usage_historical  s    778H8H*UUrO   c                 B    [         R                  " U R                  5      $ )z*Get metrics about the team's scrape queue.)rZ  get_queue_statusr[   r   s    rL   rn   FirecrawlClient.get_queue_status  ra  rO   ttlactivity_ttlstream_web_viewrr   rq  rr  rs  c                F    [         R                  " U R                  UUUUS9$ )a  Create a new browser session.

Args:
    ttl: Total time-to-live in seconds (30-3600, default 300)
    activity_ttl: Inactivity TTL in seconds (10-3600)
    stream_web_view: Whether to enable webview streaming
    profile: Profile config with ``name`` (str) and
        optional ``save_changes`` (bool, default ``True``)

Returns:
    BrowserCreateResponse with session id and CDP URL
rp  )browser_modulerA   r[   )r\   rq  rr  rs  rr   s        rL   rA   FirecrawlClient.browser  s,    ( %%%+
 	
rO   r   r   rR   
session_idc                F    [         R                  " U R                  UUUUS9$ )a!  Execute code in a browser session.

Args:
    session_id: Browser session ID
    code: Code to execute
    language: Programming language ("python", "node", or "bash")
    timeout: Execution timeout in seconds (1-300, default 30)

Returns:
    BrowserExecuteResponse with execution result
rw  )ru  browser_executer[   )r\   rx  r   r   rR   s        rL   rz  FirecrawlClient.browser_execute  s,    & --
 	
rO   c                 D    [         R                  " U R                  U5      $ )zhDelete a browser session.

Args:
    session_id: Browser session ID

Returns:
    BrowserDeleteResponse
)ru  delete_browserr[   )r\   rx  s     rL   r}  FirecrawlClient.delete_browser  s     ,,T-=-=zJJrO   r  )r  	destroyedc                @    [         R                  " U R                  US9$ )zList browser sessions.

Args:
    status: Filter by session status ("active" or "destroyed")

Returns:
    BrowserListResponse with list of sessions
r  )ru  list_browsersr[   )r\   r  s     rL   r  FirecrawlClient.list_browsers  s#     ++
 	
rO   r:   kindr   rR   r  )r:   r;   c                    [        XX#US9$ )a  Create a watcher for crawl or batch jobs.

Args:
    job_id: Job ID to watch
    kind: Job kind ("crawl" or "batch")
    poll_interval: Seconds between status checks
    timeout: Maximum seconds to watch (None for no timeout)

Returns:
    Watcher instance
r  rC   )r\   r   r  r   rR   s        rL   watcherFirecrawlClient.watcher  s    & t$U\]]rO   )r_   r`   ra   rb   rc   rR   rd   re   rf   rg   rh   ri   rj   rk   rl   rm   rn   ro   rp   rq   r   r1  r   r   r   rs   r2  r   wait_timeoutr  c                   [        S X#XEXgXXXXUUUUUU4 5       5      (       ax  [        S0 [        S0 SU_SU_SU_SU_SU_SU_SU_S	U	_S
U
_SU_SU_SU_SU_SU_SU_SU_SU_SU_SU_SU_6R                  5        VV s0 s H  u  nn U c  M  UU _M     sn nD6OSn![        R
                  " U R                  UU!UUUUUUUUUS9$ s  sn nf )z5
Start a batch scrape job and wait until completion.
c              3   (   #    U  H  oS Lv   M
     g 7frv   rw   rx   s     rL   r{   /FirecrawlClient.batch_scrape.<locals>.<genexpr>i  r6  r}   r_   r`   ra   rb   rc   rR   rd   re   rf   rg   rh   ri   rj   rk   rl   rm   rn   ro   rp   rq   N)
r   r   r1  r   r   r   rs   r2  r   rR   rw   )r~   r   r   r   r7  batch_scraper[   )"r\   r)  r_   r`   ra   rb   rc   rR   rd   re   rf   rg   rh   ri   rj   rk   rl   rm   rn   ro   rp   rq   r   r1  r   r   r   rs   r2  r   r  r   rz   r   s"                                     rL   r  FirecrawlClient.batch_scrape-  s   x   Y<Whs{  FM  X`  yM  Zb  dm  ot  v}  M  OW  )X  Y  Y  Y/   
 $ !!! *! *	!
 #4!  ! "! !  !  ! "! '<! &:! $! "!  $!!" #!$  %!&  .'!( ")!* eg+! ( !1* + q!t ! (
. _c/ 	2 ((% 3+ 3#+' 
 	
1(s   
CC)rZ   r[   )Nzhttps://api.firecrawl.devN   g      ?rv   )F)b__name__
__module____qualname____firstlineno____doc__staticmethodstrboolrM   r   floatintr]   r   r   r	   r   r   r   r8   r
   r   r   r   r   r   r   bytes	bytearrayr   r   r9   r   r   r   r   r<   r   r   r:   r   r   r,   r   r   r   r   r   r   r   r+   r    r=   r3   r4   r2   r.   r   r   r   r	  r  r/   r  r  r0   r  r  r   r"  r-   r,  r?   r8  r;  r>  rA  rE  rH  r   rO  r@   rT  rW  r[  r_  rc  rg  rk  rn  rA   rz  r}  r  rD   r  r  __static_attributes__rw   rO   rL   rF   rF   E   s$    2s 2t 2 2
 "&2#' #)
#)
 )
 %	)

 )
 )
^ 37,0,0,0,0!%"&!%KO AE)-04/3$("&$(#!%)-#',0%)3QDQD $~./	QD
 $sCx.)QD tCy)QD tCy)QD $D>QD #QD 3-QD QD %S	4c9n0E+F FGHQD $u  &{   |  }  ~QD :&QD  (~QD  'tn!QD" D>#QD$ 3-%QD& D>'QD( })QD* #+QD, !-QD. 4./QD0 $sCx.)1QD2 c]3QD4 
5QDl #"

 !%6<!% $"
"
 sm"

 "
 23"
 #"
 "
H
Hs 
H-s - #

 !%6<!% $

 sm

 
 23
 #
 
(-C - #'&**.
Cui9:
 3-	

 sm
 ,'
 

D 1559#!"&.2!%26%))?)? $|,-	)?
 T.12)? })? c])? 3-)? &d^)? #)? !/)? c])? 
)?^ !%-1-1-1@D)-(-#$)%*!&"'#)-7;26"')-$)!%+/%)5d
d
 	d

  S	*d
  S	*d
 &c]d
 '";<=d
 !d
 "&d
 }d
 "d
 #d
 d
  d
  }!d
" "##d
$ %] 234%d
& !/'d
(  )d
* #'+d
, "-d
. /d
0 #1d
2 "%3d
4 c]5d
6 
7d
T !%-1-1-1@D)-(-#$)%*!&"'#)-7;26"')-$)%)/WCWC 	WC
  S	*WC  S	*WC &c]WC '";<=WC !WC "&WC }WC "WC #WC WC  WC  }!WC" "##WC$ %] 234%WC& !/'WC(  )WC* #'+WC, "-WC. c]/WC0 
1WCx 9=

 ,0

 $$45

 "%
 

D ,0	

 "%	

 

,
I 
I1D 
I@#7 @(3 ( !%-126#@D!%%)'+&>&> 	&>
 %TN&> "*$&> }&> '";<=&> #&> c]&> 8$&> 
&>\ ,06:(,HH c3h78H eM4S>9:;	H -(H 23H !H 
H4  $ $	Z }Z 	Z
 
gZHc Hg H #8<EIBFMQHL(,TT sm	T
 !345T 5$sCx.!@ABT %tCH~ =>?T u%8$sCx.%HIJT $u]DcN%BCDET !T 
T4K K KHc Hl H  $ $

 }	

 
 
l	
(  $"RV8<

 

 }
 sm
 !MNO
 $$45
 

*
ES 
ET 
EL LS L_ L %)2
 !%+/'+/3,0'+48.2%)(,2
tCy!2
 	2

 c3h(2
  }2
 'tn2
 $D>2
 tn2
 !12
 &d^2
 c]2
 %2
l %)8
 !%+/'+/3,0'+48.2!%%)(,8
tCy!8
 	8

 c3h(8
  }8
 'tn8
 $D>8
 tn8
 !18
 &d^8
 8
 #8
 c]8
 %8
| 37,0,0,0,0!%"&!%KO AE)-04/3$("&$(#!%)-#'7;&*.2)-.2%))-=g
3ig
 $~./	g

 $sCx.)g
 tCy)g
 tCy)g
 $D>g
 #g
 3-g
 g
 %S	4c9n0E+F FGHg
 $u  &{   |  }  ~g
 :&g
  (~g
  'tn!g
" D>#g
$ 3-%g
& D>'g
( })g
* #+g
, !-g
. 4./g
0 %] 2341g
2 sm3g
4 &d^5g
6 "#7g
8 &d^9g
: c];g
< "#=g
X 9=

 $$45
0 ,0	

 "%	
*	J# 	J$ 	J	Oc 	OK K$ %)#

 !%%)%)37BF<@#
tCy!#
 	#

 #
 c]#
 c]#
 #+4.#
  =>?#
 %%7 789#
N %))

 !%%)!%%)37BF<@)
tCy!)
 	)

 )
 c])
 )
 #)
 c])
 #+4.)
  =>?)
 %%7 789)
V	Gs 	G	C3 	C4 	C?@?Wd WVT V@ "&**.,0
 c]
 sm	

 "$
 $sCx.)
B 7=!%

 

 23
 #
6	K 	K <@
 !678
, +2!%^^ &'	^
 ^ #^ 
^2 37,0,0,0,0!%"&!%KO AE)-04/3$("&$(#!%)-#'7;&*.2)-.2%))-&*AK
3iK
 $~./	K

 $sCx.)K
 tCy)K
 tCy)K
 $D>K
 #K
 3-K
 K
 %S	4c9n0E+F FGHK
 $u  &{   |  }  ~K
 :&K
  (~K
  'tn!K
" D>#K
$ 3-%K
& D>'K
( })K
* #+K
, !-K
. 4./K
0 %] 2341K
2 sm3K
4 &d^5K
6 "#7K
8 &d^9K
: c];K
< "#=K
> ?K
@ smAK
 K
rO   rF   )Vr  rW   pathlibr   typingr   r   r   r   r   r	   r
   r   typesr   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r    r!   r"   r#   r$   r%   r&   r'   r(   r)   r*   r+   r,   r-   r.   r/   r0   r1   r2   r3   r4   r5   utils.http_clientr6   utils.error_handlerr7   methodsr8   r   r9   r   r:   r   r;   r7  r<   r   r=   r   rD  r>   rZ  r?   r+  r@   rN  rA   ru  rB   r   r  rD   rF   rw   rO   rL   <module>r     s    
  P P P* * * * * * * * * * *V * / , * * * , & + + . * . . s
 s
rO   