For AI agents: the complete documentation index is available at https://docs.clickmax.io/en/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/en/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/en/reference/api/firecrawl.md.
  • English
  • How to use Firecrawl through the Clickmax API

    The Clickmax API calls Firecrawl to search the web and read pages, with the same Clickmax API key you use for other calls. You do not need a Firecrawl account: without a key of your own connected, Clickmax makes the call on its own account. If you prefer your Firecrawl account, connect its key to the workspace, and calls then spend the credits of your Firecrawl account.

    Before you start, you need:

    • a Clickmax workspace API key (see Authentication in the Clickmax API);
    • only to use your own Firecrawl account: a Firecrawl API key (fc-...), created in the Firecrawl dashboard, and permission to manage integrations in the workspace.

    The Firecrawl connection exists only through the API. It does not appear on the Integrations screen.

    The examples use the TypeScript SDK. Over HTTP, the paths are the same, under /api/v0/firecrawl/.

    Use your own Firecrawl account (optional)

    import { Clickmax } from '@clickmax/public-sdk'
    
    const clickmax = new Clickmax(process.env.CLICKMAX_API_KEY!)
    
    const [ok, error, status] = await clickmax.firecrawl.connect({
      apiKey: process.env.FIRECRAWL_API_KEY!,
    })

    Clickmax checks the key with Firecrawl before storing it, without spending credits. A rejected key is not stored. Connecting again replaces the previous key. Each workspace has one Firecrawl key.

    • clickmax.firecrawl.status() tells whether a key is connected. The billing field says which account calls use: own_key (your Firecrawl account) or clickmax_credits (the Clickmax account).
    • clickmax.firecrawl.disconnect() removes the key. Later calls go back to the Clickmax account.

    Search the web

    const [ok, error, result] = await clickmax.firecrawl.search({
      query: 'aesthetic clinics in Belo Horizonte -site:instagram.com -site:facebook.com',
      limit: 20,
      country: 'BR',
    })
    
    for (const item of result?.data.web ?? []) {
      console.log(item.url, item.title, item.description)
    }

    The query accepts operators such as site:, -site: and quoted phrases. Without scrapeOptions, each result has only url, title and description. To also get each page's content, send scrapeOptions: { formats: ['markdown'], onlyMainContent: true }. This makes the search slower and more expensive.

    Read a page

    const [ok, error, page] = await clickmax.firecrawl.scrape({
      url: 'https://example.com',
      formats: ['markdown', 'links'],
      onlyMainContent: false,
      timeout: 30_000,
    })
    
    if (ok && (page.data.metadata?.statusCode ?? 200) < 400) {
      console.log(page.data.markdown, page.data.links)
    }
    • formats accepts markdown and links. The default is ["markdown"].
    • onlyMainContent: false keeps the header and footer, where phone numbers and WhatsApp links usually are.
    • A page that answered with an error still returns successfully. Check data.metadata.statusCode: 400 or more means an error page.
    • maxAge, storeInCache, blockAds, removeBase64Images and location (country, languages) follow Firecrawl's behavior.

    Check your Firecrawl account balance

    const [ok, error, usage] = await clickmax.firecrawl.creditUsage()
    console.log(usage?.data.remainingCredits)

    This call spends no credits, so it also tells you whether the connected key still works. It only works with your key connected: without one it returns firecrawl_not_connected, and searches and page reads keep working on the Clickmax account.

    Timeout

    timeout ranges from 1000 to 60000 milliseconds, and the default is 30000. Firecrawl stops trying when it reaches that time. Keep the Clickmax client timeout (60000 by default) above the call's timeout, so you get Firecrawl's answer instead of an SDK timeout error.

    Firecrawl errors

    Read the error code to decide what to do.

    codeStatusMeaningWhat to do
    firecrawl_not_connected412creditUsage was called with no Firecrawl key connectedConnect your key with firecrawl.connect, or skip the balance check
    firecrawl_key_invalid412Firecrawl rejected your connected keyConnect a valid key, or disconnect it to use the Clickmax account
    firecrawl_forbidden403Firecrawl denied the call, for example an IP or endpoint restriction on the key, or a blocked URLAdjust the key restrictions at Firecrawl or change the URL; the message says why
    firecrawl_insufficient_credits402Your Firecrawl account has no creditsTop up the account at Firecrawl
    firecrawl_rate_limited429Firecrawl is limiting your key's callsWait for retryAfter and try again. When Firecrawl does not say how long, retryAfter is 10 seconds
    firecrawl_timeout504Firecrawl did not answer in timeTry again or raise timeout
    firecrawl_invalid_request400Firecrawl rejected the parametersFix the call; the message says why
    firecrawl_unavailable502 or 503Firecrawl failed, or the Clickmax Firecrawl account is unavailable right nowTry again later, honoring retryAfter when present, or connect your own key

    Clickmax does not retry Firecrawl calls on its own. The Clickmax API rate limits still apply.