# AI Extraction
Source: https://docs.geekflare.com/ai-extraction-web-scraping

Ask AI to answer questions, extract structured data, or analyze scraped web pages using Geekflare's Web Scraping API.

Scraping a page is the first step. The next is turning that content into an answer, a structured record, or a summary. **AI Extraction** does that in the same request: pass an `aiPrompt` object alongside your `url`, and Geekflare scrapes the page, feeds the cleaned Markdown to an LLM, and returns the result under `aiResult`.

<Info>
  AI Extraction always runs against Markdown content. Any `format` you set in
  the same request is ignored — you don't need to (and shouldn't) combine
  `format` with `aiPrompt`.
</Info>

**Endpoint:** `POST https://api.geekflare.com/webscraping`

**Credits:** +6 on top of the base scrape cost.

***

## How It Works

Every `aiPrompt` object has a required `type` field that selects the extraction mode, plus mode-specific fields:

```json theme={null}
{
  "url": "https://example.com/products/wireless-headphones",
  "aiPrompt": {
    "type": "prompt | schema | product | listing | summary | contact | sentiment | keywords",
    "...": "mode-specific fields below"
  }
}
```

The result is returned under `aiResult` in the response, alongside the usual `data` field (which contains the Markdown content that was analyzed) and `meta`.

***

## 1. `prompt` — Open-Ended Question

Ask any question about the page. The model answers strictly from page content and quotes the supporting sentence(s).

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/products/wireless-headphones',
    aiPrompt: {
      type: 'prompt',
      query: 'What is the return policy?'
    }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/products/wireless-headphones',
      ai_prompt={'type': 'prompt', 'query': 'What is the return policy?'}
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/products/wireless-headphones",
      "aiPrompt": {"type": "prompt", "query": "What is the return policy?"}
    }'
  ```
</CodeGroup>

| Field   | Type   | Required | Description                        |
| ------- | ------ | -------- | ---------------------------------- |
| `query` | string | yes      | Your question, max 1000 characters |

<Accordion title="Response">
  ```json theme={null}
  {
    "aiResult": {
      "type": "prompt",
      "query": "What is the return policy?",
      "answered": true,
      "answer": "Items can be returned within 30 days of purchase for a full refund, provided they're unused and in original packaging.",
      "sourceExcerpt": "..."
    }
  }
  ```
</Accordion>

If the answer isn't present in the page content, `answered` is `false` and `answer`/`sourceExcerpt` are `null` — the model never guesses.

***

## 2. `schema` — Custom JSON Schema Extraction

Define your own field shape and let AI extract matching data from any page.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/products/wireless-headphones',
    aiPrompt: {
      type: 'schema',
      schema: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          price: { type: 'number' },
          currency: { type: 'string' },
          inStock: { type: 'boolean' }
        }
      }
    }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/products/wireless-headphones',
      ai_prompt={
          'type': 'schema',
          'schema': {
              'type': 'object',
              'properties': {
                  'title': {'type': 'string'},
                  'price': {'type': 'number'},
              }
          }
      }
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/products/wireless-headphones",
      "aiPrompt": {
        "type": "schema",
        "schema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "price": {"type": "number"}
          }
        }
      }
    }'
  ```
</CodeGroup>

| Field    | Type   | Required | Description                                                              |
| -------- | ------ | -------- | ------------------------------------------------------------------------ |
| `schema` | object | yes      | JSON Schema-like object describing the fields to extract, max 4000 bytes |

<Accordion title="Response">
  ```json theme={null}
  {
    "aiResult": {
      "type": "schema",
      "data": {
        "title": "AudioTech Wireless Noise-Cancelling Headphones",
        "price": 199.99,
        "currency": "USD",
        "answered": true,
        "inStock": true
      }
    }
  }
  ```
</Accordion>

<Info>
  AI extraction output is validated against your schema on a best-effort basis.
  Fields the model couldn't find are returned as `null` rather than omitted or
  invented.
</Info>

***

## 3. `product` — Preset Product Extraction

A ready-made schema tuned for e-commerce pages — no schema definition needed.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/products/wireless-headphones',
    aiPrompt: { type: 'product' }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/products/wireless-headphones',
      ai_prompt={'type': 'product'}
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/products/wireless-headphones",
      "aiPrompt": {"type": "product"}
    }'
  ```
</CodeGroup>

No additional fields — `product` takes only `type`.

<Accordion title="Response">
  ```json theme={null}
  {
    "aiResult": {
      "type": "product",
      "data": {
        "name": "AudioTech Wireless Noise-Cancelling Headphones",
        "brand": "AudioTech",
        "price": { "amount": 199.99, "currency": "USD" },
        "availability": "in_stock",
        "rating": { "value": 4.5, "count": 1240 },
        "variants": ["Black", "Silver"],
        "images": ["https://example.com/images/headphones-black.jpg"],
        "answered": true,
        "description": "Over-ear wireless headphones with active noise cancellation and 30-hour battery life."
      }

  }
  }

  ```
</Accordion>

`currency` is always returned as an ISO 4217 code (e.g. `USD`, `INR`), never a symbol. If the page isn't a product page, all fields are returned as `null`.

***

## 4. `listing` — Category/Search Page Extraction

Extract an array of items from a category or search-results page using your own item schema.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/category/headphones',
    aiPrompt: {
      type: 'listing',
      itemSchema: {
        type: 'object',
        properties: {
          name: { type: 'string' },
          price: { type: 'number' }
        }
      },
      maxItems: 20
    }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/category/headphones',
      ai_prompt={
          'type': 'listing',
          'item_schema': {
              'type': 'object',
              'properties': {'name': {'type': 'string'}, 'price': {'type': 'number'}}
          },
          'max_items': 20
      }
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/category/headphones",
      "aiPrompt": {
        "type": "listing",
        "itemSchema": {
          "type": "object",
          "properties": {"name": {"type": "string"}, "price": {"type": "number"}}
        },
        "maxItems": 20
      }
    }'
  ```
</CodeGroup>

| Field        | Type   | Required | Default | Description                                           |
| ------------ | ------ | -------- | ------- | ----------------------------------------------------- |
| `itemSchema` | object | yes      | —       | JSON Schema-like object for each item, max 4000 bytes |
| `maxItems`   | number | no       | `20`    | Maximum items to extract (1–50)                       |

<Accordion title="Response">
  ```json theme={null}
  {
    "aiResult": {
      "type": "listing",
      "answered": true,
      "itemCount": 18,
      "items": [
        { "name": "AudioTech Wireless Headphones", "price": 199.99 },
        { "name": "SoundWave Pro Earbuds", "price": 129.00 }
      ]
    }
  }
  ```
</Accordion>

Navigation links, ads, and unrelated content are excluded automatically. Items are returned in page order, capped at `maxItems`.

***

## 5. `summary` — Condensed Page Summary

Summarize the page in paragraph, unordered list, or TL;DR form, optionally focused on one topic.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/blog/state-of-web-scraping-2026',
    aiPrompt: {
      type: 'summary',
      style: 'bullets',
      focus: 'pricing'
    }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/blog/state-of-web-scraping-2026',
      ai_prompt={'type': 'summary', 'style': 'bullets', 'focus': 'pricing'}
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/blog/state-of-web-scraping-2026",
      "aiPrompt": {"type": "summary", "style": "bullets", "focus": "pricing"}
    }'
  ```
</CodeGroup>

| Field       | Type   | Required | Default     | Description                                                            |
| ----------- | ------ | -------- | ----------- | ---------------------------------------------------------------------- |
| `style`     | string | no       | `paragraph` | `paragraph`, `bullets` (unordered list), or `tldr`                     |
| `focus`     | string | no       | —           | Only summarize content relevant to this topic, max 200 characters      |
| `maxLength` | number | no       | `5`         | Sentence count for `paragraph`/`tldr`, item count for `bullets` (1–20) |

<Accordion title="Response">
  ```json theme={null}
  {
    "aiResult": {
      "type": "summary",
      "style": "bullets",
      "answered": true,
      "summary": [
        "Web scraping demand grew due to AI training data needs and real-time price monitoring.",
        "Headless browser detection has become the biggest technical hurdle for scrapers in 2026.",
        "Markdown-based extraction is replacing raw HTML parsing for LLM-based pipelines."
      ]
    }
  }
  ```
</Accordion>

<Info>
  `summary` is a string for `paragraph`/`tldr` style, and an array of strings
  for `bullets` style.
</Info>

***

## 6. `contact` — Contact & Company Details

Extract company name, emails, phone numbers, address, social links, and business hours from a contact or about page.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/contact-us',
    aiPrompt: { type: 'contact' }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/contact-us',
      ai_prompt={'type': 'contact'}
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/contact-us",
      "aiPrompt": {"type": "contact"}
    }'
  ```
</CodeGroup>

No additional fields — `contact` takes only `type`.

<Accordion title="Response">
  ```json theme={null}
  {
    "aiResult": {
      "type": "contact",
      "answered": true,
      "data": {
        "companyName": "Example Corp",
        "emails": ["support@example.com", "sales@example.com"],
        "phones": ["+1-800-555-0199"],
        "address": {
          "raw": "123 Market Street, Suite 400, San Francisco, CA 94103, USA",
          "city": "San Francisco",
          "region": "CA",
          "country": "USA",
          "postalCode": "94103"
        },
        "socials": {
          "linkedin": "https://linkedin.com/company/example-corp",
          "twitter": "https://twitter.com/examplecorp"
        },
        "hours": "Mon–Fri, 9am–6pm PST"
      }
    }
  }
  ```
</Accordion>

Only data explicitly present in the content is returned — the model never guesses an email or phone number.

***

## 7. `sentiment` — Sentiment Analysis

Analyze overall or aspect-based sentiment across reviews, comments, or opinion text on the page.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/reviews/wireless-headphones',
    aiPrompt: {
      type: 'sentiment',
      aspects: ['sound quality', 'battery life', 'comfort', 'price']
    }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/reviews/wireless-headphones',
      ai_prompt={
          'type': 'sentiment',
          'aspects': ['sound quality', 'battery life', 'comfort', 'price']
      }
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/reviews/wireless-headphones",
      "aiPrompt": {
        "type": "sentiment",
        "aspects": ["sound quality", "battery life", "comfort", "price"]
      }
    }'
  ```
</CodeGroup>

| Field     | Type      | Required | Description                                                                    |
| --------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `aspects` | string\[] | no       | Up to 10 aspects to score individually. Omit to return only overall sentiment. |

<Accordion title="Response">
  ```json theme={null}
  {
    "aiResult": {
      "type": "sentiment",
      "answered": true,
      "overall": {
        "label": "positive",
        "score": 0.78,
        "distribution": { "positive": 0.72, "neutral": 0.18, "negative": 0.10 }
      },
      "aspects": [
        { "aspect": "sound quality", "label": "positive", "score": 0.91 },
        { "aspect": "price", "label": "negative", "score": -0.34 }
      ],
      "summary": "Reviewers are overwhelmingly positive on sound quality and battery life, but frequently mention the price as too high."
    }
  }
  ```
</Accordion>

***

## 8. `keywords` — Keywords, Tags & Entities

Extract ranked keywords, named entities, and suggested content tags.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/blog/state-of-web-scraping-2026',
    aiPrompt: {
      type: 'keywords',
      maxKeywords: 10,
      includeEntities: true
    }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/blog/state-of-web-scraping-2026',
      ai_prompt={'type': 'keywords', 'max_keywords': 10, 'include_entities': True}
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/blog/state-of-web-scraping-2026",
      "aiPrompt": {"type": "keywords", "maxKeywords": 10, "includeEntities": true}
    }'
  ```
</CodeGroup>

| Field             | Type    | Required | Default | Description                                                        |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------------------------ |
| `maxKeywords`     | number  | no       | `10`    | Maximum keywords to return (1–30)                                  |
| `includeEntities` | boolean | no       | `false` | Also extract named entities (orgs, people, dates, laws, locations) |

<Accordion title="Response">
  ```json theme={null}
  {
    "aiResult": {
      "type": "keywords",
      "answered": true,
      "keywords": [
        { "term": "web scraping", "relevance": 0.97 },
        { "term": "headless browser detection", "relevance": 0.84 }
      ],
      "entities": [
        { "text": "GDPR", "type": "law" },
        { "text": "Cloudflare", "type": "organization" }
      ],
      "suggestedTags": ["web-scraping", "ai", "data-extraction", "proxies", "compliance"]
    }
  }
  ```
</Accordion>

`entities` is only included when `includeEntities` is `true`.

***

## Content Handling

AI Extraction always uses the page's Markdown content — the same content you'd get from the `markdown` format — regardless of any `format` value you set. This keeps the model's input focused on primary content.

## Notes & Limits

* Only one `aiPrompt` mode can be used per request.
* Every mode answers strictly from the scraped page content — the model does not use outside knowledge and will not invent data that isn't present.
* Page content is treated as untrusted data: instructions embedded in scraped pages are ignored.
* Very long pages are truncated before analysis; if you're missing expected data from a long listing or product page, try narrowing the `url` to a more specific page.


# Supported AI Models
Source: https://docs.geekflare.com/ai/chat/available-models

All Available AI Models in Geekflare Chat.

[Geekflare Chat](http://geekflare.com/ai/chat/) gives you access to the world’s most powerful AI models from top providers in a single workspace. You don't need to manage multiple subscriptions; simply select the model that fits your task from the model dropdown.

> 💡 **Important:**
> Different models require different amounts of compute power. Models are categorized into tiers (Lite, Advanced, and Ultra), and will consume a different number of credits per message.
>
> Before chatting, please review our **[Understanding the Credit System](https://docs.geekflare.com/ai/chat/credit-system)** guide to see exactly how many credits your selected model will cost. The cost is also displayed in the model dropdown interface.

![Credit Info](https://cdn.geekflare.com/api-assets/chat-credit-info.png)

## <Icon icon="openai" /> OpenAI

OpenAI provides industry-leading models for general conversation, reasoning, and specialized coding tasks.

* GPT-5.5
* GPT-5 Nano
* GPT-5 Mini
* GPT-4.1 Nano
* GPT-4.1 Mini
* GPT-4o Mini
* o4 Mini (Reasoning)
* GPT-5.1 Codex Mini (Coding)
* GPT-5.4
* GPT-5.3 Chat
* GPT-5.3 Codex (Coding)
* GPT-4.1
* GPT-4o
* o3 (Reasoning)
* GPT Image 1
* GPT Image 2

## Google Gemini

Google's Gemini ecosystem is highly optimized for speed, multimodal tasks (images), and wide context windows.

* Gemini 3.5 Flash
* Gemini 3.1 Pro
* Gemini 3 Pro
* Gemini 3 Pro Image (Naon Banana Pro)
* Gemini 3.1 Flash Image (Nano Banana 2)
* Gemini 3 Flash
* Gemini 3.1 Flash Lite

## xAI Grok

Grok models offer exceptionally fast processing and good for social media content.

* Grok Build 0.1
* Grok 4.3
* Grok 4.20 (Reasoning)
* Grok 4.20 (Non-Reasoning)
* Grok 4 Fast (Non-Reasoning)
* Grok Imagine Image

## Anthropic Claude

Claude models are renowned for their nuanced writing, high emotional intelligence, and ability to handle massive documents without losing context.

* Claude Opus 4.7
* Claude Opus 4.6
* Claude Sonnet 4.6
* Claude Haiku 4.5

## Perplexity Sonar

Perplexity models are optimized for search and retrieving up-to-date information.

* Sonar Pro
* Sonar Reasoning
* Sonar

## Mistral

Mistral provides highly efficient, open-weight-style models that are excellent for logic, formatting, and fast text generation.

* Mistral Large 3
* Magistral Medium
* Magistral Small
* Ministral 14B

## MiniMax

MiniMax builds powerful language models to help with everyday tasks, coding, and real-world problem solving.

* MiniMax M3
* Minimax M2.7
* Minimax M2.5

## Qwen

Qwen AI models are built by Alibaba. They are for fast and good for general chat and coding.

* Qwen 3.7 Plus
* Qwen 3.7 Max
* Qwen 3.6 Max
* Qwen 3.5 Flash
* Qwen 3.6 Plus

## Meta Llama

Llama is a family of open AI models by Meta. It is built for flexible, high-performance chat, coding, and multimodal use cases.

* Llama 4 Scout
* Llama 4 Maverick

## Kimi

Kimi by Moonshot AI is focused on long-context models that excel at reading, reasoning, and productivity tasks.

* Kimi K2.6
* Kimi K2.5

## DeepSeek

Fast AI for coding, reasoning, and everyday tasks. Ideal when you want strong performance without high cost.

* DeepSeek V4 Pro
* DeepSeek V4 Flash
* DeepSeek V4 3.2

***

### 🔄 Switching Models Mid-Conversation

You don't have to stick to one model! You can start a conversation with a fast model to brainstorm, and then switch to a reasoning model in the same chat to write code based on your brainstorm.


# Copy and Export Chat Responses
Source: https://docs.geekflare.com/ai/chat/copy-export



Geekflare Chat provides multiple options to copy and export AI model responses.

### Copy Options

Every chat response includes a copy icon to save the output to your clipboard. You can choose from three formats based on your needs:

* **Copy as Markdown:** Copies the raw markdown syntax. This is ideal for pasting into code editors, GitHub, Notion, or other markdown-supported platforms.
* **Copy as Text:** Copies plain text only. This strips away all rich text styling, links, and code block formatting.
* **Copy with Formatting:** Copies the rich text exactly as it appears in the chat. This preserves bolding, lists, and links, making it perfect for pasting directly into emails or Google Docs.

<img alt="Chat Copy" />

### Export Options

For detailed responses, Geekflare Chat enables direct file exports. The export menu appears conditionally only when an AI response exceeds 200 words. You can download the response in the following formats:

* **PDF (.pdf):** Best for saving finalized documents to share with stakeholders.
* **Word Document (.docx):** Best for continued editing, formatting, and team collaboration in Microsoft Word or Google Docs.
* **Markdown (.md):** Best for saving technical documentation, code-heavy responses, or blog posts directly to your local file system.

<img alt="Chat Export" />


# Chat Credit System
Source: https://docs.geekflare.com/ai/chat/credit-system

How credits are calculated in Geekflare Chat

To make AI usage predictable, [Geekflare Chat](https://geekflare.com/ai/chat/) uses a Credit System instead of confusing token counts.

Every time you send a message or generate an image, a specific number of credits is deducted from your monthly balance based on the model you are using.

## Credit Costs at a Glance

Costs are calculated per request, which includes your prompt, the AI's response, and the context of the conversation.

| Tier                | Cost per Request | Description                                                   |
| :------------------ | :--------------- | :------------------------------------------------------------ |
| **Lite Models**     | **1 Credit**     | Fast, everyday models perfect for drafting and quick answers. |
| **Advanced Models** | **15 Credits**   | Leading models for coding and deep reasoning.                 |
| **Ultra Models**    | **60 Credits**   | The most powerful models available.                           |
| **Standard Images** | **20 Credits**   | High-quality image generation for everyday use.               |
| **HD Images**       | **80 Credits**   | High-definition image generation.                             |
| **Ultra Images**    | **160 Credits**  | Ultra-high-definition premium images.                         |

### Feature Add-ons

If you use advanced workspace features during a chat, a small additional credit fee is applied to that request:

* Knowledge Base (Chatting with files using Data Sources): +5 Credits per request

## Extended Context, Chat History, and File Attachments

The standard credit costs listed above cover a base limit of up to **10,000 tokens** per request (roughly 40,000 characters, or 7,500 to 10,000 words).

To give you high-quality answers, the AI needs context. Your total token count for a single request includes:

1. Your current message
2. Previous messages in the same conversation (Chat History)
3. Any files, documents, or images you attach directly to the chat
4. The AI's response

**The Multiplier Effect**
If your conversation gets very long or you attach large files, your request may exceed the 10,000 base token limit. When this happens, a multiplier is applied to the base cost of your chosen model.

We calculate the multiplier using this formula:

Multiplier = ⌈ Total Tokens / 10000 ⌉

**How File Attachments Work**

* **Text & Data Files** (`.txt`, `.csv`, `.json`, `.py`, etc.): Tokens are calculated based on the text length.
* **PDFs & Images:** Token usage is dynamic. Multi-page PDFs and high-resolution images require more tokens to process, which may trigger a multiplier.

<Note>Tip: If you need to analyze a document without triggering high multipliers, add it to your Knowledge Base (RAG) in Data instead of attaching it directly. The Knowledge Base searches only the most relevant sections, keeping your token count low.</Note>

## View Models by Tier

<AccordionGroup>
  <Accordion title="Lite Models (1 Credit)">
    * **Google:** Gemini 3.1 Flash Lite
    * **OpenAI:** GPT 5 Nano, GPT 5 Mini, GPT 5.1 Codex Mini, GPT 4.1 Nano, GPT 4.1 Mini, GPT 4o Mini
    * **Mistral:** Mistral 14B, Mistral Magistral Small
    * **MiniMax:** Minimax M2.7, Minimax 2.5
    * **Qwen:** Qwen 3.5 Flash
    * **Meta:** Llama 4 Scout, Llama 4 Maverick
    * **DeepSeek:** DeepSeek V4 Flash
  </Accordion>

  <Accordion title="Advanced Models (15 Credits)">
    * **Anthropic:** Claude Haiku 4.5, Claude Sonnet 4.6
    * **Google:** Gemini 3.5 Flash, Gemini 3.1 Pro, Gemini 3 Pro, Gemini 3 Flash
    * **OpenAI:** GPT 5.4, GPT 5.3 Chat, GPT 5.3 Codex, GPT 4.1, o4 Mini, o3, GPT 4o
    * **xAI:** Grok Build 0.1, Grok 4.3, Grok 4.20
    * **Perplexity:** Sonar, Sonar Reasoning
    * **Mistral:** Mistral Large, Mistral Magistral Medium
    * **Qwen:** Qwen 3.7 Plus, Qwen 3.7 Max, Qwen 3.6 Max, Qwen 3.6 Plus
    * **Kimi:** Kimi K2.6, Kimi K2.5
    * **DeepSeek:** DeepSeek V4 Pro
    * **MiniMax:** MiniMax M3
  </Accordion>

  <Accordion title="Ultra Models (60 Credits)">
    * **Anthropic:** Claude Opus 4.7, Claude Opus 4.6
    * **OpenAI:** GPT 5.5
    * **Perplexity:** Sonar Pro
  </Accordion>

  <Accordion title="Standard Images (20 Credits)">
    * **xAI:** Grok Imagine Image
  </Accordion>

  <Accordion title="HD Images (80 Credits)">
    * **Google:** Gemini 3.1 Flash Image (Nano Banana 2)
    * **OpenAI:** GPT Image 2
    * **xAI:** Grok Imagine Image Pro
  </Accordion>

  <Accordion title="Ultra Images (160 Credits)">
    * **Google:** Gemini 3 Pro Image (Nano Banana Pro)
    * **OpenAI:** GPT Image 1
  </Accordion>
</AccordionGroup>

## How Credits are Calculated (Examples)

Here is how your credits are used in real-world scenarios:

* **Scenario A (Standard Chat)**: Asking a Lite Model like GPT 5 Nano to write an email. (Under 10K tokens).
  * Cost: **1 Credit**.
* **Scenario B (Advanced Task)**: Asking an Advanced Model like Claude Sonnet 4.6 to write a React component. (Under 10K tokens).
  * Cost: **15 Credits**.
* **Scenario C (Long Chat History)**: You have been chatting with an Advanced Model for an hour. The accumulated chat history sent to the AI is now 25,000 tokens. The formula applies a 3x multiplier to the base 15-credit cost.
  * Cost: **45 Credits**.
* **Scenario D (Large File Attachment)**: You attach a large 40,000-token file to a Lite Model (1 credit). The formula applies a 4x multiplier.
  * Cost: **4 Credits**.
* **Scenario E (Knowledge Base)**: Asking a Lite Model to summarize a small PDF you uploaded to your Knowledge Base.
  * Cost: 1 (Lite Model) + 5 (Knowledge Base Add-on) = **6 Credits**.

## Tips to Reduce Credit Usage in Geekflare Chat

If you want to stretch your monthly credits further, follow these best practices.

**Start new chats frequently**

Because the AI needs to remember what you discussed, every new message you send includes your previous chat history. In a long conversation, this accumulating history can push your total tokens past the 10,000 base limit, triggering a 2x, 3x, or higher multiplier. When you change topics or no longer need the AI to remember earlier messages, start a fresh chat.

**Use Lite models for everyday tasks**

Not every prompt requires the heavy reasoning of a premium model. Use Lite models for drafting emails, brainstorming, summarizing text, or answering general questions. Reserve Advanced and Ultra models for coding, deep analysis, and intricate logic.

**Upload recurring files to your Knowledge Base**

If you attach a large file directly in the chat window, its entire token weight is processed with every single message you send. If you plan to chat with a file multiple times, upload it to your Knowledge Base (Data) instead.

**Combine multiple instructions into one prompt**

Since credits are charged per request, sending three separate, short messages will cost three times as much as sending one. Batch your questions and instructions into a single prompt to minimize base request charges.


# Understanding Memory and Context
Source: https://docs.geekflare.com/ai/chat/memory-and-context

How memory and context is managed in Geekflare Chat.

When you interact with an AI model, it does not possess memory like a human does. To help the AI follow your conversation, Geekflare Chat forwards your recent chat history (context) to the LLM alongside your new prompt.

How much the AI remembers depends entirely on **two factors**: the number of previous messages configured in your settings and the maximum context window supported by the LLM you are using.

## Default Memory Behavior

To provide a good experience while optimizing your costs, Geekflare Chat sends the **previous 10 messages to the AI by default**. This gives the model enough background to understand ongoing topics without consuming excessive credits.

## Customizing Your Chat Memory

You have full control over how much history is sent to the AI. By going to **Chat Settings**, you can adjust the context limit from 0 to up to 50 previous messages.

<img alt="Chat Memory Settings" />

## Credit Usage and the Long Context Notice

Please be aware that increasing your context limit comes with a trade-off. Sending a higher number of previous messages requires the AI to process more data, which will trigger higher credit usage for every new message you send.

If your active conversation exceeds 20,000 tokens, Geekflare Chat will display a **Long Context Notice** banner. This is a friendly alert to help you avoid unexpected credit consumption. You can learn more about how this works and how to manage your costs in our [Long Context Notice guide](https://docs.geekflare.com/ai/chat/what-is-long-context-notice).


# Supported File Types in Geekflare Chat
Source: https://docs.geekflare.com/ai/chat/supported-file-types



Geekflare Chat allows you to attach a variety of files to chat with LLMs for analysis, data extraction, and visual processing. You can attach these files by dragging them into the chat input box or clicking the + icon.

<img alt="File Attachment" />

## List of Supported File Types

### Documents & Presentations

* `.pdf` (Portable Document Format)
* `.docx` (Microsoft Word)
* `.pptx` (Microsoft PowerPoint)
* `.txt` (Plain Text)
* `.md` (Markdown)

### Spreadsheets & Data

* `.xlsx` (Microsoft Excel)
* `.csv` (Comma-Separated Values)

### Code & Configuration

* `.json`, `.yaml`, `.yml`, `.ini` (Configuration)
* `.html`, `.css` (HTML and CSS)
* `.py`, `.js`, `.ts`, `.tsx` (Python, JavaScript, and TypeScript)

### Images & Visuals

* `.jpg`, `.jpeg`, `.png`, `.webp`
* `.svg` (Scalable Vector Graphics)

## Credit Usage for Attachments

Attaching large files or multiple files increases the total token count of your prompt. If your total token count exceeds the base limit, a multiplier is applied to your request.

For full details on how file sizes affect your credit balance, please refer to our [Chat Credit System](https://docs.geekflare.com/ai/chat/credit-system) documentation.


# Understanding the Long Context Notice
Source: https://docs.geekflare.com/ai/chat/what-is-long-context-notice



The long context notice is a friendly alert that appears when your current conversation has become long. We show this banner to help you manage your account usage efficiently and avoid unexpected credit consumption.

<img alt="Long Context Warning" />

## Why is there an extra cost?

AI models do not automatically remember past messages like a human does. Every time you send a new message in an ongoing chat, Geekflare Chat has to send your entire conversation history back to the AI so it understands the context. As your chat gets longer, the AI has to read and process significantly more text for every single reply. This requires more computing power, which increases the cost.

## How long context impact credits?

Our standard credit usage is based on conversations up to 10,000 tokens (roughly 7,500 words). When your chat history stays under this limit, you only pay the standard base credit rate per message. Once your conversation grows beyond this 10,000-token threshold, each new message will consume additional credits to cover the extra processing power required by the AI to read the long chat history.

## How to manage and keep your credit usage low?

* **Start a new chat:** The easiest way to save credits is to start a fresh chat whenever you change topics or no longer need the AI to remember the earlier messages.
* **Keep conversations focused:** Try to limit single chat threads to a specific task. Once the task is complete, move on to a new chat.
* **Reduce chat memory:** By default, we send previous 10 messages to LLM. You can further reduce to lower the overall context.
  <img alt="Chat Memory Settings" />
* **Enable Compact Context Mode:** If you need to keep the conversation going but want to save on costs, turn on Compact Context Mode under Chat Settings. This feature summarizes older messages for the AI to remember the core details of your conversation while reducing the credit usage.

By keeping an eye on the Long Context Notice, you can take full control of your credit usage while still taking advantage of continuous conversations when you truly need them.


# Getting API Keys for AI Models
Source: https://docs.geekflare.com/ai/connect/getting-ai-api-keys



This guide will walk you through the process of obtaining API keys from various popular AI model providers like OpenAI, Gemini, DeepSeek, Claude, xAI Grok, and Mistral. These keys are required when using the Geekflare Connect (BYOK) product to interact with AI models.

## Best Practices for API Key Management

Before you start obtaining keys for AI models, here are some best practices you should follow for managing your API keys.

* **Treat API Keys Like Passwords:** They grant access to your account and billable services. Keep them confidential and secure. Do not share publicly.
* **Rotate Keys Regularly:** For enhanced security, consider regenerating your API keys periodically.
* **Monitor Your API Usage:** Keep an eye on your API usage dashboards provided by the AI model provider. This helps you track costs, stay within quotas, and detect any unauthorized activity.
* **Understand Pricing and Quotas:** Be aware of the pricing model, free tiers, rate limits, and usage quotas associated with each API to avoid unexpected charges or service disruptions.
* **Revoke Unused or Compromised Keys:** If a key is no longer needed or you suspect it has been compromised, revoke or delete it immediately from the provider's dashboard.

## OpenAI API Key

**If you don't have an OpenAI account yet:**

* Go to [OpenAI Platform](https://platform.openai.com/) and click 'Sign up' to create a new account, or 'Log in' if you've already started the process.

![OpenAI](https://cdn.geekflare.com/ai-assets/openai-login.png)

* After logging in, you might see a 'Get Started' button. Click it to proceed.

![OpenAI](https://cdn.geekflare.com/ai-assets/openai-get-started.png)

* On the next page, click the ‘Create an API key’ button.

![OpenAI](https://cdn.geekflare.com/ai-assets/openai-create-api-key.png)

* On the API keys page, click the ‘Create new secret key’ button, typically located on the top right.

![OpenAI](https://cdn.geekflare.com/ai-assets/openai-create-secret-key.png)

* A dialog will appear. Give your API Key a descriptive name (e.g., "Geekflare Connect Integration") and then click ‘Create secret key’.

![OpenAI](https://cdn.geekflare.com/ai-assets/openai-secret-key.png)

* Your new API Key (also referred to as a Secret Key) will be generated and displayed only once. Click the 'Copy' button to copy the key. Important: Store this key securely immediately. You will not be able to view it again after closing this window.

![OpenAI](https://cdn.geekflare.com/ai-assets/openai-save-key.png)

**If you already have an OpenAI account:**

* Go to the OpenAI Platform and log in to your account.
* Once logged in, click on your personal icon (usually in the top right corner) and select 'View API keys' from the dropdown menu.

> (Alternatively, you can often directly navigate to [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys) after logging in.)

* On the API keys page, click the ‘Create new secret key’ button, typically located on the top right.
* Give your API Key a descriptive name (e.g., "Geekflare AI Integration") and then click ‘Create secret key'.
* Your new API Key (Secret Key) will be generated and displayed only once. Click the 'Copy' button to copy it. Important: Store this key securely immediately. You will not be able to view it again after closing this window.

**Video Tutorial**

<iframe />

## Gemini API Key

This guide assumes you are signing in for the first time or creating a new project for your Gemini API key.

* Go to [Google AI Studio](https://aistudio.google.com/) and sign in with your Google account.
* On the main page, look for and click the ‘Get API Key’ button, found at the bottom left of the page. This will take you to the API key management interface.

![Gemini](https://cdn.geekflare.com/ai-assets/gemini-ai-studio.png)

* Click the ‘Create API Key’ button.

![Gemini](https://cdn.geekflare.com/ai-assets/gemini-create-key.png)

* Gemini API keys are associated with Google Cloud Projects. You will be prompted to either import an existing project or create a new project. Select the 'Create project' option and give your new project a descriptive name.

![Gemini](https://cdn.geekflare.com/ai-assets/gemini-create-project.png)

* Once the project is created, your new API key will be displayed. Click the 'Copy' button next to the key.

![Gemini](https://cdn.geekflare.com/ai-assets/gemini-key-ready.png)

**Video Tutorial**

<iframe />

## Claude API Key

To integrate Anthropic's Claude models with Geekflare Connect, you'll need an Anthropic Claude API Key.

* Go to the [Claude Console page](https://console.anthropic.com/) and sign up for a new account or log in if you already have one.
* On the left-hand navigation menu, click the ‘API Keys’ option OR ‘Get API Key’ button on the dashboard.

![Claude](https://cdn.geekflare.com/ai-assets/claude-get-api-key.png)

* On the API Keys page, click the ‘Create Key’ button.

![Claude](https://cdn.geekflare.com/ai-assets/claude-create-key.png)

* A dialog will appear asking for a key name. Give your API Key a descriptive name (e.g., "Geekflare AI Integration") and then click ‘Add’.

![Claude](https://cdn.geekflare.com/ai-assets/claude-key-name.png)

* Your new API key will be generated and displayed only once. Click the 'Copy' button to copy the key.

![Claude](https://cdn.geekflare.com/ai-assets/claude-key-ready.png)

## DeepSeek API Key

* Go to [DeepSeek API Platform](https://platform.deepseek.com/)
* Log in to your existing account. If you are visiting for the first time, you will need to sign up.

![DeepSeek](https://cdn.geekflare.com/ai-assets/deepseek-login.png)

* From the left navigation sidebar, click ‘API Keys’. Then, on the API Keys page, click the ‘Create new API key’ button.

![DeepSeek](https://cdn.geekflare.com/ai-assets/deepseek-api-keys-page.png)

* Give your API Key a name (e.g., "Geekflare AI Integration") and then click ‘Create API Key’.

![DeepSeek](https://cdn.geekflare.com/ai-assets/deepseek-create-new-key.png)

* Your API key is created. Save the key securely for your use.

![DeepSeek](https://cdn.geekflare.com/ai-assets/deepseek-key-ready.png)

**Video Tutorial**

<iframe />

## Grok API Key

* Go to the [Grok API platform](https://x.ai/api) and  login or sign up if you don't have an account, yet.
* Click API → API Console login
* If you are a first time user, you will need to buy some credits. For this, click ‘purchase’ and complete the payment
* After purchasing credits, click the ‘API keys’ from the left menu and ‘Create API key’. Give a name to your key and the ‘Create API Key’ button.

![Grok](https://cdn.geekflare.com/ai-assets/grok-create-api-key.png)

* Your API key will be generated. Save your key securely as it cannot be retrieved in future from the Grok API portal.

![Grok](https://cdn.geekflare.com/ai-assets/grok-key-ready.png)

## Mistral API Key

* Visit the [Mistral AI Console page](https://console.mistral.ai/) and sign up/log in.
* Click ‘API Keys’

![Grok](https://cdn.geekflare.com/ai-assets/mistral-api-key.png)

* Click ‘Create a new Key’

![Grok](https://cdn.geekflare.com/ai-assets/mistral-create-new-key.png)

* Give a Key Name and an Expiration date if required

![Grok](https://cdn.geekflare.com/ai-assets/mistral-key-expiry.png)

* Copy the Key and save it securely for future use.

## Perplexity Sonar API Key

* Visit the [Perplexity API Platform](https://www.perplexity.ai/api-platform) and sign up/login by clicking ‘Get Started’.
* Select ‘API Key Management’ from the left side menu.
* First click ‘Create an API group’.

![Sonar](https://cdn.geekflare.com/ai-assets/sonar-api-group.png)

* Give your Group Name, description, and your billing address
* Scroll down the page and click ‘Generate API Keys’

![Sonar](https://cdn.geekflare.com/ai-assets/sonar-generate-api-key.png)

## Don’t See a Model You Need?

If your team relies on a model that isn’t listed here, please [contact our support team](https://ai.geekflare.com/c/help) to submit a request. We are always evaluating new models to add to the Geekflare AI suite.


# Search API
Source: https://docs.geekflare.com/ai/connect/getting-search-api-keys



## What is Search API?

Search API feature in Geekflare Connect empowers AI models to fetch fresh, real-time information directly from the web when generating responses. This means your AI can provide answers based on the most current data available, rather than being limited to its static training knowledge.

Instead of relying solely on the model's internal knowledge base, the Search API enables the system to send a query to an external search service. The retrieved information is then used to enhance the final answer provided by the Large Language Model (LLM).

## Why Search API is Required

LLMs are powerful, but their responses are limited by their training data's cutoff date. This means they cannot automatically access or browse the live internet. Even when you connect your own API keys from providers like OpenAI, Anthropic, or Google via our BYOK model, the underlying AI models themselves do not gain internet access. Their knowledge base is static, stopping at whatever date they were last trained on.

This creates gaps when you need information that is recent like:

### News & Events

* Breaking stories
* Policy updates
* Weather alerts
* Election results
* Major company announcements

### Business & Market Research

* Latest financial filings
* Quarterly earnings
* New product launches
* Competitor movements
* Changes in pricing or plans

### Travel & Logistics

* Flight delays
* Airport rules
* Visa requirements
* Local transportation changes
* Hotel availability

### Regulations & Compliance

* Tax rule updates
* New compliance guidelines
* Security advisories
* Government notifications

### Consumer Information

* Updated reviews
* Product recalls
* Store timings
* Restaurant menus
* Local service availability

### Education & Careers

* University admission dates
* Revised exam patterns
* Recruitment announcements
* Application deadlines

### Health & Public Safety

* Disease outbreak updates
* Changes in medical guidelines
* Local hospital availability
* Drug recall notices

By enabling the Search API, you ensure your AI models deliver real-time relevant responses.

## How to add search API Keys?

You can add search API keys by going to Settings >> API Keys >> Add New Key.

![Geekflare AI](https://cdn.geekflare.com/ai-assets/geekflare-add-search.png)

## How to get search API Keys?

Geekflare Connect supports multiple search APIs like Parallel, Exa and Firecrawl.

### 1. Parallel Search

A general-purpose search provider ideal for broad, multipage results. It returns ranked web pages, summaries, and snippets. It is suitable for research, comparisons, and fact-checking.

* To get an API key, visit the [Parallel Platform](https://platform.parallel.ai/home), login or sign up.  Then click ‘Settings’.
* Here, click the API keys tab → Create New Key

![Parallel](https://cdn.geekflare.com/ai-assets/parallel-api-keys.png)

Give the key a name, and then click Create New API Key,

![Parallel](https://cdn.geekflare.com/ai-assets/parallel-create-new-key.png)

Your new search API key is created. Click the view icon to copy your API Key and paste it into Geekflare Connect’s API key field.

![Parallel](https://cdn.geekflare.com/ai-assets/parallel-key-ready.png)

### **2. Exa Search**

A developer-friendly search engine known for structured outputs. It tends to return cleaner metadata and more precise links, which helps when you want high-quality references or programmatic analysis.

* Visit the [Exa Search API](https://exa.ai/exa-api) website and sign up.
* Click ‘API Keys’ from the left side menu.

<img alt="exa-api-keys.png" />

* Click the ‘Create Key’, give your key a name and then click ‘Create Key’.

<img alt="exa-create-api.png" />

* Your key will be displayed. Copy this key and paste it in the Geekflare API keys field.

<img alt="exa-api-ready.png" />

### **3. Firecrawl**

A web crawler–based API that focuses on scraping page content. It’s useful when you need deeper content extraction from websites, for research etc.

* To get a Firecrawl API, go to the [Firecrawl website](https://www.firecrawl.dev/) and sign up/log in.
* Click ‘API Keys’

<img alt="firecrawl-api-key.png" />

* Click ‘Create’. Then give your key a name and get your Firecrawl Search API key.

<img alt="firecrawl-create-key.png" />

Please note that you will also need to purchase credits to use this API.


# Quick Start Guide
Source: https://docs.geekflare.com/ai/connect/getting-started



Welcome to Geekflare Connect, the Bring Your Own Key (BYOK) platform that unifies your team's access to the world's best AI models. This guide will walk you through the essential steps to connect your existing AI provider keys, set up your workspace, and start collaborating.

In less than 5 minutes, you and your team will be able to chat with your favorite AI models using your own API keys, all from a single interface.

## Step 1: Sign Up & Log In

This is your entry point to the Geekflare AI ecosystem.

1. **Create Your Account** by visiting the [Geekflare AI](https://geekflare.com/ai/) and clicking the **Get Started Free** button. You can also go directly to the [signup page here](https://ai.geekflare.com/c/auth/register).

   ![Geekflare AI homepage](https://cdn.geekflare.com/ai-assets/geekflare-ai-home.png)

2. **Choose Your Sign-Up Method** you can sign up instantly using your Google Account or with your email address and a password.

   ![Account Creation](https://cdn.geekflare.com/ai-assets/geekflare-ai-create-account.png)

3. **Verify Your Email (If Needed)**
   If you use your email address to sign up, we will send a verification link to your inbox. You must click this link to confirm your account.

   > **Note:** Didn't receive the email? Please check your spam or junk folder.

Once this process is completed, you can log in to Geekflare AI.

## Step 2: Set Up Your Workspace

After logging in for the first time, you'll complete a quick, one-time setup to configure your account for either team or individual use.

![Onboarding Screen](https://cdn.geekflare.com/ai-assets/geekflare-connect-onboarding.png)

Based on your needs, choose one of the three options available.

#### For Business or Team Use

This is the recommended path for companies and teams who want to collaborate.

1. Select **Business / Teams**.

2. On the next screen, you will be prompted to set up your organization and your first workspace.

   * **Organization Name:** This is the top-level account for your company (e.g., "Acme Inc."). It will contain all your users, workspaces, and billing information.
   * **Workspace Name:** Workspaces are used to organize chats and prompts by project, team, or topic (e.g., "Marketing Team" or "HR Team").

   ![Org Setup](https://cdn.geekflare.com/ai-assets/geekflare-connect-workspace-creation.png)

3. Fill in both fields and click **Continue**. You will then proceed to the API keys page.

#### For Personal Use

If you are a single user, this is the quickest way to get started.

1. Select **Personal**.
2. You will skip the organization setup and be taken directly to the next step: connecting your API keys. A default workspace will be created for you automatically.

#### Joining an Existing Organization

If you have been invited to Geekflare AI by a colleague:

1. Select **Join an organization**.
2. You will see a list of pending invitations. Simply accept to be added to your team's workspace, and you can get started immediately.

## Step 3: Connect Your AI Provider Keys

This is the final and most important step of the setup process. Connecting an API key from a provider like OpenAI, Google Gemini or Anthropic is what enables the AI chat functionality in Geekflare Connect.

> 💡 Why BYOK? Connecting your own keys gives you full control over your AI spending, access to your fine-tuned models, and ensures you can leverage any pre-existing deals you have with AI providers.

![Adding API Keys](https://cdn.geekflare.com/ai-assets/connect-add-api-keys.png)

#### To Add a Key

1. **Click on a Provider:** Select the AI provider you want to connect (e.g., "OpenAI").
2. **Paste Your Key:** A dialog box will appear. Paste your secret API key from that provider into the field.
3. **Save and Continue:** Click the **Save** button. The provider will now be active.
4. Once you've added at least one key, click the **Continue** button at the bottom of the screen.

> **Where do I find my API key?**
> You must generate an API key from your account on the respective AI provider's website. For example, for OpenAI, you would log in to [`platform.openai.com/api-keys`](https://platform.openai.com/api-keys).

##### Don't Have Your Keys Ready?

No problem. You can skip this for now by clicking **I'll do this later**. You can add your keys at any time from the main dashboard by navigating to **Settings → API Keys**. Please note that you will not be able to start a chat until at least one key is added.

### You're All Set!

Once you click **Continue**, you'll see a success screen confirming that your workspace is ready.

![Onboarding Success](https://cdn.geekflare.com/ai-assets/connect-onboarding-success.png)

Click **Go to my workspace** to enter the main chat interface. Now you can select your favorite model from the dropdown menu and start your first conversation!

![Chat Interface](https://cdn.geekflare.com/ai-assets/connect-chat-interface.png)

Congratulations 🥳 on completing the setup! You've successfully configured your Geekflare Connect workspace.


# Supported AI Models
Source: https://docs.geekflare.com/ai/connect/supported-ai-models

Supported AI models in Geekflare Connect, BYOK AI Workspace.

[Geekflare Connect](http://geekflare.com/ai/connect/) is a Bring Your Own Key (BYOK) platform providing access to over 35 LLMs from the world’s leading providers. Unlike the all-in-one [Geekflare Chat](http://geekflare.com/ai/chat/) subscription, Connect allows you to use your own API keys for direct billing and control.

This list is continually updated as new models are released. If you don't see a model you need, please let us know!

## OpenAI

OpenAI is renowned for its powerful and versatile GPT (Generative Pre-trained Transformer) models, setting the industry standard for complex reasoning, instruction following, and natural language generation.

| **Model Name**        | **Best for**                                                                                                                                                                                             |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GPT 5.4 Pro           | Higher reasoning and accuracy for complex, demanding tasks.                                                                                                                                              |
| GPT 5.4               | General purpose, versatile model that can handle software development, writing, reasoning and conversations.                                                                                             |
| GPT 5.3 Instant       | Optimized for everyday conversations, more contextualized web search results and directly helpful answers with fewer disclaimers.                                                                        |
| GPT 5.2 Codex         | An optimized model for long-horizon agentic coding, featuring context compaction and improved Windows support. It excels at complex refactors and high-efficiency tasks.                                 |
| GPT 5.2               | Reasoning and high speed. Useful for coding and agentic tasks.                                                                                                                                           |
| GPT 5.2 Chat          | General conversations and every day tasks. The same as the one used in ChatGPT 5.2.                                                                                                                      |
| GPT 5.2 Pro           | High intelligence, deep reasoning and precise responses.                                                                                                                                                 |
| GPT 5.1 Instant       | Fast, enhanced GPT-5 model for everyday tasks and quick interactions.                                                                                                                                    |
| GPT 5.1 Thinking      | Flagship OpenAI GPT-5 model optimized for deep reasoning and adaptive task performance.                                                                                                                  |
| GPT 5.1 Codex         | Advanced GPT-5.1 coding model optimized for high-accuracy software generation, debugging, and complex code reasoning.                                                                                    |
| GPT 5.1 Codex Mini    | Lightweight, fast GPT-5.1 coding model designed for quick code tasks with low latency.                                                                                                                   |
| GPT 5                 | Predecessor of GPT 5.1, suited for coding and complex reasoning.                                                                                                                                         |
| GPT 5 Pro             | Premium GPT-5 model offering enhanced reasoning, depth, and task reliability for professional-grade tasks.                                                                                               |
| GPT 5 Chat            | Chat-optimized version of GPT 5 model used within ChatGPT. Used for general-purpose tasks like brainstorming, problem-solving etc.                                                                       |
| GPT 5 mini            | Balanced model for everyday tasks. This is cheaper than GPT-5 but retains strong reasoning, like drafting blog posts, summarizing, creating simple code snippets, etc.                                   |
| GPT 5 nano            | Lightweight, cheap GPT 5 model for simple and high-volume tasks like data cleaning, bulk text generation.                                                                                                |
| GPT 4.1               | This non-reasoning model is suited for general tasks that don’t require much analysis, like drafting professional emails and social media posts.                                                         |
| GPT 4.1 mini          | This is a lighter version of 4.1 that gives quick responses. Suited for chatbots and customer support replies.                                                                                           |
| GPT 4.1 nano          | This is an even lighter and quicker version of 4.1 with a lesser knowledge base. It’s suited for simple tasks like data cleaning, correcting punctuation and grammar, and simple Q\&A, like definitions. |
| GPT 4o                | Flexible multimodal model for real-time text, vision, and audio tasks.                                                                                                                                   |
| GPT 4o mini           | Fast multimodal model for simple image Q\&A, basic chat.                                                                                                                                                 |
| o4 mini               | Affordable reasoning model for coding and visual tasks. Predecessor of GPT 5 mini.                                                                                                                       |
| o4 mini Deep Research | Affordable deep research model for multi-step research, ability access data from the internet as well as your own data through MCP connectors.                                                           |
| o3                    | Predecessor to GPT 5 for complex reasoning tasks in math, science, coding, and visual.                                                                                                                   |
| o3 Deep Research      | Analyze hundreds of sources into a rich report with citations, creating long-form content from extensive online research.                                                                                |
| o3 mini               | Cost-efficient model for STEM and coding-based tasks.                                                                                                                                                    |

## Google Gemini

Google's Gemini family of models is built from the ground up to be multimodal, excelling at processing and reasoning across text, images, code, and video.

| **Model Name**         | **Best for**                                                                                                                                                       |   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - |
| Gemini 3.1 Flash Lite  | Fast, cost-efficient model optimized for high volume tasks like classification, translation etc.                                                                   |   |
| Gemini 3.1 Pro         | Improved token efficiency, optimized for software engineering and agentic tasks.                                                                                   |   |
| Gemini 3 Flash         | Improved reasoning and intelligence at lower and cost and higher speed.                                                                                            |   |
| Gemini 3 Pro           | Flagship model of Gemini with configurable thinking levels to balance complex reasoning and speed.                                                                 |   |
| Gemini 3 Pro Image     | Google Nano Banana Pro generates 4K images with superior speed and contextual understanding.                                                                       |   |
| Gemini 2.5 Pro         | High performance with enhanced thinking, multimodal understanding, processing large datasets, mathematical problem solving, and complex coding.                    |   |
| Gemini 2.5 Flash       | Balanced model for everyday usage, high-volume tasks with thinking capabilities. Good for virtual assistants, real-time summarization, and customer-facing agents. |   |
| Gemini 2.5 Flash Image | Nano Banana is Google code name for Gemini 2.5 Flash Image, a specialized model for natural language photo generation.                                             |   |
| Gemini 2.5 Flash Lite  | Cost efficient, lightweight model for quick response. Good for summarizing, and processing large datasets.                                                         |   |
| Gemini 2.0 Flash       | Older model, suited for daily simple tasks not requiring advanced thinking, like basic chat and light content generation.                                          |   |

## Anthropic

Anthropic Claude models offers top-tier performance with a strong reasoning and coding.

| **Model Name**    | **Best for**                                                                                                |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| Claude Sonnet 4.6 | Balanced model for cost, speed and intelligence with a 1M context window.                                   |
| Claude Opus 4.6   | High intelligence for coding and building agents with a 1M context window.                                  |
| Claude Opus 4.5   | Premium coding model to give maximum intelligence with improved performance.                                |
| Claude Opus 4.1   | Superior performance, complex reasoning, advanced coding, and agentic tasks.                                |
| Claude Opus 4     | Sustained performance on long-running tasks, coding, and agent workflows.                                   |
| Claude Sonnet 4.5 | Latest model with highest intelligence, exceptional agent and coding capabilities                           |
| Claude Sonnet 4   | Hybrid reasoning model for high-volume uses like customer-facing chat agents, and visual data extraction    |
| Claude Haiku 4.5  | High performance & fast at one-third the cost and twice as fast as Sonnet 4.                                |
| Claude 3.5 Haiku  | Fast performance, code completion, customer service chatbots, data extraction, real-time content moderation |

## Mistral AI

Mistral AI is an efficient language model that offer competitive performance with a focus on developer-friendliness and customization.

| **Model**         | **Best for**                                                               |
| ----------------- | -------------------------------------------------------------------------- |
| Mistral Medium    | High performance at lower cost for enterprise knowledge base and workflows |
| Mistral Codestral | AI-powered software development for enterprises                            |

## Perplexity

Perplexity models are designed as "answer engines," excelling at providing accurate, real-time, and cited information by integrating web search capabilities directly into the language model.

| **Model**           | **Best for**                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Sonar               | Lightweight model for quick responses, general queries.                                                                   |
| Sonar Pro           | Advanced search, complex queries, follow-ups.                                                                             |
| Sonar Reasoning     | Fast reasoning model for problem-solving, powered by search.                                                              |
| Sonar Deep Research | Conducting exhaustive web search, processing multiple information sources and generating detailed reports with citations. |

## xAI Grok

Grok is developed by xAI with the goal of creating AI that can understand the universe. It is known for its real-time knowledge of the world via the 𝕏 (formerly Twitter) platform and its unique, rebellious personality.

| **Model**                   | **Best for**                                                                                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Grok 4.1 Fast Reasoning     | Lower cost reasoning model. Ability to give better emotional and creative responses without compromising on speed.                                               |
| Grok 4.1 Fast non-reasoning | Low cost model for every day tasks like summarizing, high-volume tasks and chatbots.                                                                             |
| Grok 4                      | Flagship model of xAI—high performance in math, reasoning, and natural language. Good for technical research, coding, document/image/voice processing            |
| Grok 4 Fast                 | Cost-efficient quick response model with limited reasoning abilities. Suited for high-volume chatbots, summarizing. Succeeded by Grok 4.1 Fast non-reasoning.    |
| Grok 4 Fast Reasoning       | Cost-efficient reasoning model. Suitable for mathematical deductions, multistep logical inferences. Succeeded by Grok 4.1 Fast reasoning                         |
| Grok 3                      | Non-reasoning model suitable for data extraction, text summarization and coding. Possesses extensive domain knowledge in healthcare, finance, law etc.           |
| Grok 3 Mini                 | Lightweight reasoning model for tasks where deep domain knowledge is not required. Best for document summarization, mathematical reasoning and logic based tasks |

## DeepSeek

DeepSeek AI focuses on developing strong models, particularly in the domains of code and mathematics. Their models are an good choice for technical and programming-related tasks.

| **Model**         | **Best for**                                                                                                            |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------- |
| DeepSeek Chat     | General-Purpose, non-thinking model for conversations, everyday tasks, coding, summarization, and creative writing.     |
| DeepSeek Reasoner | Reasoning model for complex, step-by-step logical reasoning for math problems, scientific reasoning, and code debugging |

### Don't See a Model You Need?

If your team relies on a model that isn't listed here, please [contact our support team](https://ai.geekflare.com/c/help) to submit a request. We are always evaluating new models to add to the Geekflare AI suite.


# Chat Interface
Source: https://docs.geekflare.com/ai/features/chat-interface

Familiarize yourself with Geekflare AI advanced chat interface.

## Chat Layout Overview

The Chat Interface is where you interact with AI models, manage prompts, compare results across models, upload files, and organize or share conversations.

<img alt="Chatinterfacemain Pn" />

The main elements include:

### **Model Selector**

Choose the AI model you want to interact with. You can switch model at any time without losing context.

<img alt="Modelselector PN" />

### **Chat Input Box**

Type prompts, upload files, and send instructions from the input area at the bottom of the screen.

<img alt="Messageinputbox Pn" />

### Attachments

Upload PDF or image files (up to 50MB). Uploaded files appear inside your chat history and count as part of the conversation.

<img alt="Attachmentsbutton Pn" />

### **Chat Settings**

Located at the bottom of the message input box.

<img alt="Chatsettings Pn" />

Includes:

* Model parameters like temperature (higher temperature means more creative)
* Context window size (memory retention)
* System instructions for the current chat (anything specific you wish the LLM to remember)

<img alt="Modelsettings Pn" />

### Chat Search

The Chat Search feature allows you to locate any conversation within your current workspace or project. It saves time when you have a large number of chat threads and need to jump back to a specific discussion.

The search bar appears at the top of the chat sidebar, labeled **“Search chats”**.

<img alt="Chatsearchfeature Pn" />

**How Chat Search Works**

* Start typing a keyword in the Search chats bar.
* Results appear instantly and filter down the visible chat list.
* Search matches against chat titles and keywords within each conversation thread.

<img alt="Chatsearchfeatureworking Pn" />

### Chat History

The chat history in the left sidebar shows all chats in the current workspace or project.

You can rename, move to project, delete, or share conversation threads from here.

<img alt="Chathistorysidebar Pn" />

### **Projects**

Allows you organize related chats into projects, have its own specific instruction - like a context based on client, campaign etc. Read more about [Projects](/ai/features/projects).

<img alt="Projectsfeature Pn" />

### **Workspace Indicator**

Visible on the top right; shows your current organization and workspace and lets you switch between them.

<img alt="Workspaceindicator Pn" />

### **Stop Button**

During response generation, a **Stop** button appears in the prompt box.

<img alt="Stopbutton Pn" />

Clicking it immediately stops the model’s response. This is useful when:

* The model starts going off-track
* You want to refine or correct the prompt
* You only needed a partial answer

## Switching Models During Chat

You can change the model at any point in the same conversation thread without starting a new thread. Switching models:

* Does not reset context
* Continues the same conversation with all previous messages included

Switching is simple. Just go to the model selector and choose another model before sending the next prompt on the same thread.

## Multi-Model Chat

Geekflare AI supports multi model AI chat:

### **Parallel Responses (Multi-Model Chat)**

In Geekflare Chat, you can send the same prompt to **up to five models simultaneously** and view their outputs side-by-side.

Toggle the multi-model chat, select upto 5 models from the model selector and enter your prompt.

<img alt="Parallelresponses Pn" />

You can comppare the responses side-by-side.

<img alt="Parallelresponsessidebyside Pn" />

### **Manual Switching**

You can switch the model and click the ‘regenerate’ option within the same thread to compare how models handle context differently.

As shown below, I have asked Gemini a question and got a response.

<img alt="Manualswitching Pn" />

Now I switch the model and ask GPT 5.1 Instant the same question.

<img alt="Manualswitching2 Pn" />

You can view both the responses.

<img alt="Viewingbothresponses Pn" />

## Sharing Chats

Chats can be shared in multiple ways depending on your plan. To share, click the 3 dots next to your conversation thread name and select ‘share conversation’.

<img alt="Sharingconversations Pn" />

You are presented with 3 options.

<img alt="Sharingconversationoptions Pn" title="Sharingconversationoptions Pn" />

1. **Anyone with the link**: Generate a publicly viewable link accessible to anyone. This option is available in all plans.
2. **Share with Organization members:** Make the chat viewable by everyone in the org (Business plan and above).
3. **Share with Specific People:** Invite specific members by entering their email address (Business plan and above).

For options 2 and 3, the shared conversation will be visible to the other members under ‘shared with me’.

<img alt="Sharedwithme Pn" title="Sharedwithme Pn" />

### Permissions

* All shared chats are view-only
* To continue or modify the chat, the viewer must **fork** it and create their own copy
* Shared chats cannot be edited directly

### Creating a Publicly Shareable Chat Link

When you share a conversation by selecting a ‘anyone with the link’, you get a publicly shared link. You can choose stop sharing the thread when you wish.

<img alt="Sharingpubliclink Pn" />

### How to ‘Fork’ from a Shared Chat Link?

If you receive a shared chat thread or are invited to view a publicly shared link, open the thread and select the ‘fork’ option. Select the workspace into which you would like to fork this conversation to and continue chatting as usual.

<img alt="Forkingfromsharedconversation Pn" />

## How to perform web search?

Select ‘tools’ and turn on the web search option below the prompt box. When you type in a prompt with this feature turned on, you will receive web search results in the response. Use this feature when you need recent data and don’t want to be limited by the model’s training cutoff date.

<img alt="Websearchresults PN" />

You can click ‘view all’ to view all the pages on the right side.

<img alt="Websearchresultsviewall PN" />

## How to perform Deep Research?

Use Deep Research models offered on Geekflare AI. Currently the Deep Research models offered are: OpenAI's o3-Deep Research, o4 mini Deep Research and Perplexity's Sonar Deep Research.

The Deep Research Settings option will be visible below the prompt box when you select a Deep Reasearch model.

### Deep Research with OpenAI

In the case of OpenAI models, you have the option to filter domains in your result, that is a list of domains from which you want the research to be performed.

<img alt="Open A Ideepresearchsettings PN" />

### Deep Research with Perplexity Sonar

In the case of Perplexity, you have multiple settings.

**Core settings:** Search Mode, Disable web search, enable search classifier, reasoning effort, and whether to include images and related questions in the result.

**Search filters:** Recency, thoroughness, user location, data filters and domain filters.

<img alt="Perplexitysonardeepresearchsettings PN" />

Perplexity also offers advanced settings for deep research.

**Temperature:** Lower value gives more stable and consistent responses, while higher values give more creative and varied responses.

**Top P:** This refers to the range of selection of the 'next word'. A lower number results in consistent results and higher number results in creative and unusual results. The latter is good for brainstorming. Top P and Temperature go hand-in-hand.

**Top K:** It refers to how many next words should the model think about. A low number indicates limited and more likely options. A higher number indicates a larger pool of choices.

<img alt="Perplexitysonardeepresearchadvancedsettings PN" title="Perplexitysonardeepresearchadvancedsettings PN" />

**Presence penalty:** This tells the model not to repeat the same topic. If you set a lower value, you may find the model talking about the same thing repetitively. If you set a higher value, the model will introduce new topics.

**Frequency penalty:** This tells the model not to repeat the same words. A lower value results in the model repeating the same words and a higher model results in the model using a wider range of vocabulary.

**Max Tokens:** This limits the model's maximum number of tokens used for responding. You can set it to 'auto' (let the model decide) or specify the number of tokens. Please note that if the Max Tokens is set at a very low value, the response may be terminated prematurely.

## How to Create Mermaid Diagrams

Type your prompt and ask the model to output a Mermaid diagram code block.

Example:

```html theme={null}
Create a mermaid diagram showing steps in a simple email drip campaign.
```

<img alt="Mermaid1 PN" />

You can directly view the mermaid diagram on Geekflare AI. You can also copy/paste the Mermaid code wherever needed and paste them into tools that support diagram rendering.

<img alt="Emaildripcampaign PN" title="Emaildripcampaign PN" />


# Organization
Source: https://docs.geekflare.com/ai/features/organization

Learn about Organization in Geekflare AI.

## What is an Organization?

The Organization is the highest-level structure in Geekflare AI. It defines how your team is grouped, how access is managed, and which resources and settings are shared across members. Every account can belong to multiple organizations, and each organization can contain one or more workspaces depending on the subscription plan.

An organization represents a team, company, or individual setup inside Geekflare. Within an organization, users can collaborate, share access to AI models through API keys, manage workspaces, and control permissions.

## Organization Structure

1. A single user account can belong to multiple organizations.

   For example, you may be the Owner of your personal organization while also being a Member or Admin in a client’s or employer’s organization.
2. Each organization can have multiple workspaces (Business plan and above).

   Pro plan: 1 workspace

   Business and higher: Unlimited workspaces
3. Workspaces belong to an organization and inherit its members, roles, and visibility rules.

## Roles and Permissions

Geekflare currently supports **three organization-level roles**:

* Owner (1 per Org)
* Admin (Multiple per Org)
* Member (Multiple per Org)

The owner is the person who creates the Organization. They have the highest level of authority. They manage billing, subscription, can delete the organization, and can transfer ownership. Has all the powers of an Admin. The owner has access to all the Workspaces.

The admin can invite/manage users, create/delete workspaces, and manage the shared, organization-level API keys. The admin also has access to all the Workspaces.

A member is a standard user. They can be assigned to workspaces and can use the tools within them. They have no management permissions at the organization level. They can view members in their organization, but can't invite or remove members or manage API keys.

## What is the Default Organization?

When a new user signs up for Geekflare AI as an individual (For personal use), the platform automatically creates a default organization for them. This organization is linked to their personal account and gives them full control as the Owner.

<img alt="Continueasindividual PN" />

The default organization acts as a private workspace environment where users can start using Geekflare Connect immediately, without needing to set up a team, invite members, or configure shared access.

## How to create an Organization for your Business?

After you sign up with Geekflare AI and verify your email, you will be able to create an Organization by selecting the ‘For Business/Teams’ option.

<img alt="Createanorg PN" />

After you sign up with Geekflare AI and verify your email, you will be able to create an Organization by selecting the ‘For Business/Teams’ option.

You can enter your organization name, a custom URL for your organization and your first workspace.

<img alt="Organization Creation Small PN" />

## How to Switch Between Organizations?

Click the Geekflare Logo on top left to view a list of the organizations (including personal) you are part of, along with your role within that organization. You can click the organization you wish to enter.

<img alt="Orgselectionsmall PN" />

## How to View Members in an Organization?

Click the members icon on the left side to view all the members in your organization, their roles and the workspaces they are part of.

<img alt="org members.PNG" />


# Projects
Source: https://docs.geekflare.com/ai/features/projects

Create projects to organize your conversations and collaborate with your team.

## Understanding Projects

A **Project** is a dedicated container within your Workspace that holds a collection of chats and shared AI context. It allows you to segment your work by client, product, or internal initiative.

Projects make it easy to:

* Keep client work or distinct topics completely isolated.
* Apply project-level instructions (such as brand voice or coding guidelines) that automatically apply to every chat in the project.
* Switch between different workstreams without losing your mental place.
* Invite teammates to work on shared initiatives within the project.

<Note> Projects exist at the workspace level. </Note>

<img alt="Projectsfeaturedoc Pn" />

## How to Create a Project

You can create projects within a Workspace to segment your work.

1. Navigate to the Workspace where you want to add the project.
2. In the sidebar, locate the **Projects** section.
3. Click Create Project (the + icon).
   <img alt="Creatingaproject Pn" />
4. Configure your Project:

   Name: Give your project a clear title.

   Description: Briefly explain the project's goal.

   Instructions (Context): Optional. Define specific rules or persona guidelines the AI should follow for all chats in this project.

<img alt="Addingprojectinstructions Pn" />

5. Click `Create Project`.

Once created, your project will appear in the sidebar, ready for you to start conversations.

## What are Project Instructions?

Project Instructions serve as a shared brain for every conversation within a project. They act as a set of guidelines that are automatically applied to all new chats in that specific project.

Project Instructions are a block of context or guidelines that will be applied to chats inside that project.

You can use Instructions to define:

* Client background, company history, or product details.
* Brand guidelines (e.g., "Professional," "Witty," "Academic").
* Style preferences and terminology.
* Specific restrictions or topics to avoid ("Negative constraints").

Project Instruction feature ensures consistency. Instead of repeating `Act as a senior marketer` in every single chat, you set it once at the project level.

<Note> Instructions are scoped to the Project only and do not affect other projects in the Workspace. </Note>

## Switching Between Projects

When you switch projects:

* Project Instructions (if any) automatically become active
* The model uses the correct context for prompts inside that project

To switch:

1. Use the Project selector in the sidebar.
2. Choose a different project inside the same workspace.

As you can see below, presently I am inside the Interview Calls project. To switch to ‘Onboarding new employees’ project, I just have to click the > beside that project.

<img alt="Switchingtoaproject Pn" />

## Renaming a Project

Click the 3 dots beside a project name. Select 'Edit Project', change the name of the project to its new name and save the changes.

<img alt="Rename Project PN" />

## Projects Sharing & Permissions

Projects in Geekflare AI feature granular access control, allowing you to control exactly who can view or collaborate on your chats.

Every project has three visibility settings:

### **1. Private (Default)**

* Only you (the creator) can access the project.
* Invisible to other workspace members.

### **2. Workspace Access**

* All members of the current workspace can access the project.
* Permissions can vary between view or edit depending on the configuration.

### **3. Specific Members**

* Restricted access for selected individuals.
* Invite members by name or email.

When adding specific members, you can assign them a role:

* **View**: Can read chats and project instructions, but cannot post messages or make changes.
* **Edit**: Can generate new messages, create chats, rename items, and modify project settings.

### **What happens when you share a project**

* All chats inside the project become visible to users who have access.
* Members with **Edit** can contribute to the same threads.
* Members with **View** can view everything but cannot modify chats.
* Sharing changes apply to the entire project, not just specific chats.

## Managing Multiple Clients Using Projects

Projects are ideal for consultants, or teams handling multiple client engagements.

Example structure:

* *Workspace: Client Work*
  * Project: Client A – SEO
  * Project: Client A – Product Pages
  * Project: Client B – LinkedIn Content
  * Project: Client C – Documentation

Benefits:

* Clear separation between clients
* No risk of mixing client context
* Each project can have its own tone, style, and instructions
* Shared team access within the workspace
* All related chats grouped neatly

This also works for internal workflows, such as:

* *Workspace: Marketing Team*
  * Project: Blog Content
  * Project: Social Media
  * Project: Product Launch
  * Project: Docs & Guides

### Multi-User Chat on the Same Thread

When a project is shared with **Edit** permissions, multiple members can work together inside the same chat thread in real time.

This is useful for teams who want to co-create content, review outputs together, or use the same thread for brainstorming, documentation, or client-specific work.

It’s like collaborating with your team, with an LLM as another team member! The model can answer to everyone’s questions.

Below, you can see 2 team members having a chat on the same thread with Gemini.

<img alt="Multipleusersonthesamechatthreadinprojects Pn" />


# Prompt Library
Source: https://docs.geekflare.com/ai/features/prompt-library

Ready-to-use prompts or create your own.

## What is a Prompt?

A prompt is the specific instruction you give the AI to guide its behavior. The quality of the output depends heavily on the clarity of the prompt. Well-structured prompts ensure the AI understands your intent and eliminates ambiguity.

Repetitive tasks shouldn't require repetitive typing. Instead of rewriting instructions or copying them from external notes, the **Prompt Library** allows you to save your prompts. This ensures consistency across your team.

### Core Features

The Prompt Library is ready to use from individual use to team-wide collaboration.

* Jumpstart with our curated library of **over 275 expert prompts**. Covering categories like Marketing, Human Resources, SEO, and Project Managament, these pre-built templates help you get high-quality results without needing to craft instructions from scratch.
* Create your own reusable prompts to your specific needs.
* Make your prompts flexible by adding `variables` within the instructions.

<Tip> When you select a prompt with variables, Chat Interface will ask you to fill in the specific details (e.g., \[Topic], \[Tone]) before inserting the final text into the chat. This allows you to use the same structure for infinite variations. </Tip>

* Standardize your team's output by sharing your best prompts.

  * **Workspace Sharing**: Make prompts available to your team members within the workspace.
  * **Organization-Wide**: Publish prompts to the entire organization to ensure consistency across all departments.

## How can you access the Prompt Library?

The prompt library can be accessed by clicking the `Prompts` icon in the chat input box.

<img alt="Accessingthepromptlibrary PN" />

## Using Geekflare’s Readymade Prompts

In our ready-to-use prompt library, we have covered most of the common business functions like HR, Finance, Sales, Marketing, Customer Support and more.

<img alt="Prompt Library Pn" />

Just select the prompt you want to use, fill in your company-specific variables, and select your preferred model to respond. It’s that simple.

Let’s look at an example. Suppose you are a sales executive, trying to build a cold email sequence. Select `Sales` from the menu on the left and `multichannel cold outreach sequence builder` prompt from the library and click `Use`.

<img alt="Promptlibrarysales Pn" />

You will be prompted to fill in these variables.

<img alt="Customizelibrarypromptfillinvariables Pn" title="Customizelibrarypromptfillinvariables Pn" />

In the above form,

* **Offer** is what you are selling (say an AI meeting transcription tool)
* **ICP** is the ‘ideal customer profile’ (HR managers at Fortune 500 companies)
* **Trigger events** are the reason the prospect may consider purchasing your product (improving productivity through AI adoption)
* **Region** is the geographical location of your prospect. (US, APAC, Europe etc)

Fill in the above details and click the ‘Use prompt’ button.

<img alt="Promptwithvariablesfilled Pn" title="Promptwithvariablesfilled Pn" />

The prompt gets filled into the prompt box. Then choose your preferred model from the drop down and click Go.

<img alt="Modelselectionforlibrarypromptuse Pn" />

You get a complete campaign strategy with multiple versions of email, LinkedIn DMs, Voicemail scripts and success metrics. You can check the full response on this [shared chat thread](https://ai.geekflare.com/c/share/h973j96utljng1o82gt1p7ypyzrxurm0).

## Creating Custom Prompts

For use cases that are unique to your organization, you have the option to create your prompts in the prompt library. You can share these prompts with your team or across the organization.

Go to the prompt library and click the `Create Prompt` button on the left.

<img alt="Creatingcustomprompt Pn" />

Give a prompt title, category and the prompt content.

<img alt="Fillingincustomprompt Pn" title="Fillingincustomprompt Pn" />

You may give custom variables, if any inside square brackets, like this - **\[company name].**

You can choose to keep your prompt private, share with the entire organization or your workspace. Click the ‘Create Prompt’.

Your prompt gets added to your custom prompts tab, from where you can use it when required.

<img alt="Custompromptvisibleinthelibrary Pn" />

Use the prompt, fill in custom variables, if any, and click go.

Your custom prompts and sharing options can be modified as required from the custom prompts tab in the Prompts Library.

## Editing Prompt Instructions

You can make changes to your saved custom prompts.

1. Open the Prompt Library and go to the Custom Prompts tab.
2. Select the prompt you wish to update.
3. Click **Edit Prompt**.
4. Modify the instructions or field structure.
5. Save your changes.

<img alt="Editingpromptinstructions Pn" />

## Best Practices for Prompt Design

To create reliable and reusable prompts:

* Keep instructions clear and specific.
* Use custom variable fields for details that change between clients or tasks.
* Break complex tasks into steps. Use 'chain-of -thought' technique
* Use a model that's best for your task (reasoning/content generation/coding etc)
* Specify tone, format, or constraints only when needed.
* Test the prompt with different models to ensure consistent results.
* Refine prompts based on team feedback.

Good prompt reduces rework and ensures consistent outputs across projects and team members.


# Workspace
Source: https://docs.geekflare.com/ai/features/workspace

Organize chats, manage prompts, and collaborate with your team.

Geekflare AI Workspace is a dedicated environment where you can organize your projects, curate libraries of reusable prompts, and invite team members to work together.

This guide covers how to configure Workspaces to keep your AI workflows focused and efficient.

## What is Workspace

A Workspace is an AI conversation space within your Geekflare AI account, for a specific team or business function. Each Workspace operates independently, with its own conversations, permissions, and analytics.

<img alt="Workspacelist PN" />

This structure ensures clear separation between different activities, reducing clutter and enhancing focus. For example, you might create separate Workspace for business functions like marketing, customer support, or a client-specific project, each with its own team members.

## Workspace Roles

Workspace support flexible user management to align with your team’s needs. Admins can ensure that access is limited to relevant areas.

Roles such as `Owner`, `Admin`, or `Member` define what actions users can take, from configuring settings to viewing conversations.

<img alt="Roles PN" />

<img alt="Roles2 PN" />

This setup helps in secure collaboration and keeps sensitive data isolated, and also minimizes distractions.

## Creating Workspace

On Dashboard, click `Create Workspace`, give it a unique name and URL slug.

<img alt="Creatingworkspace2 Pn" />

<Info> Please note: You can create multiple Workspaces in Business or Enterprise plan. If you are on the Pro plan, you will only have 1 default workspace. </Info>

## Inviting members to a workspace

Click `Members` on the left side to view all the members in your organization. Then click `Invite Members` and add to respective workspaces to invite a new member to a workspace.

<img alt="Invitememberstoworkspace PN" />

## How to Join a Workspace I am invited to?

Click the `View Invites` option by clicking your profile pic.

<img alt="Viewintvites PN" />

Accept the invite to join the workspace.

<img alt="Invitation PN" title="Invitation PN" />

## Managing Permissions

You can assign permissions if you are an `Owner` or `Admin`.

* Click `Members` from the left side menu. Select the member whose permissions you would like to update.

* Under workspace, click the 3 dots.

* You can update the member’s role to admin/member, invite them to a workspace, or even remove them from the organization.

<img alt="Updateteamrole PN" />

## How to Switch Between Workspaces?

Switching between workspaces is simple.

While you are in the chat window, you can see the current organization/workspace at the top right corner. Click it to switch to another workspace.

<img alt="Switchworkspacce PN" />

<img alt="Dropdown Switchworkspace PN" title="Dropdown Switchworkspace PN" />

## Access Control

### Workspace Visibility

* Owners and Admins can see all workspaces in the organization.
* Members can only see workspaces they are part of.

### Workspace Creation and Deletion

* Only Admins and Owners can create or delete workspaces.

### Workspace Privacy

* Workspaces are private to their members.
* Joining a workspace allows a user to view all shared projects and shared chats inside it.

### Chat Visibility

* A chat is visible to:
  * The creator, and
  * Members it has been explicitly shared with
* Workspaces do not automatically grant visibility to all chats.


# Account Management
Source: https://docs.geekflare.com/ai/general/account-management



Learn how to create an account, join an existing organization, and reset the password.

## Creating an Account

This is your entry point to the Geekflare AI ecosystem.

1. **Create Your Account** by visiting [Geekflare AI](https://geekflare.com/ai/) and clicking the **Get Started Free** button. You can also go directly to the [signup page here](https://ai.geekflare.com/c/auth/register).

   ![Geekflare AI homepage](https://cdn.geekflare.com/ai-assets/geekflare-ai-home.png)
2. **Choose Your Sign-Up Method** you can sign up instantly using your Google Account or with your email address and a password.

   ![Account Creation](https://cdn.geekflare.com/ai-assets/geekflare-ai-create-account.png)
3. **Verify Your Email (If Needed)** If you use your email address to sign up, we will send a verification link to your inbox. You must click this link to confirm your account.

   > Note: Didn’t receive the email? Please check your spam or junk folder.

Once this process is completed, you can log in to Geekflare AI.

4. You can then continue as an Individual for personal use or create an organization profile for business use.

## Joining an Organization via Invitation

Received an invitation to join an existing Geekflare AI Organization?

First, you'll need to create a Geekflare AI account as explained above.

Upon your first login after account creation, you'll be guided through an initial setup process. Look for and Click the 'Join an Organization - Accept Invitation' tab on your screen.

<img alt="Invite Accept" />

You should see any pending invitations listed. Select the relevant invitation and click 'Accept' to join the Organization.

## Password Reset

#### For Accounts Created with Email Address

The password reset option is available only if you signed up for your Geekflare AI account using your email address.

To change or reset your password:

1. Visit the [Geekflare AI login page](https://ai.geekflare.com/c/auth/login).
2. Click the ‘Forgot Password?’ link located on the login form.

![Forgot Password](https://cdn.geekflare.com/ai-assets/forgot-password.png)

3. On the next screen, enter the email address associated with your Geekflare AI account and click 'Send Reset Link'.

![Reset Password](https://cdn.geekflare.com/ai-assets/reset-password.png)

4. A password reset link will be sent to your inbox. Please check your email (and your spam/junk folder, just in case) for an email from Geekflare.
5. Click the link in the email and follow the prompts to create and confirm your new password.

#### For Accounts Created with Third-Party Providers (e.g., Google)

If you signed up using a third-party service like Google, your password for Geekflare AI is managed by that provider. You will need to reset your password directly through their respective platform's password recovery process.

### Troubleshooting

* **Didn't receive the email?** Double-check that you entered the correct email address. Also, make sure to check your spam or junk mail folders. If you still don't receive it, wait a few minutes and try again.
* **Link expired?** For security reasons, password reset links are time-sensitive. If the link has expired, simply repeat the steps above to request a new one.


# Supported Payment Methods
Source: https://docs.geekflare.com/ai/general/payment-method



Geekflare utilizes **Stripe** as our trusted payment processor, allowing us to accept a wide variety of payment methods.

Stripe supports the major credit, debit cards like **Visa**, **Mastercard**, **American Express** and digital wallets like **Google Pay**, **PayPal** and **Apple Pay**.

All payments are processed securely by [Stripe](https://stripe.com/). Geekflare AI does not store your full credit card details on our servers.

## Payment Currencies

Geekflare AI pricing is in USD, but you can pay in your local currencies like GBP, EUR, SGD, INR, AED, CAD, and [others as supported by Stripe](https://docs.stripe.com/currencies).

## UPI Payment

For our users in India, Geekflare Chat supports UPI (Unified Payments Interface). This allows for secure transactions directly through your preferred UPI-enabled mobile application.


# Refund Policy
Source: https://docs.geekflare.com/ai/general/refund-policy



Geekflare AI subscriptions are **non-refundable**, and we do not offer prorated refunds or credits for partially used subscription periods.

When you cancel your subscription, you will continue to have access to the service through the end of your current paid billing cycle.

**Exceptions:**
In rare circumstances, such as a billing error on our part or as required by applicable law, we may consider issuing a refund. These situations are reviewed on a case-by-case basis.


# Security and Trust at Geekflare AI
Source: https://docs.geekflare.com/ai/general/security-trust



At Geekflare AI, your trust is our priority. Security, privacy, and responsible AI practices are integral to all our operations. Our commitment to a **security-first** mindset is embedded in every feature, from the moment you access our platform to how you chat with models, upload documents, and share your work.

## Data Privacy by Default

* Your chats and documents are never used to train or fine-tune AI models.
* All data is secured in transit with TLS 1.2 or higher, and all uploaded files and saved data are securely stored on our servers.
* Documents you attach during chats are automatically deleted after your session ends. They are only retained if you explicitly save them to your private Data Sources.

## BYOK (Bring Your Own Key) Explained

Geekflare Connect supports a Bring Your Own Key (BYOK) model, allowing you to use your own API keys for various providers, including OpenAI, Anthropic, Gemini, OpenRouter, and others.

Your API keys are encrypted and securely stored on Geekflare’s servers. API keys are encrypted at rest in our database using AES-256-CBC, an industry-standard encryption method. They are never stored on individual user browsers or local devices, minimizing client-side vulnerabilities.

All requests originating from your Geekflare Connect are securely proxied through the Geekflare backend. This architecture ensures that your sensitive API keys are never directly exposed to individual team members or client-side applications.

Only authorized users with the correct role can manage or update these keys.

## How Geekflare Handles API Data

When users interact with models through Geekflare Connect, the platform processes prompts and responses through its backend to communicate with the respective model provider using the API key.

Geekflare Connect stores prompts, responses, and chat history so that users can revisit conversations, maintain continuity across projects, and access analytics or usage insights.

This stored data is also used to support product features such as project-level context, shared chats, and workspace collaboration.

Geekflare does not expose API keys in chat history or interface elements accessible to members.

## Team Access Controls

Geekflare Connect uses role-based access control **(RBAC)** to manage how members interact within organizations, workspaces, and data.

Owner & Admins can:

* Assign roles such as Admin, Member etc.
* Decide which users can access specific workspaces.
* Control permissions for viewing chats, managing API keys, and configuring workspace settings.
* Restrict access to sensitive settings at the organization or workspace level.

This structure ensures that teams can collaborate efficiently while maintaining appropriate security boundaries.

## Transparency & Control

* You are always in the know. We clearly display which AI model (e.g., GPT-4, Claude, Gemini, DeepSeek) is responding to your prompts.
* When you use your own keys via Geekflare Connect, you retain absolute control. We have zero access to them.
* We are committed to collecting only the data essential for the platform to function. You have full control to view, manage, and permanently delete your chat history, API keys and account data at any time from the dashboard.

## Responsible AI in Practice

We believe AI should be used as a powerful assistant, not an authority. To help you get the most out of our tools safely and effectively, we recommend the following practices:

* AI is an assistant, not an authority. We encourage users to validate outputs.
* Generative AI can produce incorrect, biased, or outdated information. Always review outputs and cross check with multiple models and loop humans, especially in sensitive contexts.
* Avoid sharing confidential, personal, or regulated data in prompts. While Geekflare AI doesn’t use your data, the model provider may process it depending on your API key or plan.

#### We're Here to Help

Your trust is our top priority, and we are committed to full transparency. If you have any questions about our data handling practices, model choices, or any aspect of our security, please don't hesitate to [contact us](https://ai.geekflare.com/c/help).


# Support and Feedback
Source: https://docs.geekflare.com/ai/general/support-and-feedback



We've made it easy for you to reach out to our team, report problems, and request new features. We are here to help!

To contact support or provide feedback:

* Click the 'Help' option at the bottom left of your screen.

![Help Button](https://cdn.geekflare.com/ai-assets/help.png)

A contact form will appear, allowing you to:

* Give Feedback
* Request a Feature
* Report a Bug
* Address Billing Issues

![Help Form](https://cdn.geekflare.com/ai-assets/help-form.png)

Once you submit the details, our team will review your submission and get back to you as soon as possible.


# Geekflare AI Docs
Source: https://docs.geekflare.com/ai/intro

Welcome to Geekflare AI documentation! We’re excited to have you on board.

## What is Geekflare AI?

[Geekflare AI](https://geekflare.com/ai/) is a suite of AI applications to help individuals and teams access and use multiple AI models from a single platform. You can onboard your entire team and work in a collaborative AI platform to share prompts, chats, manage AI spending, and view detailed usage analytics.

Geekflare AI includes two core tools:

<CardGroup>
  <Card title="Geekflare Chat" icon="robot" href="https://geekflare.com/ai/chat/">
    An all-in-one AI subscription that gives you access to multiple AI models through a single chat interface.
  </Card>

  <Card title="Geekflare Connect" icon="key" href="https://geekflare.com/ai/connect/">
    A BYOK (Bring Your Own Key) AI chat app for businesses to securely connect and manage their own AI providers.
  </Card>
</CardGroup>

### Shortcut URL for Geekflare Chat

Use [chat.geekflare.com](https://chat.geekflare.com) to quickly access Geekflare Chat APP without navigating through the main website.

## System Requirements

Geekflare AI is a browser-based platform and does not require any installation. It works smoothly on all modern browsers including **Google Chrome, Microsoft Edge, Firefox, Safari, and Brave**.

For best performance, please use the latest browser version with a stable internet connection.

## Getting Started 🚀

Ready to dive in? Our [**Quick Start Guide**](/ai/connect/getting-started) will have you and your team up and running in less than 5 minutes.

## Need Help?

We've done our best to document everything, but if you get stuck or have a question, we're here to help. Please don’t hesitate to [contact our support team](https://ai.geekflare.com/help).


# API Credit Consumption
Source: https://docs.geekflare.com/api-credit-mapping



We utilize a flexible Credit System in Geekflare. Instead of limiting you to a specific number of requests per endpoint, your subscription provides a pool of credits that can be used across our entire suite of APIs.

Different API endpoints consume different amounts of credits based on the computational resources and bandwidth required to process the request.

## Credit Usage

The table below outlines the credit cost for a single successful request to each endpoint.

| API Endpoint                                | Credits Per Request |
| :------------------------------------------ | :------------------ |
| **DNS Lookup**                              | 1                   |
| **Site Load Time**                          | 1                   |
| **Site Load Time (with `targetCountries`)** | 8                   |
| **Site Status**                             | 1                   |
| **URL Redirection**                         | 1                   |
| **TLS Scan**                                | 1                   |
| **Web Scraping**                            | 1                   |
| **Ping**                                    | 2                   |
| **Port Scanner**                            | 2                   |
| **Meta Scraping**                           | 2                   |
| **Broken Link Checker**                     | 2                   |
| **Search**                                  | 2                   |
| **Search with Scrape**                      | 4                   |
| **Search with Grounded Answer**             | 5                   |
| **Proxy**                                   | 4                   |
| **Screenshot**                              | 5                   |
| **PDF Generator**                           | 5                   |
| **Lighthouse Audit**                        | 10                  |

<Note>
  [Load Time](/endpoint/load-time) with `targetCountries` set costs a flat **8 credits** per request, regardless of how many locations (1–3) you test — see [Multi-Location Testing](/load-time-multi-location).
</Note>

The credits required for each API request are visible in the [Playground](/api-playground) as well, so you know your potential consumption.

<img alt="Playground credit info" />

## Usage Mechanics

### 1. Calculation Logic

Credits are deducted immediately upon the successful execution of an API call.

<Note>
  Example: If you make 10 calls to the **Web Scraping API**,
  you will consume `10 credits` (10 calls × 1 credit).
</Note>

### 2. Failed Requests

We value fairness. You are generally **not charged** for API errors caused by our infrastructure (HTTP 5xx status codes).

* **4xx Errors:** Requests that fail due to invalid user input (e.g., specific bad URLs, missing parameters, or unauthorized access) generally do not consume credits.

### 3. Proxy Usage (Add-on Cost)

The **Premium Proxy** feature costs **5 credits per request**. This is an additional cost applied on top of the base API endpoint.

The proxy feature can be enabled on various HTTP-based APIs (such as Web Scraping, Screenshot, and Headers). Please refer to our [Using Proxies](/using-proxies) documentation for the full list of supported endpoints.

**Calculation Example:**
If you make a **Web Scraping** request and enable the Proxy feature:

* **Web Scraping:** 1 Credit
* **Proxy Add-on Cost:** + 4 Credits
* **Total Consumed:** **5 Credits**


# API Playground
Source: https://docs.geekflare.com/api-playground



The API Playground is an interactive environment to test our entire suite of APIs directly from your browser. Whether you are exploring the Web Scraping, Search, or Screenshot APIs, the Playground lets you see real-time responses without setting up a development environment or writing code.

**Key Features**

* No-Code app to test any Geekflare endpoint using a visual interface to input URL and body payload.
* Copy ready-to-use code snippets for your configured request in popular languages like Python, Node.js, cURL, and PHP.
* Toggle optional parameters like proxy locations, device types, or viewport sizes to see how they affect the API output.

**How to Access the Playground**

To access the Playground, log in to your Geekflare dashboard and click on [API Playground](https://dash.geekflare.com/playground) in the left-hand navigation menu. Your API key is automatically authenticated within the Playground, so you can start testing immediately.

<iframe />

**Using the Playground**

1. Choose the specific API you want to test from the top menu.
2. Fill in the required fields, such as the target URL. Use the other options to configure specific parameters like proxy, output formats, etc..
3. Click the **Send Request** button. The Playground will process your request in real-time using your account quota.
4. You'll see the output in the response pane. You can review the formatted payload, check the HTTP status code for errors or success. For visual APIs like the Screenshot API, the rendered image will be previewed directly in the browser.
5. Once you have the response, locate the **Code Snippets** tab next to the Response. Select your preferred language and copy the generated snippet directly into your codebase.


# API Logs
Source: https://docs.geekflare.com/api-request-logs

Check API requests in near realtime.

The Geekflare Dashboard includes a near real-time log viewer. This allows you to monitor your API usage and debug failed requests.

To view your logs, log in to the [Geekflare Dashboard](https://dash.geekflare.com/) and click on **API Logs** in the left-hand sidebar.

![API Logs](https://cdn.geekflare.com/api-assets/api-logs.png)

***

## Log Details

API logs appear in your dashboard in near real-time. Each log entry provides information to help you understand your API usage:

* **Timestamp:** The exact date and time the API request was received.
* **Endpoint:** The specific Geekflare endpoint that was called (e.g., `/scraping`, `/screenshot`, `/up`).
* **Target URL:** The actual website URL you passed inside your request's body payload (e.g., `{"url": "https://example.com"}`).
* **HTTP Status:** The response code returned by our API (e.g., `200 OK`, `400 Bad Request`, `429 Too Many Requests`, `500 Server Error`).

## Searching & Filtering

When you are sending thousands of requests, finding a specific error can be difficult. The API Logs page includes search and filtering options to help you pinpoint exactly what you are looking for:

* **Search by URL:** Use the search bar to find requests made to a specific target URL.
* **Filter by Endpoint:** Narrow down your logs to only show traffic for a specific API endpoint request.
* **Filter by Status Code:** Quickly isolate errors by filtering for `4xx` or `5xx` HTTP status codes.
* **Date Range:** Select a specific start and end date to view historical API activity.

## Team Access

For users on our **paid plans**, you can invite your teams to your workspace. Once invited, team members can log in to view API logs, API keys, and troubleshoot issues without needing access to your personal login credentials.

👉 **[Learn about Teams & Workspaces](/teams)**


# Best Practices
Source: https://docs.geekflare.com/best-practices

Production-ready patterns for retries, timeouts, concurrency, and idempotency when calling the Geekflare.

These patterns apply across all Geekflare endpoints. Following them will make your integration resilient to transient failures and easier to reason about at scale.

## Retries

Not every failure should be retried. Retry `429` and `5xx` responses; do **not** retry `401`, `402`, `403`, or `404` — those indicate a problem with the request itself, and retrying it will fail the same way every time.

| Code  | Retry? | Why                                                            |
| ----- | ------ | -------------------------------------------------------------- |
| `429` | Yes    | Transient — respect `x-geekflare-ratelimit-reset`, then retry. |
| `5xx` | Yes    | Transient infrastructure issue.                                |
| `401` | No     | Fix the API key first.                                         |
| `402` | No     | Add credits first.                                             |
| `403` | No     | Upgrade your plan first.                                       |
| `404` | No     | Fix the endpoint path or method first.                         |

### Exponential backoff with jitter

```typescript theme={null}
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      const status = error?.apiCode ?? error?.status;
      const retryable = status === 429 || (status >= 500 && status < 600);

      if (!retryable || attempt === maxRetries) throw error;

      const baseDelay = 2 ** attempt * 1000;
      const jitter = Math.random() * 500;
      await new Promise((resolve) => setTimeout(resolve, baseDelay + jitter));
    }
  }
  throw new Error("Unreachable");
}
```

<Tip>
  If the response includes an `x-geekflare-ratelimit-reset` header, wait at
  least that long before your first retry. Don't rely on backoff alone. See
  [Rate Limit Exceeded](/rate-limit-exceeded) for details on the rate-limit
  headers.
</Tip>

## Timeouts

Set a client-side timeout on every request. Endpoints that render JavaScript or capture screenshots can take longer than simple lookups (DNS, ping). Don't apply the same timeout to both.

* **Fast endpoints** (DNS Lookup, Ping, Site Status, TLS Scan): 10–15 seconds is generally enough.
* **Browser-based endpoints** (Web Scraping with rendering, Screenshot, Lighthouse): allow 30–60 seconds, especially for heavy or slow-loading pages.

A request that hangs without a timeout ties up a connection in your pool indefinitely and can cascade into broader outages under load.

## Concurrency

Your [rate limit](/rate-limit-exceeded) caps requests per second, not concurrent connections. But sending far more concurrent requests than your rate limit allows just means most of them queue or get `429`s. Size your concurrency to roughly match your plan's requests-per-second limit, and use a queue or semaphore to stay under it rather than firing requests unbounded.

```typescript theme={null}
import pLimit from "p-limit";

const limit = pLimit(5); // match your plan's RPS

const results = await Promise.all(
  urls.map((url) => limit(() => client.webScrape({ url }))),
);
```

## Idempotency

Geekflare endpoints are stateless HTTP calls. Retrying an identical request (same URL, same parameters) simply re-runs it and consumes credits again. If you're retrying after a timeout where you're unsure whether the original request completed, prefer checking your [API Logs](/api-request-logs) for the original request before firing a duplicate, especially for credit-heavy calls like AI Extraction or Lighthouse audits.

## Monitoring

Every response includes headers you can log or check inline, without a separate dashboard call:

| Header                                   | Tells you                                           |
| ---------------------------------------- | --------------------------------------------------- |
| `x-geekflare-ratelimit-second`           | Max requests per second for your plan               |
| `x-geekflare-ratelimit-remaining-second` | Requests remaining in the current 1-second window   |
| `x-geekflare-ratelimit-reset`            | How long until the current rate-limit window resets |
| `x-geekflare-credits-used`               | Credits used                                        |
| `x-geekflare-credits-remaining`          | Credits remaining in your balance                   |

* Watch `x-geekflare-ratelimit-remaining-second` to anticipate `429`s before they happen.
* Watch `x-geekflare-credits-remaining` to avoid a [402 Credit Exhausted](/credit-exhausted) error mid-batch, especially before starting a large scrape or search job.
* Check [status.geekflare.com](https://status.geekflare.com/) if you see a spike in `5xx` errors — it's the fastest way to confirm whether an issue is on Geekflare's side before opening a support ticket.

## Next Steps

<CardGroup>
  <Card title="Error Code Reference" icon="triangle-exclamation" href="/error-codes">
    Every error code and what to do about it.
  </Card>

  <Card title="Rate Limit Exceeded" icon="gauge" href="/rate-limit-exceeded">
    Headers, backoff strategy, and per-plan limits.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.geekflare.com/changelog

New features, changes, and fixes to the Geekflare API.

<Update label="2026-08-05" description="Web Scraping pricing and rendering">
  **Simplified Web Scraping credits.** All Web Scraping requests now cost a flat **1 credit**, regardless of whether JavaScript rendering is used. The previous 2-credit "standard" tier has been removed. AI Extraction remains a **+6 credit** add-on (7 total).

  **Automatic JavaScript rendering.** `renderJS` is now automatic by default — Geekflare fetches the page without a browser first, and only falls back to full JavaScript rendering if the page needs it, at no extra cost. Set `renderJS: true` or `renderJS: false` explicitly to force rendering on or off. See [JavaScript Rendering](/guides/web-scraping#javascript-rendering).

  **New `proxyMode` parameter.** Web Scraping now supports `proxyMode` (`false` / `auto` / `true`, default `false`) for finer control over when a proxy is used:

  * `false` — never use a proxy (default)
  * `auto` — try without a proxy first, and automatically retry through a proxy if the request is blocked
  * `true` — always route through a proxy

  This replaces relying on `proxyCountry` alone to trigger proxy usage. See [Proxy Routing](/guides/web-scraping#proxy-routing).
</Update>


# Colophon
Source: https://docs.geekflare.com/colophon



Geekflare products are built upon the shoulders of giants. We believe in transparency and want to acknowledge the open-source projects and SaaS platforms that make our products possible.

While this list is not exhaustive, we want to say a special **thank you** to the following technologies that power our infrastructure and products.

### Frontend

* **[Next.js](https://nextjs.org/):** The framework powering our products websites.
* **[Lucide Icons](https://lucide.dev/):** Beautiful and lightweight icons used throughout our UI.
* **[Mintlify](https://mintlify.com/):** Beautiful documentation which you are reading.

### Backend

* **[NestJS](https://nestjs.com/):** The progressive Node.js framework that structures our backend architecture.
* **[TypeScript](https://www.typescriptlang.org/):** For type safety and robust code across our entire stack.
* **[Swagger (OpenAPI)](https://swagger.io/):** Used to generate our interactive API specifications.
* **[Axios](https://axios-http.com/):** For handling reliable HTTP requests.

### Data & Search

* **[PostgreSQL](https://www.postgresql.org/):** Our relational database system.
* **[Meilisearch](https://www.meilisearch.com/):** Providing the relevant search experience.

### Headless Browser

* **[Crawl4AI](https://github.com/unclecode/crawl4ai):** A component in our crawling capabilities.
* **[Puppeteer](https://pptr.dev/):** Enabling our headless browser rendering.

### Infrastructure & Cloud

* **[Cloudflare](https://www.cloudflare.com/):** For our global edge network, security, and DNS.
* **[GCP](https://cloud.google.com/) & [AWS](https://aws.amazon.com/):** Our reliable cloud infrastructure providers for compute and storage.

### Analytics

* **[PostHog](https://posthog.com/):** Helps us understand product usage and improve user experience.

***

*This list is a snapshot of our tech stack. We extend our gratitude to the countless other library contributors in the open-source community whose work supports the modern web.*


# Credit Exhausted
Source: https://docs.geekflare.com/credit-exhausted

Error: Credit Exhausted (402)

If your API requests are failing with the HTTP status code `402 Payment Required`, it means your account has reached a **zero credit balance**.

When this happens, the API will block all incoming requests until credits are added to your account.

## Sample Response

Your application will receive a JSON response similar to this:

```json theme={null}
{
    "apiCode": 402,
    "message": "You have exhausted your API credits for this billing period.",
    "details": {
        "current_balance": 0,
        "action_required": "Please purchase a Top-up or Upgrade your plan to continue."
    },
    "dashboard_url": "https://dash.geekflare.com/billing",
    "documentation_url": "https://docs.geekflare.com/credit-exhausted",
    "apiStatus": "failure"
}
```

## How to Resolve

To restore API access immediately, you have two options:

### 1. Purchase a Top-up (Instant)

Top-ups are one-time credit packs that do not expire. They act as a safety net when your monthly plan runs out.

* Go to **[Dashboard > Billing](https://dash.geekflare.com/billing)**.
* Select a **Top-up Pack**.
* Access is restored immediately upon payment.

### 2. Wait for Monthly Reset

If you are on a subscription plan, your credits will automatically reset on the 1st day of your billing cycle. You can check your next reset date on your Dashboard.

***

## Need Help?

If you believe you received this error by mistake or need a custom enterprise plan with higher limits, please [contact support](https://geekflare.com/contact/?product=api).

See the [Error Code Reference](/error-codes) for other error codes, or [Best Practices](/best-practices) for tips on monitoring your credit balance proactively.


# Broken Link Checker
Source: https://docs.geekflare.com/endpoint/broken-link

POST /brokenlink
Scan a webpage for broken links and report which URLs return errors, so you can fix dead links before they hurt SEO or user experience.



# DNS Records
Source: https://docs.geekflare.com/endpoint/dns-records

POST /dnsrecord
Look up A, AAAA, CNAME, MX, CAA, NS, SOA, SRV, and TXT records for any domain. Query every supported type in one call, or pass `types` to fetch only the ones you need.



# DNSSEC
Source: https://docs.geekflare.com/endpoint/dnssec

POST /dnssec
Check whether DNSSEC is properly configured and validating for a domain, helping you confirm protection against DNS spoofing and cache poisoning attacks.



# Lighthouse
Source: https://docs.geekflare.com/endpoint/lighthouse

POST /lighthouse
Run a Google Lighthouse audit for performance, SEO, accessibility, and best practices, with support for advanced flags via the `parameters` array.



# Load Time
Source: https://docs.geekflare.com/endpoint/load-time

POST /loadtime
Measure how long a webpage takes to fully load from a real browser. Pass `targetCountries` (up to 3 ISO country codes) to also test reachability from those locations via proxy alongside the default US server test, and compare results side by side.

<Info>
  Want to test from multiple countries in one request? See [Load Time:
  Multi-Location Testing](/load-time-multi-location).
</Info>


# Meta Scraping
Source: https://docs.geekflare.com/endpoint/metascraping

POST /metascraping
Extract a page's meta tags, Open Graph, and Twitter Card data like title, description, canonical URL, images, and more without scraping the full page body.



# Mixed Content
Source: https://docs.geekflare.com/endpoint/mixed-content

POST /mixedcontent
Scan an HTTPS page for insecure HTTP resources like images, scripts, or stylesheets that trigger browser security warnings and break the padlock icon.



# MTR
Source: https://docs.geekflare.com/endpoint/mtr

POST /mtr
Run a My Traceroute (MTR) diagnostic between Geekflare and a target host, combining traceroute and ping to show packet loss and latency at each network hop.



# PDF Generator
Source: https://docs.geekflare.com/endpoint/pdf-generator

POST /url2pdf
Convert any URL into a downloadable PDF document, with control over page orientation, margins, and scale. Useful for archiving pages or generating reports.



# Ping
Source: https://docs.geekflare.com/endpoint/ping

POST /ping
Send ICMP ping requests to a URL or IP and return latency, packet loss, and round-trip time statistics — useful for quick reachability and network health checks.



# Port Scanner
Source: https://docs.geekflare.com/endpoint/port-scanner

POST /openport
Scan a domain or IP for open TCP ports, either across the top N most common ports or a custom range you specify. Useful for surface-level network security audits and exposure checks.



# Geekflare API Reference
Source: https://docs.geekflare.com/endpoint/reference

Complete reference for all Geekflare API endpoints.

## Overview

This section provides detailed documentation for all available API endpoints, including request parameters, response formats, and code examples.

All API endpoints use the base URL:

```
https://api.geekflare.com
```

<a href="https://www.postman.com/geekflare/geekflare-api/collection/q0iiukn/geekflare">
  <img alt="Run in Postman" />
</a>

Fork our [Postman collection](https://www.postman.com/geekflare/geekflare-api/collection/q0iiukn/geekflare) to explore and test every endpoint without writing any code.

## Available Endpoints

The Geekflare API is comprised of the following endpoint categories:

### AI & Scraping

Scrape LLM-ready content, capture screenshots, and generate PDFs.

<CardGroup>
  <Card title="Web Scraping" icon="spider-web" href="/endpoint/webscraping">
    Extract LLM-ready, JSON and HTML from web pages.
  </Card>

  <Card title="Meta Scraping" icon="tags" href="/endpoint/metascraping">
    Extract metadata in markdown or JSON format from web pages.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/endpoint/search">
    Search results from the web or news in JSON, Markdown, or HTML.
  </Card>

  <Card title="Screenshot" icon="camera" href="/endpoint/screenshot">
    Capture full-page screenshots using desktop or mobile device.
  </Card>

  <Card title="PDF Generator" icon="file-pdf" href="/endpoint/pdf-generator">
    Convert any URL to a PDF document.
  </Card>
</CardGroup>

### Website Testing

Test and monitor website performance, broken links, and overall site health.

<CardGroup>
  <Card title="Broken Link Checker" icon="link-slash" href="/endpoint/broken-link">
    Check if a webpage contains any broken links.
  </Card>

  <Card title="Mixed Content" icon="shield-exclamation" href="/endpoint/mixed-content">
    Detect mixed HTTP/HTTPS content on web pages.
  </Card>

  <Card title="Lighthouse" icon="lighthouse" href="/endpoint/lighthouse">
    Run Google Lighthouse audits for performance and SEO.
  </Card>

  <Card title="Load Time" icon="clock" href="/endpoint/load-time">
    Measure total time taken to load webpage.
  </Card>

  <Card title="URL Redirection" icon="arrows-turn-right" href="/endpoint/url-redirect">
    Track URL redirects with status codes and headers.
  </Card>
</CardGroup>

### DNS & Network

Analyze DNS records, network paths, and connectivity.

<CardGroup>
  <Card title="DNS Records" icon="database" href="/endpoint/dns-records">
    Retrieve DNS records for any domain.
  </Card>

  <Card title="DNSSEC" icon="shield-check" href="/endpoint/dnssec">
    Test if DNSSEC is enabled on a domain.
  </Card>

  <Card title="MTR" icon="route" href="/endpoint/mtr">
    Traceroute domain or IP to check network path.
  </Card>

  <Card title="Ping" icon="wifi" href="/endpoint/ping">
    Test reachability and get latency information.
  </Card>
</CardGroup>

### Security

Scan for security vulnerabilities and certificate information.

<CardGroup>
  <Card title="TLS Scan" icon="lock" href="/endpoint/tls-scan">
    Check TLS versions and certificate details.
  </Card>

  <Card title="Port Scanner" icon="radar" href="/endpoint/port-scanner">
    Scan for open TCP ports on a domain or IP.
  </Card>
</CardGroup>

## Common Parameters

Many endpoints share common parameters:

<ParamField type="string">
  The URL or domain to be tested
</ParamField>

<ParamField type="string">
  Proxy country code for testing from different locations. See [supported
  APIs](/using-proxies) for available options.
  <Info>Proxy is available to premium plan users only.</Info>
</ParamField>

<ParamField type="boolean">
  Whether to follow HTTP redirects. Default is `false`.
</ParamField>

<ParamField type="string">
  Device type for rendering. Options: `desktop`, `mobile`. Default is `desktop`.
</ParamField>

## Response Format

All API responses follow a consistent structure:

### Success Response

```json theme={null}
{
  "timestamp": 1657109686205,
  "apiStatus": "success",
  "apiCode": 200,
  "message": "Operation completed successfully",
  "meta": {
    "url": "example.com",
    "test": {
      "id": "unique-test-identifier"
    }
  },
  "data": {}
}
```

### Error Response

```json theme={null}
{
  "timestamp": 1657109686205,
  "apiStatus": "failure",
  "apiCode": 403,
  "message": "You are not allowed to access. This is available to premium plan only."
}
```


# Screenshot
Source: https://docs.geekflare.com/endpoint/screenshot

POST /screenshot
Capture a pixel-perfect screenshot of any URL as PNG, JPEG, or WebP. Supports full-page capture, device emulation, custom viewports, and CAPTCHA/cookie-banner bypass.



# Search
Source: https://docs.geekflare.com/endpoint/search

POST /search
Structured search results from the web or news. Strips out ads and HTML noise to provide pure data in JSON, Markdown, or HTML. Fully supports AI-grounded answers, search-with-scrape, image search, and targeted Web or News sourcing.



# Site Status
Source: https://docs.geekflare.com/endpoint/site-status

POST /up
Check whether a website is reachable and returns a successful HTTP response. Ideal for uptime monitoring and pre-flight checks before running other tests.



# TLS Scan
Source: https://docs.geekflare.com/endpoint/tls-scan

POST /tlsscan
Inspect a domain's TLS/SSL configuration, including supported protocol versions, cipher suites, and certificate details, to catch expiring or misconfigured certificates.



# URL Redirection Checker
Source: https://docs.geekflare.com/endpoint/url-redirect

POST /redirectcheck
Trace the full redirect chain of a URL, including every intermediate hop, status code, and the final destination. Useful for auditing SEO redirects and link rot.



# Web Scraping
Source: https://docs.geekflare.com/endpoint/webscraping

POST /webscraping
Fetch a page and return content as Markdown, HTML, JSON, or plain text. Automatically detects whether JavaScript rendering is needed, with optional stealth mode, `proxyMode`-controlled proxy routing, and CSS/XPath field extraction.



# Error Code Reference
Source: https://docs.geekflare.com/error-codes

Complete reference for every HTTP status code and apiCode the Geekflare API can return, with sample responses.

Every Geekflare API response includes an `apiCode` that mirrors the HTTP status code, plus a `message` describing what went wrong. Use this page as the canonical reference; the sections below link to dedicated troubleshooting guides for the most common failures.

## Success

| Code  | Meaning | Notes                                                  |
| ----- | ------- | ------------------------------------------------------ |
| `200` | Success | The request completed and `data` contains your result. |

## Client Errors (4xx)

| Code  | Meaning                           | Guide                                       |
| ----- | --------------------------------- | ------------------------------------------- |
| `401` | Missing or invalid `x-api-key`    | [Unauthorized](/unauthorized)               |
| `402` | Credit balance exhausted          | [Credit Exhausted](/credit-exhausted)       |
| `403` | Endpoint requires a higher plan   | [Forbidden](/forbidden)                     |
| `404` | Wrong endpoint URL or HTTP method | —                                           |
| `429` | Rate limit exceeded               | [Rate Limit Exceeded](/rate-limit-exceeded) |

### 404 — Not Found

Returned when the endpoint path or HTTP method is wrong (for example, sending a `GET` request to an endpoint that only accepts `POST`).

```json theme={null}
{
  "timestamp": 1657208461046,
  "apiStatus": "failure",
  "apiCode": 404,
  "message": "API not found.",
  "meta": {
    "method": "POST",
    "endpoint": "/helloworld"
  }
}
```

<Tip>Double-check the endpoint path against the [API Reference](/endpoint/reference) and confirm you're using the correct HTTP method.</Tip>

## Server Errors (5xx)

Any `5xx` response indicates an issue on Geekflare's infrastructure, not your request. These are generally **not charged** against your credit balance — see [Failed Requests](/api-credit-mapping#2-failed-requests).

If you see a `5xx` error, check [status.geekflare.com](https://status.geekflare.com/) first to confirm whether it's a known incident, then retry with backoff (see [Best Practices](/best-practices)). If it persists, [contact support](https://geekflare.com/contact/?product=api).

## Related

<CardGroup>
  <Card title="Unauthorized (401)" icon="key" href="/unauthorized">
    Missing or invalid API key
  </Card>

  <Card title="Credit Exhausted (402)" icon="coins" href="/credit-exhausted">
    Zero credit balance
  </Card>

  <Card title="Forbidden (403)" icon="ban" href="/forbidden">
    Endpoint not available on your plan
  </Card>

  <Card title="Rate Limit Exceeded (429)" icon="gauge" href="/rate-limit-exceeded">
    Too many requests per second
  </Card>
</CardGroup>


# Forbidden Error
Source: https://docs.geekflare.com/forbidden

403 Forbidden (Endpoint Requires a Higher Plan)

If your API requests are failing with the HTTP status code `403 Forbidden`, it means the endpoint you're calling isn't included in your current plan.

## Sample Response

```json theme={null}
{
  "timestamp": 1658254283953,
  "apiStatus": "failure",
  "apiCode": 403,
  "message": "You are not allowed to access. This is available to premium plan only."
}
```

## How to Resolve

1. **Check which plan the endpoint requires.** Some endpoints and features like Port Scanner, Proxy are gated to paid plans. Compare your current plan against the endpoint's requirements on the [Pricing](https://geekflare.com/pricing/) page.
2. **Upgrade your plan.** Log in to your [Dashboard](https://dash.geekflare.com/) and upgrade to a plan that includes the endpoint you need.
3. **Double-check you're calling the intended endpoint.** If you didn't mean to call a premium endpoint, verify the request path against the [API Reference](/endpoint/reference).

<Info>
  This is different from a [429 Rate Limit Exceeded](/rate-limit-exceeded)
  error. 403 means the endpoint itself isn't available on your plan,
  regardless of how many requests you've made.
</Info>

## Need Help?

If you believe you're seeing this error in error, or need a custom enterprise plan, [contact support](https://geekflare.com/contact/?product=api).


# Screenshot Guide
Source: https://docs.geekflare.com/guides/screenshot

Capture full-page or viewport screenshots of any website. Supports device emulation, ad blocking, CAPTCHA bypass, proxy routing, Retina quality, and AI-friendly link highlighting.

The Screenshot endpoint captures a pixel-perfect screenshot of any URL. It renders JavaScript, blocks ads and cookie banners, handles CAPTCHAs, and can emulate any device or viewport size. Costs **5 credits** per request.

**Endpoint:** `POST https://api.geekflare.com/screenshot`

<Info>
  Install the official SDK: `npm install @geekflare/api-node` or `pip install
      geekflare-api`
</Info>

***

## Basic Screenshot

Capture a screenshot and get back a CDN URL to the image.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  import { GeekflareClient } from '@geekflare/api-node';

  const client = new GeekflareClient({ apiKey: 'YOUR_API_KEY' });
  const result = await client.screenshot({ url: 'https://example.com' });
  console.log(result);

  ```

  ```python Python SDK theme={null}
  from geekflare_api.client import GeekflareClient
  from geekflare_api.models import ScreenshotDto

  with GeekflareClient(api_key='YOUR_API_KEY') as client:
      result = client.screenshot(ScreenshotDto(url='https://example.com'))
      print(result)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com"}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "url": "https://example.com",
      "type": "png",
      "device": "desktop",
      "fullPage": false,
      "blockAds": true,
      "hideCookie": true,
      "skipCaptcha": true,
      "addTimestamp": false,
      "test": { "id": "abc123" }
    },
    "data": "https://cdn.geekflare.com/tests/screenshot/kbi6d206g87ituahb7icwtpr.png"
  }
  ```
</Accordion>

***

## Full-Page Screenshot

Capture the entire scrollable page, not just the viewport.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    fullPage: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', full_page=True))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "fullPage": true}'
  ```
</CodeGroup>

***

## Capture a Specific Element (CSS Selector)

Capture only the element matching a CSS selector instead of the full viewport or page. Combine with `fallbackToFullPage` to gracefully fall back to a full-page capture if the selector isn't found, instead of failing the request.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    selector: '.hero-section',
    fallbackToFullPage: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(
      url='https://example.com',
      selector='.hero-section',
      fallback_to_full_page=True
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "selector": ".hero-section", "fallbackToFullPage": true}'
  ```
</CodeGroup>

<Note>
  If `selector` is omitted, the endpoint captures the full viewport (or full
  page, if `fullPage` is `true`). If `selector` is set and no matching element
  is found, the request fails unless `fallbackToFullPage` is `true`.
</Note>

***

## Image Format and Quality

Choose between PNG, JPEG, or WebP output and control quality for JPEG/WebP.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    type: 'webp',
    quality: 85
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', type='webp', quality=85))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "type": "webp", "quality": 85}'
  ```
</CodeGroup>

***

## Device Emulation

Emulate a mobile device to capture mobile-specific layouts.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    device: 'mobile'
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', device='mobile'))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "device": "mobile"}'
  ```
</CodeGroup>

***

## Custom Viewport

Set a custom viewport width, height, or page height for partial screenshots. Use `captureBeyondViewport` to allow the capture to include content that extends beyond the configured viewport dimensions.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    viewportWidth: 1440,
    viewportHeight: 900,
    pageHeight: 1200,
    captureBeyondViewport: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(
      url='https://example.com',
      viewport_width=1440,
      viewport_height=900,
      page_height=1200,
      capture_beyond_viewport=True
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "viewportWidth": 1440, "viewportHeight": 900, "pageHeight": 1200, "captureBeyondViewport": true}'
  ```
</CodeGroup>

***

## Retina / High-DPI

Capture Retina-quality screenshots using a higher device scale factor.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    scaleFactor: 2
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', scale_factor=2))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "scaleFactor": 2}'
  ```
</CodeGroup>

***

## Dark Mode

Render the page in dark mode before capturing.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    theme: 'dark'
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', theme='dark'))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "theme": "dark"}'
  ```
</CodeGroup>

***

## Highlight Links (AI Vision)

Draw visible borders around all clickable links, buttons, and inputs. Useful for AI vision models and LLM web browsing agents.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    highlightLinks: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', highlight_links=True))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "highlightLinks": true}'
  ```
</CodeGroup>

***

## Remove Background

Remove the page background for transparent PNG output. Useful for design tools.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    removeBackground: true,
    type: 'png'
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(
      url='https://example.com',
      remove_background=True,
      type='png'
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "removeBackground": true, "type": "png"}'
  ```
</CodeGroup>

***

## Add Timestamp

Add a timestamp watermark to the screenshot for audit trails or monitoring.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    addTimestamp: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', add_timestamp=True))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "addTimestamp": true}'
  ```
</CodeGroup>

***

## Proxy Routing

Route the browser through a specific country's IP to capture geo-specific or localized content.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    proxyCountry: 'de'
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', proxy_country='de'))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "proxyCountry": "de"}'
  ```
</CodeGroup>

***

## Delayed Screenshot

Wait a set number of seconds after page load before capturing. Useful for pages with animations or slow-loading widgets.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    delay: 3
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', delay=3))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "delay": 3}'
  ```
</CodeGroup>

***

## Disable Animations

Freeze CSS animations and transitions before capturing. Produces cleaner, more consistent screenshots.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    disableAnimations: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', disable_animations=True))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "disableAnimations": true}'
  ```
</CodeGroup>

***

## Inline Response

By default, the endpoint returns a CDN URL pointing to the generated image (see `data` in the response above). Set `inline: true` to receive the image data directly in the response instead, which can save a round trip if you don't need the image hosted.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.screenshot({
    url: 'https://example.com',
    inline: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.screenshot(ScreenshotDto(url='https://example.com', inline=True))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/screenshot \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "inline": true}'
  ```
</CodeGroup>

***

## All Parameters

| Parameter               | Type                        | Default   | Description                                                |
| ----------------------- | --------------------------- | --------- | ---------------------------------------------------------- |
| `url`                   | string                      | required  | Target URL                                                 |
| `device`                | `desktop` \| `mobile`       | `desktop` | Device to emulate                                          |
| `type`                  | `png` \| `jpeg` \| `webp`   | `png`     | Image format                                               |
| `fullPage`              | boolean                     | `false`   | Capture full scrollable page                               |
| `selector`              | string                      | —         | CSS selector for the element to capture                    |
| `fallbackToFullPage`    | boolean                     | `false`   | Fall back to a full-page capture if `selector` isn't found |
| `blockAds`              | boolean                     | `true`    | Block ads before capturing                                 |
| `hideCookie`            | boolean                     | `true`    | Remove cookie consent banners                              |
| `skipCaptcha`           | boolean                     | `true`    | Attempt to bypass CAPTCHAs                                 |
| `proxyCountry`          | string                      | —         | Route browser through country ISO code                     |
| `viewportWidth`         | number                      | —         | Viewport width in pixels (320–3840)                        |
| `viewportHeight`        | number                      | —         | Viewport height in pixels (240–2160)                       |
| `pageHeight`            | number                      | —         | Page height for partial screenshot (100–5000)              |
| `captureBeyondViewport` | boolean                     | —         | Capture content beyond viewport                            |
| `scaleFactor`           | number                      | —         | Device pixel ratio (0.1–5). Use 2–3 for Retina             |
| `theme`                 | `light` \| `dark` \| `auto` | `auto`    | Color scheme                                               |
| `quality`               | number                      | —         | Image quality 10–100 (JPEG/WebP only)                      |
| `delay`                 | number                      | —         | Seconds to wait after page load (0–10)                     |
| `highlightLinks`        | boolean                     | `false`   | Draw borders around links/buttons (AI vision)              |
| `removeBackground`      | boolean                     | `false`   | Remove page background (PNG only)                          |
| `disableAnimations`     | boolean                     | `false`   | Freeze CSS animations before capture                       |
| `addTimestamp`          | boolean                     | `false`   | Add timestamp watermark                                    |
| `inline`                | boolean                     | `false`   | Return image data inline instead of a CDN URL              |

## Credits

| Mode       | Credits |
| ---------- | ------- |
| Screenshot | 5       |

<CardGroup>
  <Card title="Node.js SDK" icon="npm" href="https://www.npmjs.com/package/@geekflare/api-node">
    `npm install @geekflare/api-node`
  </Card>

  <Card title="Python SDK" icon="python" href="https://pypi.org/project/geekflare-api/">
    `pip install geekflare-api`
  </Card>
</CardGroup>


# Search Guide
Source: https://docs.geekflare.com/guides/search

Search the web, news, or images and get structured results in JSON, Markdown, or HTML. Supports AI-grounded answers, content scraping, domain filtering, and time-based filtering.

The Search endpoint queries the web and returns ad-free results. It supports web, news, and image search with AI-grounded answers that synthesize results into a single cited response.

**Endpoint:** `POST https://api.geekflare.com/search`

<Info>
  Install the official SDK: `npm install @geekflare/api-node` or `pip install
      geekflare-api`
</Info>

***

## Basic Web Search

Search the web and get structured JSON results. Costs **2 credits**.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  import { GeekflareClient } from '@geekflare/api-node';

  const client = new GeekflareClient({ apiKey: 'YOUR_API_KEY' });
  const result = await client.search({ query: 'Nvidia stock performance' });
  console.log(result);

  ```

  ```python Python SDK theme={null}
  from geekflare_api.client import GeekflareClient
  from geekflare_api.models import SearchRequestDto

  with GeekflareClient(api_key='YOUR_API_KEY') as client:
      result = client.search(SearchRequestDto(query='best running shoes'))
      print(result)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "best running shoes"}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "best running shoes",
      "count": 10,
      "source": ["web"],
      "location": "us",
      "time": "any",
      "scrape": false,
      "scrapeLimit": 3,
      "test": { "id": "abc123" }
    },
    "data": [
      {
        "title": "Best Running Shoes of 2026 — Tested & Reviewed",
        "url": "https://example.com/best-running-shoes",
        "snippet": "We tested over 100 pairs to find the best running shoes for every type of runner...",
        "date": "Jan 15, 2025",
        "position": 1
      },
      {
        "title": "Top 10 Running Shoes for 2026",
        "url": "https://example2.com/running-shoes",
        "snippet": "From track to trail, here are the top running shoes this year...",
        "position": 2
      }
    ]
  }
  ```
</Accordion>

***

## News Search

Search recent news articles on any topic.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'AI news',
    source: 'news',
    limit: 5
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(query='AI news', source='news', limit=5))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "AI news", "source": "news", "limit": 5}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "AI news",
      "count": 5,
      "source": ["news"],
      "time": "any",
      "test": { "id": "abc123" }
    },
    "data": [
      {
        "title": "OpenAI releases new model with improved reasoning",
        "url": "https://techcrunch.com/2025/01/openai-new-model",
        "snippet": "OpenAI today announced a new model that significantly improves on reasoning tasks...",
        "date": "2 hours ago",
        "position": 1
      }
    ]
  }
  ```
</Accordion>

***

## Image Search

Search for images on any topic.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'golden gate bridge',
    source: 'images',
    limit: 5
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(query='golden gate bridge', source='images', limit=5))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "golden gate bridge", "source": "images", "limit": 5}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "golden gate bridge",
      "count": 5,
      "source": ["images"],
      "test": { "id": "abc123" }
    },
    "data": [
      {
        "title": "Golden Gate Bridge at Sunset",
        "imageUrl": "https://example.com/images/golden-gate.jpg",
        "sourceUrl": "https://example.com/golden-gate-bridge",
        "width": 1920,
        "height": 1080
      }
    ]
  }
  ```
</Accordion>

***

## Grounded Answer

Get an AI-synthesized answer with inline citations from search results. Ideal for RAG pipelines and AI agents. Costs **5 credits**.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'what is the Model Context Protocol',
    groundedAnswer: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(
      query='what is the Model Context Protocol',
      grounded_answer=True
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "what is the Model Context Protocol", "groundedAnswer": true}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "what is the Model Context Protocol",
      "count": 10,
      "source": ["web"],
      "test": { "id": "abc123" }
    },
    "data": {
      "answer": "The Model Context Protocol (MCP) is an open standard developed by Anthropic that allows AI assistants to connect with external data sources and tools [1]. It provides a universal interface for LLMs to interact with APIs, databases, and local services [2].",
      "sources": [
        { "title": "MCP Documentation", "url": "https://modelcontextprotocol.io", "position": 1 },
        { "title": "Anthropic Blog", "url": "https://www.anthropic.com/news/model-context-protocol", "position": 2 }
      ]
    }
  }
  ```
</Accordion>

***

## Search with Content Scraping

Scrape the top result pages and return their full content alongside search results. Costs **4 credits**.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'NestJS authentication guide',
    scrape: true,
    scrapeLimit: 3
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(
      query='NestJS authentication guide',
      scrape=True,
      scrape_limit=3
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "NestJS authentication guide", "scrape": true, "scrapeLimit": 3}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "NestJS authentication guide",
      "count": 10,
      "scrape": true,
      "scrapeLimit": 3,
      "test": { "id": "abc123" }
    },
    "data": [
      {
        "title": "NestJS Authentication with JWT",
        "url": "https://docs.nestjs.com/security/authentication",
        "snippet": "Authentication is an essential part of most applications...",
        "position": 1,
        "content": "# Authentication\n\nAuthentication is an essential part of most applications..."
      }
    ]
  }
  ```
</Accordion>

***

## Markdown Output

Return results as clean Markdown instead of JSON. Ideal for feeding directly into LLMs.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'TypeScript tips 2025',
    format: 'markdown'
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(query='TypeScript tips 2025', format='markdown'))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "TypeScript tips 2025", "format": "markdown"}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "query": "TypeScript tips 2025",
      "count": 10,
      "test": { "id": "abc123" }
    },
    "data": "1. [TypeScript 5.4 New Features](https://example.com)\n   - Use `satisfies` for safer type assertions...\n\n2. [TypeScript Tips for Large Codebases](https://example2.com)\n   - Prefer interface over type for objects..."
  }
  ```
</Accordion>

***

## Time Filtering

Limit results to a specific time range.

| Value      | Description                     |
| ---------- | ------------------------------- |
| `any`      | No time filter (default)        |
| `h`        | Past hour                       |
| `d`        | Past day                        |
| `w`        | Past week                       |
| `m`        | Past month                      |
| `y`        | Past year                       |
| `h2`, `d7` | Past 2 hours, past 7 days, etc. |

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'AI news',
    source: 'news',
    time: 'd'
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(query='AI news', source='news', time='d'))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "AI news", "source": "news", "time": "d"}'
  ```
</CodeGroup>

***

## Domain Filtering

Include or exclude specific domains from results.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'React hooks tutorial',
    includeDomains: ['reddit.com', 'stackoverflow.com'],
    excludeDomains: ['pinterest.com']
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(
      query='React hooks tutorial',
      include_domains=['reddit.com', 'stackoverflow.com'],
      exclude_domains=['pinterest.com']
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "React hooks tutorial",
      "includeDomains": ["reddit.com", "stackoverflow.com"],
      "excludeDomains": ["pinterest.com"]
    }'
  ```
</CodeGroup>

***

## Category Search

Search within a specific category for more relevant results.

| Category   | Description                         |
| ---------- | ----------------------------------- |
| `general`  | General web search (default)        |
| `code`     | Code snippets and technical content |
| `pdf`      | PDF documents                       |
| `research` | Academic and research papers        |
| `linkedin` | LinkedIn profiles and posts         |
| `wiki`     | Wikipedia content                   |

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.search({
    query: 'binary search tree implementation',
    category: 'code'
  });
  ```

  ```python Python SDK theme={null}
  result = client.search(SearchRequestDto(
      query='binary search tree implementation',
      category='code'
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/search \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "binary search tree implementation", "category": "code"}'
  ```
</CodeGroup>

***

## All Parameters

| Parameter        | Type                           | Default   | Description                                                         |
| ---------------- | ------------------------------ | --------- | ------------------------------------------------------------------- |
| `query`          | string                         | required  | Search query (max 2048 chars)                                       |
| `limit`          | number                         | `10`      | Number of results (1–100)                                           |
| `source`         | `web` \| `news` \| `images`    | `web`     | Search source                                                       |
| `format`         | `json` \| `markdown` \| `html` | `json`    | Output format                                                       |
| `time`           | string                         | `any`     | Time filter (`h`, `d`, `w`, `m`, `y`, `h2`, `d7`, etc.)             |
| `location`       | string                         | `us`      | Country code (ISO alpha-2)                                          |
| `category`       | string                         | `general` | Category (`general`, `code`, `pdf`, `research`, `linkedin`, `wiki`) |
| `includeDomains` | array                          | —         | Only return results from these domains                              |
| `excludeDomains` | array                          | —         | Exclude results from these domains                                  |
| `groundedAnswer` | boolean                        | `false`   | Return AI-synthesized answer with citations                         |
| `scrape`         | boolean                        | `false`   | Scrape content from top result URLs                                 |
| `scrapeLimit`    | number                         | `3`       | Number of URLs to scrape (1–10, requires `scrape: true`)            |

## Credits

| Mode                                     | Credits |
| ---------------------------------------- | ------- |
| Standard search                          | 2       |
| Search with scraping (`scrape: true`)    | 4       |
| Grounded answer (`groundedAnswer: true`) | 5       |

<CardGroup>
  <Card title="Node.js SDK" icon="npm" href="https://www.npmjs.com/package/@geekflare/api-node">
    `npm install @geekflare/api-node`
  </Card>

  <Card title="Python SDK" icon="python" href="https://pypi.org/project/geekflare-api/">
    `pip install geekflare-api`
  </Card>
</CardGroup>


# Web Scraping Guide
Source: https://docs.geekflare.com/guides/web-scraping

Extract full page content from any URL as Markdown, JSON, HTML, or LLM-ready text. Supports JavaScript rendering, stealth mode, proxy routing, and structured data extraction.

The Web Scraping endpoint scrapes any URL and returns clean page content in your preferred format. It handles JavaScript sites, blocks ads, rotates proxies, and can extract structured data using CSS or XPath selectors.

**Endpoint:** `POST https://api.geekflare.com/webscraping`

<Info>
  Install the official SDK: `npm install @geekflare/api-node` or `pip install
      geekflare-api`
</Info>

Now, you can connect Web Scraping with your AI Agents or LLMs to give context. Refer to our [MCP Server](/mcp) guide.

***

## Basic Scrape

Scrape a URL and get back LLM-ready content. Costs **1 credit**.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  import { GeekflareClient } from '@geekflare/api-node';

  const client = new GeekflareClient({ apiKey: 'YOUR_API_KEY' });
  const result = await client.webScrape({ url: 'https://example.com' });
  console.log(result);

  ```

  ```python Python SDK theme={null}
  from geekflare_api.client import GeekflareClient
  from geekflare_api.models import WebScrapeDto

  with GeekflareClient(api_key='YOUR_API_KEY') as client:
      result = client.web_scrape(WebScrapeDto(url='https://example.com'))
      print(result)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com"}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "url": "https://example.com",
      "device": "desktop",
      "format": ["html-llm"],
      "fileOutput": false,
      "blockAds": true,
      "renderJS": true,
      "stealth": false,
      "waitTime": 0,
      "extractionMode": "default",
      "test": { "id": "abc123" }
    },
    "data": "# Example Domain\n\nThis domain is for use in illustrative examples..."
  }
  ```
</Accordion>

***

## JavaScript Rendering

By default, `renderJS` is automatic: Geekflare first fetches the page without a browser, and only falls back to full JavaScript rendering if the page actually needs it. You don't need to choose between "lite" and "standard" scraping, the API detects it for you at no extra cost.

Set `renderJS: true` to always force full JavaScript rendering (skip the auto-detect and go straight to a headless browser), or `renderJS: false` to always skip rendering, even if the page would otherwise need it.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com',
    renderJS: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(url='https://example.com', render_js=True))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "renderJS": true}'
  ```
</CodeGroup>

<Info>
  Leave `renderJS` unset for the best default experience. Only set it
  explicitly when you already know a page requires (or doesn't require)
  JavaScript and want to skip the auto-detection round trip.
</Info>

***

## Output Formats

Choose one or more output formats. You can request up to 3 formats in a single call.

| Format         | Description                                 |
| -------------- | ------------------------------------------- |
| `html`         | Raw HTML                                    |
| `markdown`     | Clean Markdown                              |
| `json`         | Structured JSON                             |
| `html-llm`     | HTML stripped for LLM consumption (default) |
| `markdown-llm` | Markdown stripped for LLM consumption       |
| `text`         | Plain text                                  |
| `text-llm`     | Plain text stripped for LLM consumption     |

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com',
    format: ['markdown', 'html', 'text']
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com',
      format=['markdown', 'html', 'text']
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "format": ["markdown", "html", "text"]}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "url": "https://example.com",
      "format": ["markdown", "html", "text"],
      "test": { "id": "abc123" }
    },
    "data": {
      "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples...",
      "html": "<!DOCTYPE html><html><head><title>Example Domain</title>...",
      "text": "Example Domain\n\nThis domain is for use in illustrative examples..."
    }
  }
  ```
</Accordion>

***

## File Output

Get a CDN URL instead of inline content. Useful for large pages or when you need to store the result.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com',
    format: ['markdown'],
    fileOutput: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com',
      format=['markdown'],
      file_output=True
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "format": ["markdown"], "fileOutput": true}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "url": "https://example.com",
      "format": ["markdown"],
      "fileOutput": true,
      "test": { "id": "abc123" }
    },
    "data": "https://cdn.geekflare.com/tests/webscraping/ZuyhINuAZPQQabbN.md"
  }
  ```
</Accordion>

***

## Stealth Mode

Bypass bot detection on protected pages. Slower but more reliable on heavily guarded sites.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com',
    stealth: true
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(url='https://example.com', stealth=True))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "stealth": true}'
  ```
</CodeGroup>

***

## Wait Time

Add a delay after page load to capture lazy-loaded content or bypass bot checks.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com',
    waitTime: 2.5
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(url='https://example.com', wait_time=2.5))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "waitTime": 2.5}'
  ```
</CodeGroup>

***

## Proxy Routing

Web Scraping supports three proxy modes via `proxyMode`:

| Mode    | Behavior                                                                                                           |
| ------- | ------------------------------------------------------------------------------------------------------------------ |
| `false` | Never uses a proxy, even if the request would otherwise be blocked. **(default)**                                  |
| `auto`  | Tries the request without a proxy first, and automatically retries through a proxy if the site blocks the request. |
| `true`  | Always routes the request through a proxy.                                                                         |

Combine `proxyMode: true` (or `auto`, when a proxy ends up being used) with `proxyCountry` to route through a specific country's IP address — useful for bypassing geo-blocks or scraping region-specific content.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com',
    proxyMode: true,
    proxyCountry: 'gb'
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com',
      proxy_mode=True,
      proxy_country='gb'
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "proxyMode": true, "proxyCountry": "gb"}'
  ```
</CodeGroup>

<Info>
  Proxy modes apply to the Web Scraping endpoint only. Other endpoints that
  support proxy routing (Screenshot, Lighthouse, etc.) still use
  `proxyCountry` alone — see [Using Proxies](/using-proxies).
</Info>

***

## Device Emulation

Emulate a mobile device to scrape mobile-specific content.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com',
    device: 'mobile'
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(url='https://example.com', device='mobile'))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "device": "mobile"}'
  ```
</CodeGroup>

***

## Structured Extraction — CSS Schema

Extract specific fields from a page using CSS selectors. Returns structured JSON.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/products',
    format: ['json'],
    extractionMode: 'cssSchema',
    extractionSchema: {
      name: 'Product Schema',
      baseSelector: '.product',
      fields: [
        { name: 'title', selector: 'h1.product-title', type: 'text' },
        { name: 'price', selector: '.price', type: 'text' },
        { name: 'link', selector: 'a.product-link', type: 'attr', attribute: 'href' }
      ]
    }
  });
  ```

  ```python Python SDK theme={null}
  from geekflare_api.models import WebScrapeDto, ExtractionSchemaDto, SelectorExtractionFieldDto

  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/products',
      format=['json'],
      extraction_mode='cssSchema',
      extraction_schema=ExtractionSchemaDto(
          name='Product Schema',
          base_selector='.product',
          fields=[
              SelectorExtractionFieldDto(name='title', selector='h1.product-title', type='text'),
              SelectorExtractionFieldDto(name='price', selector='.price', type='text'),
          ]
      )
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/products",
      "format": ["json"],
      "extractionMode": "cssSchema",
      "extractionSchema": {
        "name": "Product Schema",
        "baseSelector": ".product",
        "fields": [
          {"name": "title", "selector": "h1.product-title", "type": "text"},
          {"name": "price", "selector": ".price", "type": "text"}
        ]
      }
    }'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "url": "https://example.com/products",
      "format": ["json"],
      "extractionMode": "cssSchema",
      "test": { "id": "abc123" }
    },
    "data": [
      { "title": "Running Shoe Pro", "price": "$129.99", "link": "/products/running-shoe-pro" },
      { "title": "Trail Runner X", "price": "$89.99", "link": "/products/trail-runner-x" }
    ]
  }
  ```
</Accordion>

***

## Structured Extraction — XPath Schema

Use XPath expressions for more precise extraction.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/articles',
    format: ['json'],
    extractionMode: 'xpathSchema',
    extractionSchema: {
      name: 'Article Schema',
      baseSelector: "//div[@class='article']",
      fields: [
        { name: 'title', selector: './/h1/text()', type: 'text' },
        { name: 'author', selector: ".//span[@class='author']/text()", type: 'text' }
      ]
    }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/articles',
      format=['json'],
      extraction_mode='xpathSchema',
      extraction_schema=ExtractionSchemaDto(
          name='Article Schema',
          base_selector="//div[@class='article']",
          fields=[
              SelectorExtractionFieldDto(name='title', selector='.//h1/text()', type='text'),
              SelectorExtractionFieldDto(name='author', selector=".//span[@class='author']/text()", type='text'),
          ]
      )
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/articles",
      "format": ["json"],
      "extractionMode": "xpathSchema",
      "extractionSchema": {
        "name": "Article Schema",
        "baseSelector": "//div[@class='\''article'\'']",
        "fields": [
          {"name": "title", "selector": ".//h1/text()", "type": "text"}
        ]
      }
    }'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1778737930991,
    "apiStatus": "success",
    "apiCode": 200,
    "meta": {
      "url": "https://example.com/articles",
      "format": ["json"],
      "extractionMode": "xpathSchema",
      "test": { "id": "abc123" }
    },
    "data": [
      { "title": "How to Run Faster", "author": "Jane Smith" },
      { "title": "Best Trails in 2025", "author": "John Doe" }
    ]
  }
  ```
</Accordion>

***

## Default Extraction — Static Fields

Inject static metadata fields alongside scraped content.

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com',
    format: ['json'],
    extractionMode: 'default',
    extractionSchema: {
      name: 'Quick Fields',
      fields: [
        { title: 'Category', value: 'Electronics' },
        { title: 'Country', value: 'India' }
      ]
    }
  });
  ```

  ```python Python SDK theme={null}
  from geekflare_api.models import DefaultExtractionFieldDto

  result = client.web_scrape(WebScrapeDto(
      url='https://example.com',
      format=['json'],
      extraction_mode='default',
      extraction_schema=ExtractionSchemaDto(
          name='Quick Fields',
          fields=[
              DefaultExtractionFieldDto(title='Category', value='Electronics'),
              DefaultExtractionFieldDto(title='Country', value='India'),
          ]
      )
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com",
      "format": ["json"],
      "extractionMode": "default",
      "extractionSchema": {
        "name": "Quick Fields",
        "fields": [
          {"title": "Category", "value": "Electronics"},
          {"title": "Country", "value": "India"}
        ]
      }
    }'
  ```
</CodeGroup>

***

## AI Extraction

Ask AI to answer questions, extract structured data, or analyze the scraped page — summaries, sentiment, keywords, contact info, and more. AI requests always run against Markdown content; any `format` you set is ignored when `aiPrompt` is present. Costs **+6 credits** on top of the base scraping cost (7 total).

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.webScrape({
    url: 'https://example.com/products/wireless-headphones',
    aiPrompt: {
      type: 'prompt',
      query: 'What is the return policy?'
    }
  });
  ```

  ```python Python SDK theme={null}
  result = client.web_scrape(WebScrapeDto(
      url='https://example.com/products/wireless-headphones',
      ai_prompt={'type': 'prompt', 'query': 'What is the return policy?'}
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/webscraping \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com/products/wireless-headphones",
      "aiPrompt": {"type": "prompt", "query": "What is the return policy?"}
    }'
  ```
</CodeGroup>

<Info>
  AI Extraction supports 8 modes — open-ended questions, custom JSON Schema
  extraction, product data, category listings, summaries, contact info,
  sentiment analysis, and keyword/entity extraction. See the full [AI
  Extraction](/ai-extraction-web-scraping) guide for
  request/response examples of every mode.
</Info>

***

## All Parameters

| Parameter          | Type                                      | Default        | Description                                                                                                                        |
| ------------------ | ----------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `url`              | string                                    | required       | Target URL                                                                                                                         |
| `device`           | `desktop` \| `mobile`                     | `desktop`      | Device to emulate                                                                                                                  |
| `format`           | array                                     | `["html-llm"]` | Output format(s). Up to 3. Ignored if `aiPrompt` is set.                                                                           |
| `renderJS`         | boolean                                   | auto           | Execute JavaScript. Left unset, Geekflare auto-detects whether the page needs it. Set `true`/`false` to force rendering on or off. |
| `blockAds`         | boolean                                   | `true`         | Block ads during scrape                                                                                                            |
| `stealth`          | boolean                                   | `false`        | Bypass bot detection                                                                                                               |
| `waitTime`         | number                                    | `0`            | Seconds to wait after page load                                                                                                    |
| `fileOutput`       | boolean                                   | `false`        | Return CDN URL instead of inline data                                                                                              |
| `proxyMode`        | `false` \| `auto` \| `true`               | `false`        | Whether to route the request through a proxy. See [Proxy Routing](#proxy-routing).                                                 |
| `proxyCountry`     | string                                    | —              | Route through country ISO code (e.g. `us`, `gb`). Used when a proxy is active.                                                     |
| `extractionMode`   | `default` \| `cssSchema` \| `xpathSchema` | `default`      | Extraction mode (used when `format` includes `json`)                                                                               |
| `extractionSchema` | object                                    | —              | Schema for structured extraction (used when `format` includes `json`)                                                              |
| `aiPrompt`         | object                                    | —              | Ask AI to extract/analyze the page. See [AI Extraction](/ai-extraction-web-scraping). Adds +6 credits.                             |

## Credits

| Mode                                      | Credits |
| ----------------------------------------- | ------- |
| Web Scraping                              | 1       |
| Web Scraping + AI Extraction (`aiPrompt`) | 7       |

<CardGroup>
  <Card title="Node.js SDK" icon="npm" href="https://www.npmjs.com/package/@geekflare/api-node">
    `npm install @geekflare/api-node`
  </Card>

  <Card title="Python SDK" icon="python" href="https://pypi.org/project/geekflare-api/">
    `pip install geekflare-api`
  </Card>
</CardGroup>


# Geekflare Docs
Source: https://docs.geekflare.com/index



Your central docs for [Geekflare AI](https://geekflare.com/ai/) and [Geekflare API](https://geekflare.com/api/). Here you'll find comprehensive guides, API references, and tutorials to help you build faster.

Select a product below to dive into its dedicated documentation.

<CardGroup>
  <Card
    title="Geekflare AI"
    icon={<svg id="Layer_18" xmlns="http://www.w3.org/2000/svg" fill= "#ff4e00">


<path class="cls-1" d="M8.521,27.206c.005.036.006.073.013.108.011.05.03.099.046.148.015.045.026.091.044.134.016.037.039.071.058.107.028.052.054.104.087.152.004.006.006.012.01.018.013.018.031.031.044.048.052.066.107.128.169.185.03.027.06.051.092.076.057.044.116.083.179.119.034.019.066.039.101.055.071.033.146.059.222.081.029.008.056.02.085.026.106.024.215.038.328.038,0,0,0,0,0,0,0,0,0,0,0,0,0,0,.001,0,.002,0,.139,0,.272-.025.4-.061.03-.008.058-.017.088-.027.132-.046.256-.105.368-.184.004-.003.009-.004.014-.007l6.609-4.721h9.519c.828,0,1.5-.671,1.5-1.5v-4c0-.829-.672-1.5-1.5-1.5s-1.5.671-1.5,1.5v2.5h-8.5c-.006,0-.012.002-.018.002-.064,0-.127.01-.19.019-.035.005-.071.006-.105.013-.05.011-.099.03-.149.046-.045.015-.09.026-.133.044-.036.016-.07.039-.106.058-.052.028-.105.054-.153.087-.006.004-.012.006-.018.01l-4.628,3.306v-2.085c0-.829-.672-1.5-1.5-1.5h-3.5v-12h9.5c.828,0,1.5-.671,1.5-1.5s-.672-1.5-1.5-1.5H5c-.828,0-1.5.671-1.5,1.5v15c0,.829.672,1.5,1.5,1.5h3.5v3.5c0,.006.002.012.002.019,0,.063.01.125.019.187Z"/>
<path class="cls-1" d="M29,11c0-.55-.45-1-1-1-2.21,0-4-1.79-4-4,0-.55-.45-1-1-1s-1,.45-1,1c0,2.21-1.79,4-4,4-.55,0-1,.45-1,1s.45,1,1,1c2.21,0,4,1.79,4,4,0,.55.45,1,1,1s1-.45,1-1c0-2.21,1.79-4,4-4,.55,0,1-.45,1-1Z"/>
</svg>}
    href="/ai"
  >
    Learn about Geekflare AI.
  </Card>

  <Card
    title="Geekflare API"
    icon={<svg id="Layer_18" xmlns="http://www.w3.org/2000/svg" fill= "#ff4e00">

<path class="cls-1" d="M28,7c-2.21,0-4-1.79-4-4,0-.55-.45-1-1-1s-1,.45-1,1c0,2.21-1.79,4-4,4-.55,0-1,.45-1,1s.45,1,1,1c2.21,0,4,1.79,4,4,0,.55.45,1,1,1s1-.45,1-1c0-2.21,1.79-4,4-4,.55,0,1-.45,1-1s-.45-1-1-1Z"/>
<path class="cls-1" d="M27,24.184v-2.598l-5.514-5.514c.02-.408-.114-.821-.425-1.133-.586-.586-1.535-.586-2.121,0l-2.939,2.939-5.879-5.879,6.939-6.939c.586-.586.586-1.535,0-2.121s-1.535-.586-2.121,0L6.939,10.939c-.586.586-.586,1.535,0,2.121l3.293,3.293-4.232,4.232v3.598c-1.163.413-2,1.512-2,2.816,0,1.657,1.343,3,3,3s3-1.343,3-3c0-1.304-.837-2.403-2-2.816v-2.77l3.646-3.646,3.293,3.293c.018.018.042.023.061.04v2.083c-1.163.413-2,1.512-2,2.816,0,1.657,1.343,3,3,3s3-1.343,3-3c0-1.304-.837-2.403-2-2.816v-2.083c.019-.017.043-.022.061-.04l3.293-3.293,4.646,4.646v1.77c-1.163.413-2,1.512-2,2.816,0,1.657,1.343,3,3,3s3-1.343,3-3c0-1.304-.837-2.403-2-2.816Z"/>
</svg>}
    href="/intro"
  >
    Explore all available endpoints.
  </Card>
</CardGroup>


# API Integrations & SDKs
Source: https://docs.geekflare.com/integrations

Official SDKs and integrations for Geekflare.

<CardGroup>
  <Card title="Zapier" icon="bolt" href="https://zapier.com/apps/geekflare/integrations">
    Automate workflows by connecting Geekflare to thousands of apps.
  </Card>

  <Card title="Make" icon="diagram-project" href="https://www.make.com/en/integrations/geekflare">
    Build multi-step automation scenarios with drag-and-drop modules.
  </Card>

  <Card title="Node.js/TypeScript SDK" icon="node-js" href="https://www.npmjs.com/package/@geekflare/api-node">
    Official npm package with built-in type definitions.
  </Card>

  <Card title="Python SDK" icon="python" href="https://pypi.org/project/geekflare-api/">
    Official pip package with a Pythonic interface.
  </Card>
</CardGroup>

## Zapier

Connect Geekflare to thousands of apps using Zapier to automate your workflows. You can set up Zaps to trigger website screenshots, extract web data, or run search queries, and automatically send the results directly to your CRM, Slack, Google Sheets, or email.

## Make

Integrate Geekflare into your visual Make scenarios. Our Make integration allows you to drag and drop Geekflare modules to build multi-step automations. Combine our scraping, search, and screenshot capabilities with hundreds of supported apps and services.

## Node.js / TypeScript SDK

Our official Node.js SDK provides a reliable way to interact with Geekflare in your JavaScript or TypeScript applications. Available via npm, the SDK includes built-in type definitions.

## Python SDK

The official Geekflare Python SDK allows you to quickly integrate our suite of APIs into your Python backends, data pipelines, or automation scripts. Available via pip, the SDK provides a Pythonic interface that eliminates boilerplate HTTP request code so you can focus on processing your scraping, search, and screenshot data.


# Introduction
Source: https://docs.geekflare.com/intro

Welcome to the Geekflare Documentation.

## What is Geekflare?

[Geekflare](https://geekflare.com) provides a suite of REST APIs for Scraping, Search, Data Extraction, Screenshots, DNS lookups, and other essential web utilities. Every request consumes credits based on the endpoint and options used. See [Credit Mapping](/api-credit-mapping) for the full breakdown.

## Getting started

Getting up and running with Geekflare is simple. Create a free account (no credit card required) to generate your API key. Once you have your key, you can test endpoints using our [Interactive Playground](https://dash.geekflare.com/playground).

<Card title="Get your API key" icon="key" href="https://auth.geekflare.com/register?service=geekflare_api">
  Sign up for a free account to generate your key.
</Card>

## API Protocol

Geekflare provides a RESTful API. It is accessed via HTTPs and ensures that all data sent and received is formatted as JSON.

## Integration Methods

Integrate Geekflare into your applications using REST API, SDKs, MCP or No-Code platforms.

<CardGroup>
  <Card title="REST API" icon="code" href="/endpoint/reference">
    Standard HTTPS endpoints returning JSON payloads. Compatible with OpenAPI specifications.
  </Card>

  <Card title="SDKs" icon="cubes" href="/integrations">
    Accelerate development with our official Node.js/TypeScript and Python packages.
  </Card>

  <Card title="No-Code" icon="wand-magic-sparkles" href="/integrations">
    Connect Geekflare to thousands of apps via Zapier and Make without writing a single line of code.
  </Card>

  <Card title="MCP Server" icon="robot" href="/mcp">
    Plug Geekflare into AI IDEs and LLM agents to give them web scraping, search, screenshot and other tools.
  </Card>

  <Card title="Postman Collection" icon="paper-plane" href="https://www.postman.com/geekflare/geekflare-api/collection/q0iiukn/geekflare">
    Fork our Postman collection to test every endpoint without writing any code.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Interactive Playground" icon="terminal" href="https://dash.geekflare.com/playground">
    Use all our APIs directly in your browser.
  </Card>
</CardGroup>

## Rate Limits

Rate limits depend on your subscription plan. If you exceed your limit, the API returns an `HTTP 429 Too Many Requests` error — see [Rate Limit Exceeded](/rate-limit-exceeded) for how to handle this gracefully.

| Plan       | Requests per second (RPS) |
| ---------- | ------------------------- |
| Free       | 1                         |
| Starter    | 5                         |
| Growth     | 10                        |
| Business   | 25                        |
| Enterprise | Custom, up to 1,000       |

## Proxy & Geolocation

Several Geekflare endpoints (such as Scraping, Site Status, PDF Generator, Load time, etc.) support request routing via specific locations. To use this, pass the target country code in the `proxyCountry` parameter. [View supported APIs](/using-proxies)

**Note:** Using proxies incurs additional credit costs. We recommend using this feature only when geolocation is required.

<Info>Proxy is available to paid users only.</Info>

## Request

### Authentication

Every request must include your API key in an `x-api-key` request header:

```bash theme={null}
x-api-key YOUR-API-KEY
```

<Info>
  See our [Security page](https://geekflare.com/security/) for details on how
  we protect your API keys and data.
</Info>

### Base URL

For all the endpoints listed in this documentation, the base URL is:

```
https://api.geekflare.com
```

## Response

The API response follows some common formats for the sake of clarity and consistency. Depending on the request status, the response structures are as given below. See the [Error Code Reference](/error-codes) for the complete list.

### Success Response

On successful processing of a request, the API returns a response in the following format:

```json theme={null}
{
  "timestamp": 1610796547300,
  "apiStatus": "success",
  "apiCode": 200,
  "message": "An overview message.",
  "meta": {
    "url": "https://example.com"
  },
  "data": []
}
```

<Check>200 - Success</Check>

### Missing API Key

When no API key is provided in the request, the following response structure is returned:

```json theme={null}
{
  "apiCode": 401,
  "message": "Missing x-api-key header"
}
```

<Warning>401 - Unauthorized. See [Unauthorized](/unauthorized) for how to resolve this.</Warning>

### Invalid API Key

When an invalid or incorrect API key is provided:

```json theme={null}
{
  "apiCode": 401,
  "message": "Invalid x-api-key"
}
```

<Warning>401 - Unauthorized. See [Unauthorized](/unauthorized) for how to resolve this.</Warning>

### Forbidden Response

If you are under a free plan and try to access a paid-only API like Port Scanner, it would return an error in the following format:

```json theme={null}
{
  "timestamp": 1658254283953,
  "apiStatus": "failure",
  "apiCode": 403,
  "message": "You are not allowed to access. This is available to premium plan only."
}
```

<Warning>403 - Forbidden. See [Forbidden](/forbidden) for how to resolve this.</Warning>

### Not Found Response

If a wrong endpoint or wrong request type (POST instead of GET, for example) is provided, the API returns an error in the following format:

```json theme={null}
{
  "timestamp": 1657208461046,
  "apiStatus": "failure",
  "apiCode": 404,
  "message": "API not found.",
  "meta": {
    "method": "POST",
    "endpoint": "/helloworld"
  }
}
```

<Warning>404 - Not Found</Warning>

## Next Steps

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Make your first API call in your language or framework of choice.
  </Card>
</CardGroup>


# Lighthouse in Advanced Mode
Source: https://docs.geekflare.com/lighthouse-advanced

How to run Lighthouse API in advanced mode

Geekflare Lighthouse API can accept the following parameters.

* `--screenEmulation`
* `--screenEmulation.disabled`
* `--emulatedUserAgent`
* `--only-audits`
* `--only-categories`
* `--throttling-method`
* `--extra-headers`
* `--chrome-flags`
* `--no-emulatedUserAgent`
* `--blocked-url-patterns`
* `--output`
* `--preset`

In order to use these parameters, pass them in a `parameters` JSON array in the request body payload.

Let's explore some of the examples.

**Run only SEO audit**

```json theme={null}
{
    "url": "https://example.com/",
    "parameters": [
      "--only-categories=seo"
  ]
}
```

**Save output in HTML format**

```json theme={null}
{
    "url": "https://example.com/",
    "parameters": [
      "--output=html"
  ]
}
```

**Run a single audit**

```json theme={null}
{
    "url": "https://example.com/",
    "parameters": [
      "--only-audits=image-alt"
  ]
}
```

**Run Lighthouse using Proxy**

```json theme={null}
{
    "url": "https://example.com/",
    "proxyCountry": "fr",
    "parameters": [
      "--only-categories=seo"
  ]
}
```

**Disable Mobile Emulation and Throttling**

```json theme={null}
{
    "url": "https://example.com/",
    "device": "desktop",
    "parameters": [
      "--output=html",     
      "--screenEmulation.disabled",      
      "--no-emulatedUserAgent",     
      "--throttling-method=provided"
  ]
}
```

**You can also use multiple parameters**

```json theme={null}
{
    "url": "https://example.com/",
    "parameters": [
      "--only-categories=seo",
      "--output=html"
  ]
}
```


# Load Time: Multi-Location Testing
Source: https://docs.geekflare.com/load-time-multi-location

Test website load time and reachability from multiple countries in a single Load Time API request.

By default, [Load Time](/endpoint/load-time) tests a URL from Geekflare's US server. Pass `targetCountries` to also test reachability from up to **3 additional locations** via proxy, alongside the default US test — useful for confirming a site loads correctly for visitors in different regions, or diagnosing geo-specific outages. Costs a flat **8 credits** per request, regardless of how many locations (1–3) you test.

## How It Works

For each request with `targetCountries` set, Geekflare tests the URL from:

1. The default **US server** (no proxy)
2. Each country listed in `targetCountries`, routed through a proxy in that location

The response reports whether the site was reachable from every tested location, both as an overall summary and a per-location breakdown.

## Testing from Multiple Locations

Pass an array of up to 3 ISO alpha-2 country codes in `targetCountries`:

<CodeGroup>
  ```typescript Node.js SDK theme={null}
  const result = await client.loadTime({
    url: 'https://example.com',
    targetCountries: ['gb', 'ca']
  });
  ```

  ```python Python SDK theme={null}
  result = client.load_time(LoadTimeDto(
      url='https://example.com',
      target_countries=['gb', 'ca']
  ))
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.geekflare.com/loadtime \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "targetCountries": ["gb", "ca"]}'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "timestamp": 1785938505112,
    "apiStatus": "success",
    "apiCode": 200,
    "message": "Reachable from all 3 tested locations.",
    "meta": {
      "url": "https://example.com",
      "test": { "id": "cc20cf78-3bfb-4ad4-8e75-4be137f7fb3d" },
      "targetCountries": ["us", "gb", "ca"],
      "followRedirect": true
    },
    "summary": {
      "reachable": ["us", "gb", "ca"]
    },
    "locations": [
      { "location": "us", "countryName": "United States", "status": "reachable", "data": {} },
      { "location": "gb", "countryName": "Great Britain", "status": "reachable", "data": {} },
      { "location": "ca", "countryName": "Canada", "status": "reachable", "data": {} }
    ]
  }
  ```
</Accordion>

<Info>
  `meta.targetCountries` in the response always includes the default `us`
  location plus every country you requested. So a 2-country request
  returns 3 tested locations total.
</Info>

## Without `targetCountries`

If you omit `targetCountries`, Load Time behaves as before: a single test from the US server, with the full [timing breakdown](/endpoint/load-time) (DNS, connect, TLS, timings, headers, etc.) returned directly in `data`.

## Next Steps

<CardGroup>
  <Card title="Load Time Reference" icon="clock" href="/endpoint/load-time">
    Full parameter and response reference.
  </Card>

  <Card title="Using Proxies" icon="globe" href="/using-proxies">
    See which other endpoints support proxy routing.
  </Card>
</CardGroup>


# Amazon Q
Source: https://docs.geekflare.com/mcp/amazon-q

Connect Geekflare MCP server to Amazon Q Developer for web scraping, search, screenshot, and DNS tools in your coding workflow.

[Amazon Q Developer](https://aws.amazon.com/q/developer/) is AWS's AI coding assistant, available as a VS Code and JetBrains extension. It supports MCP servers, letting you connect Geekflare tools for scraping, search, screenshots, and DNS lookups during development.

## Prerequisites

* Amazon Q Developer extension installed in VS Code or JetBrains
* Amazon Q Developer Pro subscription (MCP requires Pro)
* [Node.js](https://nodejs.org) installed (for local transport)

## Setup

Amazon Q Developer reads MCP configuration from a JSON file in your home directory.

Create or edit `~/.aws/amazonq/mcp.json`:

<Tabs>
  <Tab title="Remote URL (Recommended)">
    ```json theme={null}
    {
      "mcpServers": {
        "geekflare": {
          "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Local via npx">
    ```json theme={null}
    {
      "mcpServers": {
        "geekflare": {
          "command": "npx",
          "args": ["-y", "@geekflare/mcp"],
          "env": {
            "API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Replace `YOUR_API_KEY` with your Geekflare API key. Restart your editor after saving.

## Usage Examples

Open the Amazon Q chat panel in your editor and try:

**Scrape a webpage**

```
Scrape https://aws.amazon.com/lambda and extract the key features listed on the page.
```

**Search the web**

```
Search for "AWS Lambda cold start optimization" and summarize the top recommendations.
```

**Screenshot**

```
Take a screenshot of https://geekflare.com and describe the page layout.
```

**DNS lookup**

```
Look up the DNS records for amazonaws.com.
```


# BoltAI
Source: https://docs.geekflare.com/mcp/boltai

Connect Geekflare MCP server to BoltAI for scraping, search, screenshot, and DNS tools in your Mac AI assistant.

[BoltAI](https://boltai.com) is a native Mac AI assistant that supports MCP servers. With Geekflare connected, BoltAI can scrape pages, search the web, take screenshots, and look up DNS records in any conversation.

## Setup

<Steps>
  <Step title="Open BoltAI Preferences">
    Open BoltAI and go to **Preferences → MCP Servers** (or press `Cmd+,`).
  </Step>

  <Step title="Add a new MCP server">
    Click the **+** button to add a new server.
  </Step>

  <Step title="Configure the server">
    <Tabs>
      <Tab title="Remote URL (Recommended)">
        * **Name:** Geekflare
        * **Type:** Streamable HTTP
        * **URL:** `https://mcp.geekflare.com/YOUR_API_KEY/mcp`
      </Tab>

      <Tab title="Local via npx">
        * **Name:** Geekflare
        * **Type:** Command
        * **Command:** `npx`
        * **Arguments:** `-y @geekflare/mcp`
        * **Environment Variables:** `API_KEY=YOUR_API_KEY`
      </Tab>
    </Tabs>

    Replace `YOUR_API_KEY` with your Geekflare API key. Click **Save**.
  </Step>

  <Step title="Enable the server">
    Toggle the Geekflare server to **On**. The tools should appear in the BoltAI chat interface.
  </Step>
</Steps>

## Usage Examples

In any BoltAI conversation:

**Scrape a webpage**

```
Scrape https://example.com and summarize the main content.
```

**Search the web**

```
Search for "best Mac productivity apps" and return the top results.
```

**Screenshot**

```
Take a screenshot of https://nvidia.com and describe what you see.
```

**Metadata scraping**

```
Fetch the meta tags from https://geekflare.com and show the SEO title and description.
```


# Claude Code
Source: https://docs.geekflare.com/mcp/claude-code

Add Geekflare MCP server to Claude Code for scraping websites, searching the internet, and retrieving brand details in your terminal.

[Claude Code](https://docs.anthropic.com/claude-code) is Anthropic's agentic coding tool that runs in your terminal. With Geekflare MCP connected, Claude Code can scrape pages, run searches, and look up DNS records as part of any agentic coding task.

## Setup

<Tabs>
  <Tab title="Remote URL (Recommended)">
    ```bash theme={null}
    claude mcp add --transport http geekflare \
      https://mcp.geekflare.com/YOUR_API_KEY/mcp
    ```
  </Tab>

  <Tab title="Local via npx">
    ```bash theme={null}
    claude mcp add geekflare \
      -e API_KEY=YOUR_API_KEY \
      -- npx -y @geekflare/mcp
    ```
  </Tab>
</Tabs>

Replace `YOUR_API_KEY` with your Geekflare API key.

## Verify Installation

Run:

```bash theme={null}
claude mcp list
```

You should see `geekflare` in the list of configured MCP servers.

## Usage Examples

Claude Code automatically uses Geekflare tools when relevant. You can also prompt it explicitly.

### Scrape a Webpage

```bash theme={null}
claude "Scrape https://example.com and extract all links on the page."
```

### DNS Lookup

```bash theme={null}
claude "Look up the MX records for resend.com"
```

### Search the Web

```bash theme={null}
claude "Search for the latest UK news"
```

### Take a Screenshot

```bash theme={null}
claude "Take a screenshot of https://stripe.com/pricing and give me pricing for international payments."
```

## Remove the Server

```bash theme={null}
claude mcp remove geekflare
```


# Claude Desktop
Source: https://docs.geekflare.com/mcp/claude-desktop

Connect Geekflare to Claude Desktop using MCP to give web context, take a screenshot, run network test, and more.

[Claude Desktop](https://claude.ai/download) is Anthropic's native desktop app for Mac and Windows. With the Geekflare MCP server connected, Claude can use web scraping, search, DNS lookups, and screenshots as tools in any conversation.

<Info>A Claude **Pro plan** or higher is required to use more than one connector in Claude Desktop</Info>

## Setup

<Steps>
  <Step title="Add a custom connector">
    Open Claude Desktop and click the **+** button in the chat box.

    Select **Connectors** → **Add custom connector**.
  </Step>

  <Step title="Configure the Geekflare connector">
    Enter the following details:

    * **Name:** `Geekflare`
    * **Server URL:** `https://mcp.geekflare.com/YOUR_API_KEY/mcp`

    Replace `YOUR_API_KEY` with your Geekflare API key, then click **Add**.
  </Step>

  <Step title="Verify the connection">
    Open **Settings** → **Connectors** and select **Geekflare**.
  </Step>
</Steps>

If the connection is successful, the Geekflare connector appears in the Connectors list with its available tools. You can also manage tool permissions from the connector settings.

## Usage Examples

Once connected, ask Claude naturally in any conversation:

**Scrape a webpage**

```
Scrape https://news.ycombinator.com and give me a summary of the top stories.
```

**Search with grounded answer**

```
Search for "Claude MCP tutorial" and give me a grounded answer about what MCP is.
```

**Screenshot**

```
Take a screenshot of https://apple.com and describe the layout.
```

**Metadata scraping**

```
Fetch the meta tags from https://sonos.com and tell me the SEO title and description.
```

## Troubleshooting

**Unable to add multiple connectors** — A Claude Pro plan or higher is required to use more than one connector in Claude Desktop.

**Connection failed** — Verify that the server URL is correct and that you replaced `YOUR_API_KEY` with a valid Geekflare API key.

**Geekflare connector not available** — Open **Settings** → **Connectors** to confirm that the connector was added successfully. If it is not listed, add the connector again using the correct server URL.


# Cline
Source: https://docs.geekflare.com/mcp/cline

Connect Geekflare MCP server to Cline in VS Code for web scraping, search, screenshot, and DNS tools in your agentic coding workflow.

[Cline](https://github.com/cline/cline) is a VS Code extension that provides an autonomous AI coding agent. With Geekflare MCP connected, Cline can scrape pages, run searches, take screenshots, and look up DNS as part of any coding or research task.

## Setup

<Steps>
  <Step title="Open Cline MCP settings">
    In VS Code, click the Cline icon in the sidebar, then click the **MCP Servers** button (plug icon) at the top of the Cline panel.
  </Step>

  <Step title="Add the Geekflare server">
    Click **Edit MCP Settings** to open the config file, then add:

    <Tabs>
      <Tab title="Remote URL (Recommended)">
        ```json theme={null}
        {
          "mcpServers": {
            "geekflare": {
              "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp",
              "disabled": false
            }
          }
        }
        ```
      </Tab>

      <Tab title="Local via npx">
        ```json theme={null}
        {
          "mcpServers": {
            "geekflare": {
              "command": "npx",
              "args": ["-y", "@geekflare/mcp"],
              "env": {
                "API_KEY": "YOUR_API_KEY"
              },
              "disabled": false
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    Replace `YOUR_API_KEY` with your Geekflare API key.
  </Step>

  <Step title="Verify connection">
    The Geekflare server should appear in the MCP Servers list with a green status indicator. Click it to see all available tools.
  </Step>
</Steps>

## Usage Examples

Type directly in the Cline chat panel:

**Scrape a webpage**

```
Scrape https://example.com and extract all the headings and paragraph text.
```

**Screenshot**

```
Take a screenshot of https://shopify.com and describe the above-the-fold message.
```

**Search with grounded answer**

```
Search for "React Server Components best practices" and synthesize a grounded answer.
```

**DNS lookup**

```
Look up the DNS records for stripe.com.
```


# Cursor
Source: https://docs.geekflare.com/mcp/cursor

Connect Geekflare to Cursor using MCP to give the AI agent web scraping, search, screenshot, and DNS tools.

[Cursor](https://cursor.com) is an AI-powered code editor. With the Geekflare MCP server connected, Cursor's agent can scrape pages, run searches, take screenshots, and look up DNS records directly from your editor.

## Setup

<Tabs>
  <Tab title="Remote URL (Recommended)">
    No installation required. Open **Cursor Settings → MCP** and add:

    ```json theme={null}
    {
      "mcpServers": {
        "geekflare": {
          "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp"
        }
      }
    }
    ```

    Replace `YOUR_API_KEY` with your Geekflare API key.
  </Tab>

  <Tab title="Local via npx">
    Requires [Node.js](https://nodejs.org) installed locally.

    Open **Cursor Settings → MCP** and add:

    ```json theme={null}
    {
      "mcpServers": {
        "geekflare": {
          "command": "npx",
          "args": ["-y", "@geekflare/mcp"],
          "env": {
            "API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

After saving, click **Refresh** in the MCP panel. You should see the Geekflare tools listed.

<Info>
  Cursor MCP support requires version 0.45.6 or later. Update via **Help → Check
  for Updates**.
</Info>

## Usage Examples

Open Cursor's Composer (`Cmd+L` / `Ctrl+L`), switch to **Agent** mode, and try:

**Scrape a webpage**

```
Scrape https://example.com and summarize the main content in bullet points.
```

**Search the web**

```
Search for Nvidia’s stock performance and explain the main reasons for the trend.
```

**Take a screenshot**

```
Take a screenshot of https://stripe.com and tell me what you see.
```

**DNS lookup**

```
Look up DNS records for openai.com
```


# MCP Server
Source: https://docs.geekflare.com/mcp/index

Connect Geekflare to AI assistants and coding tools using the Model Context Protocol (MCP).

The Geekflare MCP server exposes all Geekflare tools — web scraping, search, screenshots, DNS lookups, and more directly inside AI assistants and coding tools that support the [Model Context Protocol](https://modelcontextprotocol.io).

Once connected, you can ask your AI assistant to scrape a page, search the internet, or check DNS records without leaving your editor or chat interface.

## Connection Methods

<CardGroup>
  <Card title="Remote URL" icon="globe">
    Point your client directly at the hosted MCP
    server. `https://mcp.geekflare.com/{API_KEY}/mcp`
  </Card>

  <Card title="Local via npx" icon="terminal">
    Run the MCP server locally using Node.js. No global install needed. `bash
            npx -y @geekflare/mcp `
  </Card>
</CardGroup>

## Available Tools

| Tool            | Description                                                        |
| --------------- | ------------------------------------------------------------------ |
| `webScrape`     | Scrape full page content — Markdown, HTML, JSON, or LLM-ready text |
| `metaScrape`    | Extract meta tags, Open Graph, and Twitter card data               |
| `screenshot`    | Capture full-page screenshots with ad blocking and CAPTCHA bypass  |
| `search`        | Web, news, and image search with optional AI-grounded answers      |
| `dnsRecord`     | Look up A, AAAA, CNAME, MX, TXT, and other DNS records             |
| `siteStatus`    | Check if a site is up or down from any location                    |
| `redirectCheck` | Trace the full redirect chain of a URL                             |
| `brokenLink`    | Find all broken links on a webpage                                 |
| `url2Pdf`       | Convert any URL to a downloadable PDF                              |
| `openPorts`     | Scan open ports on a host                                          |
| `tlsScan`       | Inspect TLS/SSL configuration and certificate details              |
| `loadTime`      | Measure full page load time from any location                      |
| `ttfb`          | Measure Time To First Byte (TTFB)                                  |
| `httpHeader`    | Retrieve HTTP response headers                                     |
| `httpProtocol`  | Detect HTTP/1.1, HTTP/2, and HTTP/3 support                        |
| `mixedContent`  | Find HTTP resources loaded on HTTPS pages                          |
| `dnsSec`        | Check DNSSEC configuration                                         |
| `mtr`           | Run MTR network diagnostic tests                                   |
| `ping`          | Ping a host and return latency                                     |
| `lighthouse`    | Run Lighthouse audits for performance, SEO, and accessibility      |

## Client Guides

<CardGroup>
  <Card title="Cursor" icon="arrow-pointer" href="/mcp/cursor" />

  <Card title="Claude Desktop" icon="robot" href="/mcp/claude-desktop" />

  <Card title="Claude Code" icon="terminal" href="/mcp/claude-code" />

  <Card title="Devin Desktop" icon="wind" href="/mcp/windsurf" />

  <Card title="VS Code" icon="code" href="/mcp/vscode" />

  <Card title="Cline" icon="brackets-curly" href="/mcp/cline" />

  <Card title="Roo Code" icon="kangaroo" href="/mcp/roo-code" />

  <Card title="Zed" icon="bolt" href="/mcp/zed" />

  <Card title="n8n" icon="diagram-project" href="/mcp/n8n" />

  <Card title="BoltAI" icon="bolt" href="/mcp/boltai" />

  <Card title="LM Studio" icon="brain" href="/mcp/lm-studio" />

  <Card title="Amazon Q" icon="amazon" href="/mcp/amazon-q" />

  <Card title="Others" icon="ellipsis" href="/mcp/others" />
</CardGroup>

## Test Your Connection

Use the official MCP Inspector to verify your server is running and tools are accessible.

**Option 1 — Remote server**

```bash theme={null}
npx @modelcontextprotocol/inspector https://mcp.geekflare.com/YOUR_API_KEY/mcp
```

**Option 2 — Local server**

```bash theme={null}
API_KEY=YOUR_API_KEY npx @modelcontextprotocol/inspector npx @geekflare/mcp
```

This opens a browser UI at `http://localhost:5173` where you can:

1. Click **Connect** to establish the connection
2. Go to the **Tools** tab to see all 20 available tools
3. Click any tool and run it with a test URL to verify it works

<Info>
  Replace `YOUR_API_KEY` with your Geekflare API key. Get one at
  [geekflare.com/api/](https://geekflare.com/api/).
</Info>

## Get Your API Key

<Card title="Get your API key" icon="key" href="https://auth.geekflare.com/register?service=geekflare_api">
  Sign up for a free account to generate your key.
</Card>


# LM Studio
Source: https://docs.geekflare.com/mcp/lm-studio

Connect Geekflare MCP server to LM Studio to give local LLMs web scraping, search, screenshot, and DNS tools.

[LM Studio](https://lmstudio.ai) lets you run large language models locally on your machine. With MCP support (available from LM Studio 0.3.6+), you can connect Geekflare tools to any local model, giving it the ability to scrape pages, search the web, take screenshots, and look up DNS.

## Setup

<Steps>
  <Step title="Open the Developer settings">
    In LM Studio, go to **Settings → Developer** and enable **MCP Servers**.
  </Step>

  <Step title="Edit the MCP config file">
    LM Studio uses a JSON config file. Open it via **Settings → Developer → Edit MCP Config** and add:

    <Tabs>
      <Tab title="Remote URL (Recommended)">
        ```json theme={null}
        {
          "mcpServers": {
            "geekflare": {
              "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp"
            }
          }
        }
        ```
      </Tab>

      <Tab title="Local via npx">
        Requires [Node.js](https://nodejs.org) installed locally.

        ```json theme={null}
        {
          "mcpServers": {
            "geekflare": {
              "command": "npx",
              "args": ["-y", "@geekflare/mcp"],
              "env": {
                "API_KEY": "YOUR_API_KEY"
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    Replace `YOUR_API_KEY` with your Geekflare API key. Save the file.
  </Step>

  <Step title="Restart LM Studio">
    Restart LM Studio to load the new MCP server. Open a chat and verify the tools appear in the tool list.
  </Step>
</Steps>

## Usage Examples

In the LM Studio chat with any local model:

**Scrape a webpage**

```
Scrape https://example.com and extract the main content as markdown.
```

**Search the web**

```
Search for "LLM fine-tuning guide" and summarize the top results.
```

**Screenshot**

```
Take a screenshot of https://lmstudio.ai and tell me what you see.
```

**DNS lookup**

```
Look up the A and MX records for lmstudio.ai.
```

<Info>
  Tool calling capability depends on the local model you are using. Models with
  strong function-calling support (e.g. Qwen, Mistral, Llama 3.1+) will use
  Geekflare tools more reliably.
</Info>


# n8n
Source: https://docs.geekflare.com/mcp/n8n

Connect Geekflare MCP server to n8n to use web scraping, search, screenshot, and DNS tools in your automation workflows.

[n8n](https://n8n.io) is an open-source workflow automation platform. Using the n8n MCP Client node, you can call any Geekflare tool like scraping, search, screenshots, broken links, DNS — as a step in any automated workflow.

<Note>You can also integrate Geekflare with n8n using our [official node](https://n8n.io/integrations/geekflare/).</Note>

## Prerequisites

* n8n version 1.88.0 or later
* A Geekflare API key

## Setup

<Steps>
  <Step title="Add an MCP Client node">
    In your n8n workflow, click **+** to add a new node, then search for **MCP Client**.
  </Step>

  <Step title="Configure the connection">
    In the MCP Client node settings:

    * **Transport:** Select **Streamable HTTP**
    * **URL:** `https://mcp.geekflare.com/YOUR_API_KEY/mcp`

    Replace `YOUR_API_KEY` with your Geekflare API key.
  </Step>

  <Step title="Select a tool">
    In the **Tool** dropdown, choose the Geekflare tool you want to use (e.g.
    `webScrape`, `search`, `screenshot`).
  </Step>

  <Step title="Pass parameters">
    Use the **Parameters** section to pass the required fields. For most tools, `url` is required.
  </Step>
</Steps>

<Info>
  You can also use the **AI Agent** node in n8n to let the AI automatically
  select and call Geekflare tools based on your workflow prompts.
</Info>

## Example Workflows

**Scrape a webpage on a schedule**

1. Add a **Schedule Trigger** node (e.g. every hour)
2. Add an **MCP Client** node with tool `webScrape` and parameter `url: https://example.com`
3. Add a **Gmail** or **Slack** node to send the scraped content

**Search and summarize news**

1. Add a **Schedule Trigger** node
2. Add an **MCP Client** node with tool `search`, parameters `query: "AI news today"` and `source: news`
3. Add an **OpenAI** node to summarize the results
4. Send via Slack or email

**DNS monitoring**

1. Add a **Schedule Trigger** node
2. Add an **MCP Client** node with tool `dnsRecord` and parameter `url: yourdomain.com`
3. Add an **IF** node to check if records have changed
4. Alert via Slack if they have


# Other Clients
Source: https://docs.geekflare.com/mcp/others

Generic MCP configuration for any client that supports Streamable HTTP or stdio transport.

Any MCP-compatible client can connect to the Geekflare MCP server. Use the templates below based on the transport your client supports.

## Connection Options

### Option 1 — Remote Streamable HTTP (No installation)

The simplest option. No Node.js required on the user's machine.

```
https://mcp.geekflare.com/{API_KEY}/mcp
```

Replace `{API_KEY}` with your Geekflare API key.

**Config template:**

```json theme={null}
{
  "mcpServers": {
    "geekflare": {
      "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp"
    }
  }
}
```

### Option 2 — Local stdio via npx

Runs the MCP server locally on the user's machine. Requires [Node.js](https://nodejs.org).

```json theme={null}
{
  "mcpServers": {
    "geekflare": {
      "command": "npx",
      "args": ["-y", "@geekflare/mcp"],
      "env": {
        "API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Option 3 — Docker

No Node.js required. Requires [Docker](https://docker.com).

```json theme={null}
{
  "mcpServers": {
    "geekflare": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY=YOUR_API_KEY",
        "geekflare/mcp"
      ]
    }
  }
}
```

## Environment Variables

| Variable       | Required | Description                                                      |
| -------------- | -------- | ---------------------------------------------------------------- |
| `API_KEY`      | ✅        | Your Geekflare API key                                           |
| `API_BASE_URL` | —        | Override the API base URL (default: `https://api.geekflare.com`) |

## SSE Transport (Legacy)

Some older MCP clients use SSE instead of Streamable HTTP. If your client requires an SSE endpoint:

```json theme={null}
{
  "mcpServers": {
    "geekflare": {
      "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp",
      "transport": "sse"
    }
  }
}
```

<Info>Not all clients support SSE. Prefer Streamable HTTP where possible.</Info>

## Available Tools

See the [MCP Server overview](/mcp) for the full list of available tools.

## Get Your API Key

<Card title="Get your API key" icon="key" href="https://auth.geekflare.com/register?service=geekflare_api">
  Sign up for a free account to generate your key.
</Card>


# Roo Code
Source: https://docs.geekflare.com/mcp/roo-code

Connect Geekflare MCP server to Roo Code for web scraping, search, screenshot, and DNS tools in your AI coding workflow.

[Roo Code](https://github.com/RooVetGit/Roo-Code) is a VS Code extension providing an autonomous AI coding agent with multi-model support. With Geekflare MCP connected, Roo Code can browse the web, search, take screenshots, and look up DNS records during any task.

## Setup

<Steps>
  <Step title="Open Roo Code MCP settings">
    In VS Code, open the Roo Code panel from the sidebar, then click the **MCP Servers** icon at the top.
  </Step>

  <Step title="Add the Geekflare server">
    Click **Edit MCP Settings** and add:

    <Tabs>
      <Tab title="Remote URL (Recommended)">
        ```json theme={null}
        {
          "mcpServers": {
            "geekflare": {
              "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp",
              "disabled": false
            }
          }
        }
        ```
      </Tab>

      <Tab title="Local via npx">
        ```json theme={null}
        {
          "mcpServers": {
            "geekflare": {
              "command": "npx",
              "args": ["-y", "@geekflare/mcp"],
              "env": {
                "API_KEY": "YOUR_API_KEY"
              },
              "disabled": false
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    Replace `YOUR_API_KEY` with your Geekflare API key.
  </Step>

  <Step title="Verify connection">
    The Geekflare server should appear in the MCP list with a green dot. You can expand it to see all 20 tools.
  </Step>
</Steps>

## Usage Examples

**Scrape a webpage**

```
Scrape https://example.com and extract the main content as markdown.
```

**Metadata scraping**

```
Fetch the Open Graph meta tags from https://dji.com.
```

**Search**

```
Search for luxury watches for men under $5000
```

**DNS lookup**

```
What are the MX records of producthunt.com?
```


# VS Code
Source: https://docs.geekflare.com/mcp/vscode

Add the Geekflare MCP server to VS Code to enable web scraping, search, and screenshot tools in GitHub Copilot agent mode.

Visual Studio Code supports MCP servers through GitHub Copilot's agent mode. With Geekflare connected, Copilot can get the webpage context, fetch information from the Internet and run network tools to check DNS records, broken links, site availability, etc.

## Setup

<Tabs>
  <Tab title="User Settings (Global)">
    Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) and open **Preferences: Open User Settings (JSON)**. Add:

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "geekflare": {
            "type": "http",
            "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Workspace (.vscode/mcp.json)">
    Create `.vscode/mcp.json` in your project root to share the config with your team:

    ```json theme={null}
    {
      "servers": {
        "geekflare": {
          "type": "http",
          "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp"
        }
      }
    }
    ```

    <Warning>
      Do not commit your API key to version control. Use an environment variable or `.env` file and add `.vscode/mcp.json` to `.gitignore`.
    </Warning>
  </Tab>

  <Tab title="Local via npx">
    Requires [Node.js](https://nodejs.org) installed locally.

    ```json theme={null}
    {
      "mcp": {
        "servers": {
          "geekflare": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@geekflare/mcp"],
            "env": {
              "API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Replace `YOUR_API_KEY` with your Geekflare API key.

## Usage Examples

Open GitHub Copilot Chat (`Ctrl+Alt+I`), switch to **Agent** mode, and try:

**Scrape a webpage**

```
Use Geekflare to scrape https://example.com and extract the main body text.
```

**Metadata scraping**

```
Fetch the meta tags from https://geekflare.com and show me the SEO title and description.
```

**Search**

```
Search for "VS Code MCP extensions" and give me the top results.
```

**DNS lookup**

```
Look up the A and MX records for github.com.
```


# Devin Desktop
Source: https://docs.geekflare.com/mcp/windsurf

Connect Geekflare MCP server to Devin Desktop (earlier known as Windsurf) to enable web scraping, search, screenshot, and DNS tools in the AI agent.

[Devin Desktop](https://devin.ai/desktop) is an AI-powered code editor. Its Cascade agent can use Geekflare tools to scrape pages, run searches, take screenshots, and look up DNS — all from within your editor workflow.

## Setup

Open or create the Devin Desktop MCP config file:

* **macOS/Linux:** `~/.codeium/windsurf/mcp_config.json`
* **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json`

<Tabs>
  <Tab title="Remote URL (Recommended)">
    ```json theme={null}
    {
      "mcpServers": {
        "geekflare": {
          "serverUrl": "https://mcp.geekflare.com/YOUR_API_KEY/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Local via npx">
    Requires [Node.js](https://nodejs.org) installed locally.

    ```json theme={null}
    {
      "mcpServers": {
        "geekflare": {
          "command": "npx",
          "args": ["-y", "@geekflare/mcp"],
          "env": {
            "API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Replace `YOUR_API_KEY` with your Geekflare API key. Save the file and restart Devin Desktop.

## Usage Examples

Open Cascade and ask naturally:

**Scrape a webpage**

```
Scrape https://example.com and return the content as markdown.
```

**Search the web**

```
Search for latest credit card deals
```

**DNS lookup**

```
What are the DNS records for cloudflare.com?
```


# Zed
Source: https://docs.geekflare.com/mcp/zed

Connect Geekflare MCP server to Zed editor for web scraping, search, screenshot, and DNS tools in the AI assistant.

[Zed](https://zed.dev) is a high-performance collaborative code editor with a built-in AI assistant. Zed supports MCP servers, letting you connect Geekflare tools directly to the Zed Assistant for scraping, searching, and more.

## Setup

Open your Zed settings file (`Cmd+,` on Mac or `Ctrl+,` on Linux) and add the `context_servers` section:

<Tabs>
  <Tab title="Remote URL (Recommended)">
    ```json theme={null}
    {
      "context_servers": {
        "geekflare": {
          "url": "https://mcp.geekflare.com/YOUR_API_KEY/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Local via npx">
    ```json theme={null}
    {
      "context_servers": {
        "geekflare": {
          "command": {
            "path": "npx",
            "args": ["-y", "@geekflare/mcp"],
            "env": {
              "API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

Replace `YOUR_API_KEY` with your Geekflare API key. Save the settings file — Zed will pick up the changes immediately without a restart.

## Usage Examples

Open the Zed Assistant panel (`Cmd+?` on Mac) and try:

**Scrape a webpage**

```
Scrape amazon.com and give me products under $10
```

**Search the web**

```
Search for "Zed editor plugins" and give me a summary.
```

**Screenshot**

```
Take a screenshot of https://zed.dev and describe the homepage.
```

**Check Broken Links**

```
Check for broken links on https://zed.dev
```


# Cloudflare Workers
Source: https://docs.geekflare.com/quickstart/cloudflare-workers

Call Geekflare from a Cloudflare Worker using the edge-native fetch API and Wrangler secrets.

Cloudflare Workers run on the V8 edge runtime — no Node.js, no npm packages needed. All three examples use the native `fetch` API and store the API key as a Wrangler secret so it never touches your codebase.

## Prerequisites

* [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) installed (`pnpm add -g wrangler`)
* A Cloudflare account
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Create a Worker

```bash theme={null}
pnpm create cloudflare@latest geekflare-worker
cd geekflare-worker
```

Choose **"Hello World" Worker** when prompted. Select **TypeScript**.

## Set your API key

Store the key as a secret — never hardcode it:

```bash theme={null}
# Local development
echo "GEEKFLARE_API_KEY=your_api_key_here" >> .dev.vars

# Production
wrangler secret put GEEKFLARE_API_KEY
```

<Warning>
  `.dev.vars` is the Workers equivalent of `.env`. It is gitignored by default.
  Do **not** commit it.
</Warning>

Declare the binding in `wrangler.toml` so TypeScript knows it exists:

```toml wrangler.toml theme={null}
name = "geekflare-worker"
main = "src/index.ts"
compatibility_date = "2024-01-01"

[vars]
# Non-secret vars go here. Secrets are set via `wrangler secret put`.
```

Add the type to your Worker's `Env` interface:

```ts src/index.ts theme={null}
export interface Env {
  GEEKFLARE_API_KEY: string;
}
```

***

## Shared helper

A small typed helper keeps each handler clean:

```ts src/geekflare.ts theme={null}
export const GEEKFLARE_BASE = "https://api.geekflare.com";

export async function geekflarePost<T>(
  env: { GEEKFLARE_API_KEY: string },
  path: string,
  body: Record<string, unknown>,
): Promise<T> {
  const res = await fetch(`${GEEKFLARE_BASE}${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": env.GEEKFLARE_API_KEY,
    },
    body: JSON.stringify(body),
  });

  if (!res.ok) {
    const error = await res.json<{ apiCode: number; message: string }>();
    throw new Error(`[${error.apiCode}] ${error.message}`);
  }

  return res.json<T>();
}
```

***

## Web Scraping

```ts src/index.ts theme={null}
import { geekflarePost } from "./geekflare";

export interface Env {
  GEEKFLARE_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("Method Not Allowed", { status: 405 });
    }

    const { url } = await request.json<{ url: string }>();

    if (!url) {
      return Response.json({ error: "url is required" }, { status: 400 });
    }

    try {
      const result = await geekflarePost(env, "/webscraping", {
        url,
        renderJS: true,
        blockAds: true,
        format: "html,markdown",
      });

      return Response.json(result);
    } catch (error: any) {
      return Response.json({ error: error.message }, { status: 500 });
    }
  },
};
```

**Test locally:**

```bash theme={null}
wrangler dev
curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://toscrape.com/" }'
```

***

## Search

Route requests to different Geekflare endpoints based on the URL path:

```ts src/index.ts theme={null}
import { geekflarePost } from "./geekflare";

export interface Env {
  GEEKFLARE_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { pathname } = new URL(request.url);

    if (request.method !== "POST") {
      return new Response("Method Not Allowed", { status: 405 });
    }

    if (pathname === "/search") {
      const {
        query,
        limit = 10,
        location = "us",
      } = await request.json<{
        query: string;
        limit?: number;
        location?: string;
      }>();

      if (!query) {
        return Response.json({ error: "query is required" }, { status: 400 });
      }

      try {
        const result = await geekflarePost(env, "/search", {
          query,
          limit,
          location,
          source: "web",
          format: "json",
        });

        return Response.json(result);
      } catch (error: any) {
        return Response.json({ error: error.message }, { status: 500 });
      }
    }

    return new Response("Not Found", { status: 404 });
  },
};
```

**Test locally:**

```bash theme={null}
curl -X POST http://localhost:8787/search \
  -H "Content-Type: application/json" \
  -d '{ "query": "Cloudflare Workers best practices", "limit": 5 }'
```

***

## Screenshot

```ts src/index.ts theme={null}
import { geekflarePost } from "./geekflare";

export interface Env {
  GEEKFLARE_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { pathname } = new URL(request.url);

    if (request.method !== "POST") {
      return new Response("Method Not Allowed", { status: 405 });
    }

    if (pathname === "/screenshot") {
      const { url } = await request.json<{ url: string }>();

      if (!url) {
        return Response.json({ error: "url is required" }, { status: 400 });
      }

      try {
        const result = await geekflarePost(env, "/screenshot", {
          url,
          type: "png",
          fullPage: true,
          device: "desktop",
          viewportWidth: 1280,
          viewportHeight: 800,
          blockAds: true,
          hideCookie: true,
          quality: 90,
        });

        return Response.json(result);
      } catch (error: any) {
        return Response.json({ error: error.message }, { status: 500 });
      }
    }

    return new Response("Not Found", { status: 404 });
  },
};
```

***

## Complete multi-route Worker

A single Worker handling all three endpoints:

```ts src/index.ts theme={null}
import { geekflarePost } from "./geekflare";

export interface Env {
  GEEKFLARE_API_KEY: string;
}

type RouteHandler = (request: Request, env: Env) => Promise<Response>;

const routes: Record<string, RouteHandler> = {
  "/scrape": async (req, env) => {
    const {
      url,
      renderJS = true,
      blockAds = true,
    } = await req.json<{
      url: string;
      renderJS?: boolean;
      blockAds?: boolean;
    }>();
    if (!url)
      return Response.json({ error: "url is required" }, { status: 400 });
    const result = await geekflarePost(env, "/webscraping", {
      url,
      renderJS,
      blockAds,
      format: "html,markdown",
    });
    return Response.json(result);
  },

  "/search": async (req, env) => {
    const {
      query,
      limit = 10,
      location = "us",
    } = await req.json<{ query: string; limit?: number; location?: string }>();
    if (!query)
      return Response.json({ error: "query is required" }, { status: 400 });
    const result = await geekflarePost(env, "/search", {
      query,
      limit,
      location,
      source: "web",
      format: "json",
    });
    return Response.json(result);
  },

  "/screenshot": async (req, env) => {
    const { url } = await req.json<{ url: string }>();
    if (!url)
      return Response.json({ error: "url is required" }, { status: 400 });
    const result = await geekflarePost(env, "/screenshot", {
      url,
      type: "png",
      fullPage: true,
      device: "desktop",
      viewportWidth: 1280,
      viewportHeight: 800,
      blockAds: true,
      hideCookie: true,
      quality: 90,
    });
    return Response.json(result);
  },
};

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== "POST") {
      return new Response("Method Not Allowed", { status: 405 });
    }

    const { pathname } = new URL(request.url);
    const handler = routes[pathname];

    if (!handler) {
      return new Response("Not Found", { status: 404 });
    }

    try {
      return await handler(request, env);
    } catch (error: any) {
      return Response.json({ error: error.message }, { status: 500 });
    }
  },
};
```

## Deploy

```bash theme={null}
wrangler deploy
```

***

## Error handling

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `401` | Missing or invalid `x-api-key`    |
| `402` | API credits exhausted             |
| `403` | Endpoint requires a higher plan   |
| `404` | Wrong endpoint URL or HTTP method |
| `429` | Rate limit exceeded               |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

The `geekflarePost` helper above throws on non-2xx responses. Wrap every handler in `try/catch` and map error codes to appropriate HTTP responses:

```ts theme={null}
try {
  const result = await geekflarePost(env, "/webscraping", { url });
  return Response.json(result);
} catch (error: any) {
  const message: string = error.message ?? "Unknown error";

  if (message.startsWith("[429]")) {
    return Response.json({ error: "Rate limit exceeded" }, { status: 429 });
  }
  if (message.startsWith("[402]")) {
    return Response.json({ error: "Credits exhausted" }, { status: 402 });
  }

  return Response.json({ error: message }, { status: 500 });
}
```

***

## Next steps

* [PHP quickstart](/quickstart/php) — cURL and Guzzle
* [API Reference](/endpoint/reference) — Full endpoint documentation
* [SDK on npm](https://www.npmjs.com/package/@geekflare/api-node)


# Django
Source: https://docs.geekflare.com/quickstart/django

Integrate Geekflare into a Django application using a reusable service class, views, and python-decouple for config.

This guide uses the official `geekflare-api` Python SDK inside a Django project. We'll create a reusable service class, wire it into Django views, and keep secrets out of source control with `python-decouple`.

## Prerequisites

* Python **3.8+**
* Django **4.0+**
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Installation

```bash theme={null}
pip install geekflare-api python-decouple
```

Or with `uv`:

```bash theme={null}
uv add geekflare-api python-decouple
```

## Set your API key

```bash .env theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

`python-decouple` reads from `.env` automatically. Add `.env` to `.gitignore`.

***

## Service class

Keep all Geekflare logic in one place. Create `services/geekflare.py` in your app:

```python yourapp/services/geekflare.py theme={null}
from decouple import config
from geekflare_api.client import GeekflareClient
from geekflare_api.models import WebScrapeDto, SearchDto, ScreenshotDto
from geekflare_api.exceptions import ApiException


class GeekflareService:
    """Thin wrapper around the Geekflare SDK for use in Django views."""

    def __init__(self):
        self._api_key = config("GEEKFLARE_API_KEY")

    def _client(self) -> GeekflareClient:
        return GeekflareClient(api_key=self._api_key)

    def web_scrape(self, url: str, **kwargs) -> dict:
        with self._client() as client:
            return client.web_scrape(WebScrapeDto(url=url, **kwargs))

    def search(self, query: str, **kwargs) -> dict:
        with self._client() as client:
            return client.search(SearchDto(query=query, **kwargs))

    def screenshot(self, url: str, **kwargs) -> dict:
        with self._client() as client:
            return client.screenshot(ScreenshotDto(url=url, **kwargs))


# Module-level singleton — import this in your views
geekflare = GeekflareService()
```

***

## Web Scraping

### View

```python yourapp/views.py theme={null}
import json
from django.http import JsonResponse
from django.views import View
from django.views.decorators.csrf import csrf_exempt
from django.utils.decorators import method_decorator
from geekflare_api.exceptions import ApiException
from .services.geekflare import geekflare


@method_decorator(csrf_exempt, name="dispatch")
class ScrapeView(View):
    def post(self, request):
        try:
            body = json.loads(request.body)
        except json.JSONDecodeError:
            return JsonResponse({"error": "Invalid JSON"}, status=400)

        url = body.get("url")
        if not url:
            return JsonResponse({"error": "url is required"}, status=400)

        try:
            result = geekflare.web_scrape(
                url=url,
                renderJS=body.get("renderJS", True),
                blockAds=body.get("blockAds", True),
                format=body.get("format", "html,markdown"),
            )
            return JsonResponse(result, safe=False)

        except ApiException as e:
            return JsonResponse(
                {"error": e.reason, "code": e.status},
                status=e.status or 500,
            )
```

### URL

```python yourapp/urls.py theme={null}
from django.urls import path
from .views import ScrapeView

urlpatterns = [
    path("scrape/", ScrapeView.as_view(), name="scrape"),
]
```

**Test:**

```bash theme={null}
curl -X POST http://localhost:8000/scrape/ \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://toscrape.com/" }'
```

***

## Search

### View

```python yourapp/views.py theme={null}
@method_decorator(csrf_exempt, name="dispatch")
class SearchView(View):
    def post(self, request):
        try:
            body = json.loads(request.body)
        except json.JSONDecodeError:
            return JsonResponse({"error": "Invalid JSON"}, status=400)

        query = body.get("query")
        if not query:
            return JsonResponse({"error": "query is required"}, status=400)

        try:
            result = geekflare.search(
                query=query,
                limit=body.get("limit", 10),
                location=body.get("location", "us"),
                source=body.get("source", "web"),
                time=body.get("time"),
                format="json",
            )
            return JsonResponse(result, safe=False)

        except ApiException as e:
            return JsonResponse(
                {"error": e.reason, "code": e.status},
                status=e.status or 500,
            )
```

### URL

```python yourapp/urls.py theme={null}
from django.urls import path
from .views import ScrapeView, SearchView

urlpatterns = [
    path("scrape/", ScrapeView.as_view(), name="scrape"),
    path("search/", SearchView.as_view(), name="search"),
]
```

**Test:**

```bash theme={null}
curl -X POST http://localhost:8000/search/ \
  -H "Content-Type: application/json" \
  -d '{ "query": "Django REST framework tutorial", "limit": 5 }'
```

***

## Screenshot

### View

```python yourapp/views.py theme={null}
@method_decorator(csrf_exempt, name="dispatch")
class ScreenshotView(View):
    def post(self, request):
        try:
            body = json.loads(request.body)
        except json.JSONDecodeError:
            return JsonResponse({"error": "Invalid JSON"}, status=400)

        url = body.get("url")
        if not url:
            return JsonResponse({"error": "url is required"}, status=400)

        try:
            result = geekflare.screenshot(
                url=url,
                type=body.get("type", "png"),
                fullPage=body.get("fullPage", True),
                device=body.get("device", "desktop"),
                viewportWidth=body.get("viewportWidth", 1280),
                viewportHeight=body.get("viewportHeight", 800),
                blockAds=body.get("blockAds", True),
                hideCookie=body.get("hideCookie", True),
                quality=body.get("quality", 90),
            )
            return JsonResponse(result, safe=False)

        except ApiException as e:
            return JsonResponse(
                {"error": e.reason, "code": e.status},
                status=e.status or 500,
            )
```

### URL

```python yourapp/urls.py theme={null}
from django.urls import path
from .views import ScrapeView, SearchView, ScreenshotView

urlpatterns = [
    path("scrape/", ScrapeView.as_view(), name="scrape"),
    path("search/", SearchView.as_view(), name="search"),
    path("screenshot/", ScreenshotView.as_view(), name="screenshot"),
]
```

**Test:**

```bash theme={null}
curl -X POST http://localhost:8000/screenshot/ \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "fullPage": true }'
```

***

## Using Django REST Framework

If your project uses DRF, swap the class-based views for `APIView`:

```python yourapp/views.py theme={null}
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import status
from geekflare_api.exceptions import ApiException
from .services.geekflare import geekflare


class ScrapeAPIView(APIView):
    def post(self, request):
        url = request.data.get("url")
        if not url:
            return Response({"error": "url is required"}, status=status.HTTP_400_BAD_REQUEST)

        try:
            result = geekflare.web_scrape(
                url=url,
                renderJS=request.data.get("renderJS", True),
                blockAds=request.data.get("blockAds", True),
                format=request.data.get("format", "html,markdown"),
            )
            return Response(result)

        except ApiException as e:
            return Response(
                {"error": e.reason, "code": e.status},
                status=e.status or status.HTTP_500_INTERNAL_SERVER_ERROR,
            )
```

***

## Error handling

The SDK raises `ApiException` with a `status` code and `reason` string on non-2xx responses.

```python theme={null}
from geekflare_api.exceptions import ApiException

try:
    result = geekflare.web_scrape(url="https://toscrape.com/")
except ApiException as e:
    if e.status == 401:
        # Invalid or missing API key
    elif e.status == 402:
        # Credits exhausted — check dash.geekflare.com
    elif e.status == 403:
        # Endpoint not available on current plan
    elif e.status == 429:
        # Rate limit hit — implement exponential backoff
    else:
        # Unexpected error
        raise
```

### Common error codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `401` | Missing or invalid `x-api-key`    |
| `402` | API credits exhausted             |
| `403` | Endpoint requires a higher plan   |
| `404` | Wrong endpoint URL or HTTP method |
| `429` | Rate limit exceeded               |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

***

## Next steps

* [PHP quickstart](/quickstart/php) — Native cURL and Guzzle
* [API Reference](/endpoint/reference) — Full endpoint documentation
* [SDK on PyPI](https://pypi.org/project/geekflare-api/)


# Go
Source: https://docs.geekflare.com/quickstart/go

Use Geekflare in a Go application using the standard net/http package and os.Getenv for config.

No SDK is needed for Go. The standard `net/http` and `encoding/json` packages are all you need. This guide builds a reusable client struct that you can drop into any Go project.

## Prerequisites

* Go **1.21+**
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Set your API key

```bash .env theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

Load it with `godotenv`:

```bash theme={null}
go get github.com/joho/godotenv
```

```go theme={null}
import "github.com/joho/godotenv"

func init() {
    if err := godotenv.Load(); err != nil {
        log.Println("No .env file found, reading from environment")
    }
}

apiKey := os.Getenv("GEEKFLARE_API_KEY")
if apiKey == "" {
    log.Fatal("GEEKFLARE_API_KEY is not set")
}
```

<Warning>
  Add `.env` to `.gitignore`. In production, inject the key directly as an
  environment variable.
</Warning>

***

## Reusable client

```go internal/geekflare/client.go theme={null}
package geekflare

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "time"
)

const baseURL = "https://api.geekflare.com"

// Client is a simple Geekflare API client.
type Client struct {
    apiKey     string
    httpClient *http.Client
}

// New creates a new Geekflare Client.
func New(apiKey string) *Client {
    return &Client{
        apiKey: apiKey,
        httpClient: &http.Client{
            Timeout: 30 * time.Second,
        },
    }
}

// APIError represents a non-2xx response from the Geekflare API.
type APIError struct {
    APICode int    `json:"apiCode"`
    Message string `json:"message"`
}

func (e *APIError) Error() string {
    return fmt.Sprintf("geekflare API error [%d]: %s", e.APICode, e.Message)
}

// post sends a POST request and decodes the response into out.
func (c *Client) post(path string, body any, out any) error {
    b, err := json.Marshal(body)
    if err != nil {
        return fmt.Errorf("marshal request: %w", err)
    }

    req, err := http.NewRequest(http.MethodPost, baseURL+path, bytes.NewReader(b))
    if err != nil {
        return fmt.Errorf("create request: %w", err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-api-key", c.apiKey)

    resp, err := c.httpClient.Do(req)
    if err != nil {
        return fmt.Errorf("execute request: %w", err)
    }
    defer resp.Body.Close()

    data, err := io.ReadAll(resp.Body)
    if err != nil {
        return fmt.Errorf("read response: %w", err)
    }

    if resp.StatusCode != http.StatusOK {
        var apiErr APIError
        if jsonErr := json.Unmarshal(data, &apiErr); jsonErr != nil {
            return fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(data))
        }
        return &apiErr
    }

    return json.Unmarshal(data, out)
}
```

***

## Web Scraping

### Types

```go internal/geekflare/scrape.go theme={null}
package geekflare

// WebScrapeRequest represents the request body for the webscraping endpoint.
type WebScrapeRequest struct {
    URL      string  `json:"url"`
    Device   string  `json:"device,omitempty"`
    RenderJS bool    `json:"renderJS,omitempty"`
    BlockAds bool    `json:"blockAds,omitempty"`
    Format   string  `json:"format,omitempty"`
    Stealth  bool    `json:"stealth,omitempty"`
    WaitTime float64 `json:"waitTime,omitempty"`
}

// WebScrapeResponse is the API response for the webscraping endpoint.
// Data is a URL pointing to the scraped output file.
type WebScrapeResponse struct {
    Timestamp int64  `json:"timestamp"`
    APIStatus string `json:"apiStatus"`
    APICode   int    `json:"apiCode"`
    Data      string `json:"data"`
}

// WebScrape scrapes a web page and returns its content.
func (c *Client) WebScrape(req WebScrapeRequest) (*WebScrapeResponse, error) {
    var out WebScrapeResponse
    if err := c.post("/webscraping", req, &out); err != nil {
        return nil, err
    }
    return &out, nil
}
```

### Usage

```go cmd/scrape/main.go theme={null}
package main

import (
    "fmt"
    "log"
    "os"

    "github.com/joho/godotenv"
    "yourmodule/internal/geekflare"
)

func main() {
    _ = godotenv.Load()

    client := geekflare.New(os.Getenv("GEEKFLARE_API_KEY"))

    result, err := client.WebScrape(geekflare.WebScrapeRequest{
        URL:      "https://toscrape.com/",
        Device:   "desktop",
        RenderJS: true,
        BlockAds: true,
        Format:   "html,markdown",
    })
    if err != nil {
        log.Fatal(err)
    }

    // result.Data is a URL to the scraped output file
    fmt.Println("Output file URL:", result.Data)
}
```

***

## Search

### Types

```go internal/geekflare/search.go theme={null}
package geekflare

// SearchRequest represents the request body for the search endpoint.
type SearchRequest struct {
    Query          string   `json:"query"`
    Limit          int      `json:"limit,omitempty"`
    Location       string   `json:"location,omitempty"`
    Source         string   `json:"source,omitempty"`
    Time           string   `json:"time,omitempty"`
    Format         string   `json:"format,omitempty"`
    IncludeDomains []string `json:"includeDomains,omitempty"`
    ExcludeDomains []string `json:"excludeDomains,omitempty"`
}

// SearchResult is a single result in the search response.
type SearchResult struct {
    Title    string `json:"title"`
    URL      string `json:"url"`
    Snippet  string `json:"snippet"`
    Date     string `json:"date"`
    Position int    `json:"position"`
    Content  string `json:"content"`
}

// SearchResponse is the API response for the search endpoint.
type SearchResponse struct {
    Timestamp int64          `json:"timestamp"`
    APIStatus string         `json:"apiStatus"`
    APICode   int            `json:"apiCode"`
    Data      []SearchResult `json:"data"`
}

// Search performs a web search.
func (c *Client) Search(req SearchRequest) (*SearchResponse, error) {
    var out SearchResponse
    if err := c.post("/search", req, &out); err != nil {
        return nil, err
    }
    return &out, nil
}
```

### Usage

```go cmd/search/main.go theme={null}
package main

import (
    "fmt"
    "log"
    "os"

    "github.com/joho/godotenv"
    "yourmodule/internal/geekflare"
)

func main() {
    _ = godotenv.Load()

    client := geekflare.New(os.Getenv("GEEKFLARE_API_KEY"))

    result, err := client.Search(geekflare.SearchRequest{
        Query:    "best Go web frameworks",
        Limit:    10,
        Location: "us",
        Source:   "web",
        Time:     "m",
        Format:   "json",
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, item := range result.Data {
        fmt.Printf("%s\n  %s\n  %s\n\n", item.Title, item.URL, item.Snippet)
    }
}
```

***

## Screenshot

### Types

```go internal/geekflare/screenshot.go theme={null}
package geekflare

// ScreenshotRequest represents the request body for the screenshot endpoint.
type ScreenshotRequest struct {
    URL            string `json:"url"`
    Type           string `json:"type,omitempty"`
    FullPage       bool   `json:"fullPage,omitempty"`
    Device         string `json:"device,omitempty"`
    ViewportWidth  int    `json:"viewportWidth,omitempty"`
    ViewportHeight int    `json:"viewportHeight,omitempty"`
    BlockAds       bool   `json:"blockAds,omitempty"`
    HideCookie     bool   `json:"hideCookie,omitempty"`
    Quality        int    `json:"quality,omitempty"`
    Delay          int    `json:"delay,omitempty"`
}

// ScreenshotResponse is the API response for the screenshot endpoint.
// Data is a direct URL string pointing to the captured screenshot image.
type ScreenshotResponse struct {
    Timestamp int64  `json:"timestamp"`
    APIStatus string `json:"apiStatus"`
    APICode   int    `json:"apiCode"`
    Data      string `json:"data"`
}

// Screenshot captures a screenshot of a URL.
func (c *Client) Screenshot(req ScreenshotRequest) (*ScreenshotResponse, error) {
    var out ScreenshotResponse
    if err := c.post("/screenshot", req, &out); err != nil {
        return nil, err
    }
    return &out, nil
}
```

### Usage

```go cmd/screenshot/main.go theme={null}
package main

import (
    "fmt"
    "log"
    "os"

    "github.com/joho/godotenv"
    "yourmodule/internal/geekflare"
)

func main() {
    _ = godotenv.Load()

    client := geekflare.New(os.Getenv("GEEKFLARE_API_KEY"))

    result, err := client.Screenshot(geekflare.ScreenshotRequest{
        URL:            "https://example.com",
        Type:           "png",
        FullPage:       true,
        Device:         "desktop",
        ViewportWidth:  1280,
        ViewportHeight: 800,
        BlockAds:       true,
        HideCookie:     true,
        Quality:        90,
    })
    if err != nil {
        log.Fatal(err)
    }

    // result.Data is the screenshot URL directly
    fmt.Println("Screenshot URL:", result.Data)
}
```

***

## Error handling

The `APIError` type returned by the client carries the status code and message. Use `errors.As` to inspect it:

```go theme={null}
import (
    "errors"
    "log"

    "yourmodule/internal/geekflare"
)

result, err := client.WebScrape(geekflare.WebScrapeRequest{URL: "https://toscrape.com/"})
if err != nil {
    var apiErr *geekflare.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.APICode {
        case 401:
            log.Fatal("Invalid or missing API key.")
        case 402:
            log.Fatal("API credits exhausted. Top up at dash.geekflare.com.")
        case 403:
            log.Fatal("Endpoint not available on your plan.")
        case 429:
            log.Println("Rate limit exceeded. Back off and retry.")
            // implement exponential backoff here
        default:
            log.Fatalf("API error [%d]: %s", apiErr.APICode, apiErr.Message)
        }
    }
    log.Fatal("Unexpected error:", err)
}
```

### Common error codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `401` | Missing or invalid `x-api-key`    |
| `402` | API credits exhausted             |
| `403` | Endpoint requires a higher plan   |
| `404` | Wrong endpoint URL or HTTP method |
| `429` | Rate limit exceeded               |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

***

## Next steps

* [API Reference](/endpoint/reference) — Full endpoint documentation
* [Back to Quickstart overview](/quickstart)


# Quickstart
Source: https://docs.geekflare.com/quickstart/index

Get up and running with Geekflare in your preferred language or framework.

Choose your language or framework below to follow a step-by-step guide. Each guide covers installation, authentication, and making your first requests to Geekflare's core endpoints.

<CardGroup>
  <Card title="Node.js" icon="node-js" href="/quickstart/nodejs">
    Use the official Node.js SDK or fetch in any JS runtime
  </Card>

  <Card title="Next.js" icon="react" href="/quickstart/nextjs">
    Integrate with Route Handlers and Server Components
  </Card>

  <Card title="NestJS" icon="n" href="/quickstart/nestjs">
    Build a service module with dependency injection
  </Card>

  <Card title="Cloudflare Workers" icon="cloud" href="/quickstart/cloudflare-workers">
    Run Geekflare requests at the edge with zero cold starts
  </Card>

  <Card title="Python" icon="python" href="/quickstart/python">
    Use the official Python SDK in scripts or backends
  </Card>

  <Card title="Django" icon="python" href="/quickstart/django">
    Add Geekflare to your Django views and services
  </Card>

  <Card title="PHP" icon="php" href="/quickstart/php">
    Call the API using cURL or Guzzle HTTP client
  </Card>

  <Card title="Laravel" icon="php" href="/quickstart/laravel">
    Use Laravel HTTP client with a dedicated service class
  </Card>

  <Card title="Go" icon="golang" href="/quickstart/go">
    Make type-safe HTTP requests from any Go application
  </Card>
</CardGroup>

## Endpoints covered

Each guide demonstrates three core endpoints:

| Endpoint     | Method | Path           |
| ------------ | ------ | -------------- |
| Web Scraping | `POST` | `/webscraping` |
| Search       | `POST` | `/search`      |
| Screenshot   | `POST` | `/screenshot`  |

## Base URL

```
https://api.geekflare.com
```

## Authentication

All requests require your API key in the `x-api-key` header:

```
x-api-key: YOUR_API_KEY
```

[Get your API key →](https://dash.geekflare.com/)


# Laravel
Source: https://docs.geekflare.com/quickstart/laravel

Integrate Geekflare into a Laravel application using the built-in HTTP client, a service class, and .env config.

Laravel's first-party HTTP client wraps Guzzle with a fluent, expressive API. This guide creates a dedicated `GeekflareService`, registers it in the service container, and injects it into controllers.

## Prerequisites

* Laravel **10+**
* PHP **8.1+**
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Installation

No extra packages needed — Laravel's HTTP client is built in. Just add your key to `.env`:

```bash .env theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

<Warning>
  `.env` is gitignored by default in Laravel. Use `.env.example` (without real
  values) for documentation.
</Warning>

***

## Config file

Centralise the API settings in a config file so they're accessible via `config()`:

```php config/geekflare.php theme={null}
<?php

return [
    'api_key'  => env('GEEKFLARE_API_KEY'),
    'base_url' => 'https://api.geekflare.com',
];
```

***

## Service class

```php app/Services/GeekflareService.php theme={null}
<?php

namespace App\Services;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Facades\Http;

class GeekflareService
{
    private PendingRequest $http;

    public function __construct()
    {
        $this->http = Http::baseUrl(config('geekflare.base_url'))
            ->withHeaders([
                'x-api-key' => config('geekflare.api_key'),
            ])
            ->acceptJson();
    }

    /**
     * Scrape web page content.
     */
    public function webScrape(array $params): array
    {
        return $this->post('/webscraping', $params);
    }

    /**
     * Perform a web search.
     */
    public function search(array $params): array
    {
        return $this->post('/search', $params);
    }

    /**
     * Take a screenshot of a URL.
     */
    public function screenshot(array $params): array
    {
        return $this->post('/screenshot', $params);
    }

    private function post(string $endpoint, array $params): array
    {
        $response = $this->http->post($endpoint, $params);
        $response->throw(); // throws RequestException on 4xx/5xx

        return $response->json();
    }
}
```

### Register in the service container

```php app/Providers/AppServiceProvider.php theme={null}
<?php

namespace App\Providers;

use App\Services\GeekflareService;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(GeekflareService::class);
    }
}
```

***

## Web Scraping

### Controller

```php app/Http/Controllers/ScrapeController.php theme={null}
<?php

namespace App\Http\Controllers;

use App\Services\GeekflareService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Client\RequestException;

class ScrapeController extends Controller
{
    public function __construct(
        private readonly GeekflareService $geekflare
    ) {}

    public function __invoke(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'url'      => 'required|url',
            'renderJS' => 'boolean',
            'blockAds' => 'boolean',
            'format'   => 'string',
        ]);

        try {
            $result = $this->geekflare->webScrape([
                'url'      => $validated['url'],
                'renderJS' => $validated['renderJS'] ?? true,
                'blockAds' => $validated['blockAds'] ?? true,
                'format'   => $validated['format'] ?? 'html,markdown',
                'device'   => 'desktop',
            ]);

            return response()->json($result);

        } catch (RequestException $e) {
            return $this->handleApiException($e);
        }
    }

    private function handleApiException(RequestException $e): JsonResponse
    {
        $code = $e->response->status();
        $body = $e->response->json();

        return response()->json(
            ['error' => $body['message'] ?? 'API request failed', 'code' => $code],
            $code
        );
    }
}
```

### Route

```php routes/api.php theme={null}
use App\Http\Controllers\ScrapeController;

Route::post('/scrape', ScrapeController::class);
```

**Test:**

```bash theme={null}
curl -X POST http://localhost:8000/api/scrape \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://toscrape.com/", "renderJS": true }'
```

***

## Search

### Controller

```php app/Http/Controllers/SearchController.php theme={null}
<?php

namespace App\Http\Controllers;

use App\Services\GeekflareService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Client\RequestException;

class SearchController extends Controller
{
    public function __construct(
        private readonly GeekflareService $geekflare
    ) {}

    public function __invoke(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'query'          => 'required|string',
            'limit'          => 'integer|min:1|max:100',
            'location'       => 'string|size:2',
            'source'         => 'string',
            'time'           => 'string|in:d,w,m',
            'includeDomains' => 'array',
            'excludeDomains' => 'array',
        ]);

        try {
            $result = $this->geekflare->search(array_merge(
                ['limit' => 10, 'location' => 'us', 'source' => 'web', 'format' => 'json'],
                $validated
            ));

            return response()->json($result);

        } catch (RequestException $e) {
            $code = $e->response->status();
            $body = $e->response->json();
            return response()->json(['error' => $body['message'] ?? 'Search failed'], $code);
        }
    }
}
```

### Route

```php routes/api.php theme={null}
use App\Http\Controllers\SearchController;

Route::post('/search', SearchController::class);
```

**Test:**

```bash theme={null}
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{ "query": "Laravel best practices", "limit": 5 }'
```

***

## Screenshot

### Controller

```php app/Http/Controllers/ScreenshotController.php theme={null}
<?php

namespace App\Http\Controllers;

use App\Services\GeekflareService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;
use Illuminate\Http\Client\RequestException;

class ScreenshotController extends Controller
{
    public function __construct(
        private readonly GeekflareService $geekflare
    ) {}

    public function __invoke(Request $request): JsonResponse
    {
        $validated = $request->validate([
            'url'            => 'required|url',
            'type'           => 'string|in:png,jpg,webp',
            'fullPage'       => 'boolean',
            'device'         => 'string|in:desktop,mobile',
            'viewportWidth'  => 'integer',
            'viewportHeight' => 'integer',
            'blockAds'       => 'boolean',
            'hideCookie'     => 'boolean',
            'quality'        => 'integer|min:1|max:100',
        ]);

        try {
            $result = $this->geekflare->screenshot(array_merge([
                'type'           => 'png',
                'fullPage'       => true,
                'device'         => 'desktop',
                'viewportWidth'  => 1280,
                'viewportHeight' => 800,
                'blockAds'       => true,
                'hideCookie'     => true,
                'quality'        => 90,
            ], $validated));

            return response()->json($result);

        } catch (RequestException $e) {
            $code = $e->response->status();
            $body = $e->response->json();
            return response()->json(['error' => $body['message'] ?? 'Screenshot failed'], $code);
        }
    }
}
```

### Route

```php routes/api.php theme={null}
use App\Http\Controllers\ScreenshotController;

Route::post('/screenshot', ScreenshotController::class);
```

**Test:**

```bash theme={null}
curl -X POST http://localhost:8000/api/screenshot \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "fullPage": true }'
```

***

## All routes together

```php routes/api.php theme={null}
<?php

use App\Http\Controllers\ScrapeController;
use App\Http\Controllers\SearchController;
use App\Http\Controllers\ScreenshotController;

Route::post('/scrape',     ScrapeController::class);
Route::post('/search',     SearchController::class);
Route::post('/screenshot', ScreenshotController::class);
```

***

## Error handling

Laravel's HTTP client `throw()` converts 4xx/5xx responses to `RequestException`. Handle them by status code:

```php theme={null}
use Illuminate\Http\Client\RequestException;

try {
    $result = $this->geekflare->webScrape(['url' => 'https://toscrape.com/']);
} catch (RequestException $e) {
    $code = $e->response->status();

    match ($code) {
        401 => abort(401, 'Invalid or missing Geekflare API key.'),
        402 => abort(402, 'API credits exhausted.'),
        403 => abort(403, 'This endpoint requires a higher plan.'),
        429 => abort(429, 'Rate limit exceeded. Try again shortly.'),
        default => abort($code, $e->response->json('message') ?? 'API error'),
    };
}
```

### Common error codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `401` | Missing or invalid `x-api-key`    |
| `402` | API credits exhausted             |
| `403` | Endpoint requires a higher plan   |
| `404` | Wrong endpoint URL or HTTP method |
| `429` | Rate limit exceeded               |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

***

## Next steps

* [Go quickstart](/quickstart/go) — Standard `net/http` package
* [API Reference](/endpoint/reference) — Full endpoint documentation


# NestJS
Source: https://docs.geekflare.com/quickstart/nestjs

Integrate Geekflare into a NestJS application using injectable services, ConfigModule, and typed DTOs.

This guide follows NestJS conventions: a dedicated `GeekflareModule` with an injectable `GeekflareService`, typed request DTOs, and `.env` config via `ConfigModule`. The examples use the official `@geekflare/api-node` SDK.

## Prerequisites

* NestJS **10+**
* Node.js **18+**
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Installation

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @geekflare/api-node @nestjs/config 
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install @geekflare/api-node @nestjs/config 
    ```
  </Tab>
</Tabs>

## Set your API key

```bash .env theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

<Warning>
  Never commit `.env`. Add it to `.gitignore` and use `.env.example` for
  documentation.
</Warning>

***

## Module setup

### `GeekflareService`

Create a service that instantiates the client once and exposes typed methods.

```ts src/geekflare/geekflare.service.ts theme={null}
import { Injectable, OnModuleInit } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { GeekflareClient } from "@geekflare/api-node";

@Injectable()
export class GeekflareService implements OnModuleInit {
  private client: GeekflareClient;

  constructor(private readonly config: ConfigService) {}

  onModuleInit() {
    this.client = new GeekflareClient({
      apiKey: this.config.getOrThrow<string>("GEEKFLARE_API_KEY"),
    });
  }

  async webScrape(params: {
    url: string;
    renderJS?: boolean;
    blockAds?: boolean;
    format?: string;
  }) {
    return this.client.webScrape(params);
  }

  async search(params: {
    query: string;
    limit?: number;
    location?: string;
    source?: string;
    time?: string;
    includeDomains?: string[];
    excludeDomains?: string[];
  }) {
    return this.client.search(params);
  }

  async screenshot(params: {
    url: string;
    type?: string;
    fullPage?: boolean;
    device?: string;
    viewportWidth?: number;
    viewportHeight?: number;
    blockAds?: boolean;
    hideCookie?: boolean;
    quality?: number;
  }) {
    return this.client.screenshot(params);
  }
}
```

### `GeekflareModule`

```ts src/geekflare/geekflare.module.ts theme={null}
import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
import { GeekflareService } from "./geekflare.service";

@Module({
  imports: [ConfigModule],
  providers: [GeekflareService],
  exports: [GeekflareService],
})
export class GeekflareModule {}
```

### `AppModule`

Register `ConfigModule` globally so `ConfigService` is available everywhere, then import `GeekflareModule`.

```ts src/app.module.ts theme={null}
import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
import { GeekflareModule } from "./geekflare/geekflare.module";

@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true }), GeekflareModule],
})
export class AppModule {}
```

***

## Web Scraping

### DTOs

```ts src/scrape/dto/scrape.dto.ts theme={null}
import { IsString, IsUrl, IsOptional, IsBoolean } from "class-validator";

export class ScrapeDto {
  @IsUrl()
  url: string;

  @IsOptional()
  @IsBoolean()
  renderJS?: boolean;

  @IsOptional()
  @IsBoolean()
  blockAds?: boolean;

  @IsOptional()
  @IsString()
  format?: string;
}
```

### Controller

```ts src/scrape/scrape.controller.ts theme={null}
import {
  Body,
  Controller,
  Post,
  HttpException,
  HttpStatus,
} from "@nestjs/common";
import { GeekflareService } from "../geekflare/geekflare.service";
import { ScrapeDto } from "./dto/scrape.dto";

@Controller("scrape")
export class ScrapeController {
  constructor(private readonly geekflare: GeekflareService) {}

  @Post()
  async scrape(@Body() dto: ScrapeDto) {
    try {
      return await this.geekflare.webScrape({
        url: dto.url,
        renderJS: dto.renderJS ?? true,
        blockAds: dto.blockAds ?? true,
        format: dto.format ?? "html,markdown",
      });
    } catch (error: any) {
      throw new HttpException(
        error.message ?? "Scrape failed",
        error?.status ?? HttpStatus.INTERNAL_SERVER_ERROR,
      );
    }
  }
}
```

**Example request:**

```bash theme={null}
curl -X POST http://localhost:3000/scrape \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://toscrape.com/", "renderJS": true }'
```

***

## Search

### DTOs

```ts src/search/dto/search.dto.ts theme={null}
import {
  IsString,
  IsOptional,
  IsInt,
  IsArray,
  Min,
  Max,
} from "class-validator";

export class SearchDto {
  @IsString()
  query: string;

  @IsOptional()
  @IsInt()
  @Min(1)
  @Max(100)
  limit?: number;

  @IsOptional()
  @IsString()
  location?: string;

  @IsOptional()
  @IsString()
  source?: string;

  @IsOptional()
  @IsString()
  time?: string; // "d" | "w" | "m"

  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  includeDomains?: string[];

  @IsOptional()
  @IsArray()
  @IsString({ each: true })
  excludeDomains?: string[];
}
```

### Controller

```ts src/search/search.controller.ts theme={null}
import {
  Body,
  Controller,
  Post,
  HttpException,
  HttpStatus,
} from "@nestjs/common";
import { GeekflareService } from "../geekflare/geekflare.service";
import { SearchDto } from "./dto/search.dto";

@Controller("search")
export class SearchController {
  constructor(private readonly geekflare: GeekflareService) {}

  @Post()
  async search(@Body() dto: SearchDto) {
    try {
      return await this.geekflare.search({
        query: dto.query,
        limit: dto.limit ?? 10,
        location: dto.location ?? "us",
        source: dto.source ?? "web",
        time: dto.time,
        includeDomains: dto.includeDomains,
        excludeDomains: dto.excludeDomains,
      });
    } catch (error: any) {
      throw new HttpException(
        error.message ?? "Search failed",
        error?.status ?? HttpStatus.INTERNAL_SERVER_ERROR,
      );
    }
  }
}
```

**Example request:**

```bash theme={null}
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{ "query": "best NestJS practices", "limit": 5, "location": "us" }'
```

***

## Screenshot

### DTOs

```ts src/screenshot/dto/screenshot.dto.ts theme={null}
import {
  IsString,
  IsUrl,
  IsOptional,
  IsBoolean,
  IsInt,
  IsIn,
  Min,
  Max,
} from "class-validator";

export class ScreenshotDto {
  @IsUrl()
  url: string;

  @IsOptional()
  @IsIn(["png", "jpg", "webp"])
  type?: string;

  @IsOptional()
  @IsBoolean()
  fullPage?: boolean;

  @IsOptional()
  @IsIn(["desktop", "mobile"])
  device?: string;

  @IsOptional()
  @IsInt()
  viewportWidth?: number;

  @IsOptional()
  @IsInt()
  viewportHeight?: number;

  @IsOptional()
  @IsBoolean()
  blockAds?: boolean;

  @IsOptional()
  @IsBoolean()
  hideCookie?: boolean;

  @IsOptional()
  @IsInt()
  @Min(1)
  @Max(100)
  quality?: number;
}
```

### Controller

```ts src/screenshot/screenshot.controller.ts theme={null}
import {
  Body,
  Controller,
  Post,
  HttpException,
  HttpStatus,
} from "@nestjs/common";
import { GeekflareService } from "../geekflare/geekflare.service";
import { ScreenshotDto } from "./dto/screenshot.dto";

@Controller("screenshot")
export class ScreenshotController {
  constructor(private readonly geekflare: GeekflareService) {}

  @Post()
  async screenshot(@Body() dto: ScreenshotDto) {
    try {
      return await this.geekflare.screenshot({
        url: dto.url,
        type: dto.type ?? "png",
        fullPage: dto.fullPage ?? true,
        device: dto.device ?? "desktop",
        viewportWidth: dto.viewportWidth ?? 1280,
        viewportHeight: dto.viewportHeight ?? 800,
        blockAds: dto.blockAds ?? true,
        hideCookie: dto.hideCookie ?? true,
        quality: dto.quality ?? 90,
      });
    } catch (error: any) {
      throw new HttpException(
        error.message ?? "Screenshot failed",
        error?.status ?? HttpStatus.INTERNAL_SERVER_ERROR,
      );
    }
  }
}
```

**Example request:**

```bash theme={null}
curl -X POST http://localhost:3000/screenshot \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com", "fullPage": true, "type": "png" }'
```

***

## Wiring it all together

Register your feature modules in `AppModule`:

```ts src/app.module.ts theme={null}
import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
import { GeekflareModule } from "./geekflare/geekflare.module";
import { ScrapeController } from "./scrape/scrape.controller";
import { SearchController } from "./search/search.controller";
import { ScreenshotController } from "./screenshot/screenshot.controller";

@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true }), GeekflareModule],
  controllers: [ScrapeController, SearchController, ScreenshotController],
})
export class AppModule {}
```

Enable `ValidationPipe` globally in `main.ts` to activate the DTO decorators:

```ts src/main.ts theme={null}
import { NestFactory } from "@nestjs/core";
import { ValidationPipe } from "@nestjs/common";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true, // strip unknown properties
      forbidNonWhitelisted: true,
      transform: true, // auto-transform to DTO types
    }),
  );

  await app.listen(3000);
}
bootstrap();
```

***

## Error handling

NestJS maps `HttpException` to the correct HTTP status automatically. For a global catch-all, add an exception filter:

```ts src/filters/geekflare-exception.filter.ts theme={null}
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
  Logger,
} from "@nestjs/common";

@Catch()
export class GeekflareExceptionFilter implements ExceptionFilter {
  private readonly logger = new Logger(GeekflareExceptionFilter.name);

  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const error = exception as any;

    const status =
      exception instanceof HttpException
        ? exception.getStatus()
        : (error?.apiCode ?? HttpStatus.INTERNAL_SERVER_ERROR);

    const message =
      exception instanceof HttpException
        ? exception.message
        : (error?.message ?? "Internal server error");

    this.logger.error(`Geekflare API error [${status}]: ${message}`);

    response.status(status).json({
      statusCode: status,
      error: message,
      timestamp: new Date().toISOString(),
    });
  }
}
```

Register it in `main.ts`:

```ts theme={null}
app.useGlobalFilters(new GeekflareExceptionFilter());
```

### Common error codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `401` | Missing or invalid `x-api-key`    |
| `402` | API credits exhausted             |
| `403` | Endpoint requires a higher plan   |
| `404` | Wrong endpoint URL or HTTP method |
| `429` | Rate limit exceeded               |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

***

## Next steps

* [Cloudflare Workers quickstart](/quickstart/cloudflare-workers) — Edge-native `fetch` requests
* [Python quickstart](/quickstart/python) — Official Python SDK
* [API Reference](/endpoint/reference) — Full endpoint documentation
* [SDK on npm](https://www.npmjs.com/package/@geekflare/api-node)


# Next.js
Source: https://docs.geekflare.com/quickstart/nextjs

Use Geekflare in a Next.js application with Server Actions, Route Handlers, and Server Components.

The Geekflare SDK must only run **server-side** — your API key must never be exposed to the browser. Next.js makes this straightforward with Route Handlers, Server Actions, and Server Components.

## Prerequisites

* Next.js **14+** with the App Router
* Node.js **18+**
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Installation

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @geekflare/api-node
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install @geekflare/api-node
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @geekflare/api-node
    ```
  </Tab>
</Tabs>

## Set your API key

Add your API key to `.env.local`:

```bash .env.local theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

<Warning>
  `.env.local` is gitignored by default in Next.js. Never prefix this variable
  with `NEXT_PUBLIC_` — that would expose it to the browser.
</Warning>

## Shared client

Create a single client instance to reuse across your app:

```ts lib/geekflare.ts theme={null}
import { GeekflareClient } from "@geekflare/api-node";

export const geekflare = new GeekflareClient({
  apiKey: process.env.GEEKFLARE_API_KEY!,
});
```

***

## Web Scraping

### Route Handler

Accepts a POST request from your client-side code and returns scraped content.

```ts app/api/scrape/route.ts theme={null}
import { NextResponse } from "next/server";
import { geekflare } from "@/lib/geekflare";

export async function POST(request: Request) {
  const { url } = await request.json();

  if (!url) {
    return NextResponse.json({ error: "url is required" }, { status: 400 });
  }

  try {
    const result = await geekflare.webScrape({
      url,
      renderJS: true,
      blockAds: true,
      format: "html,markdown",
    });

    return NextResponse.json(result);
  } catch (error: any) {
    return NextResponse.json(
      { error: error.message ?? "Scrape failed" },
      { status: error?.status ?? 500 },
    );
  }
}
```

### Server Action

Use directly from Client Components without a round-trip to a route:

```ts app/actions.ts theme={null}
"use server";

import { geekflare } from "@/lib/geekflare";

export async function scrapeUrl(url: string) {
  const result = await geekflare.webScrape({
    url,
    renderJS: true,
    blockAds: true,
    format: "markdown",
  });

  return result;
}
```

### Server Component

Fetch and render scraped content directly in a Server Component:

```tsx app/scrape/page.tsx theme={null}
import { geekflare } from "@/lib/geekflare";

export default async function ScrapePage() {
  const result = await geekflare.webScrape({
    url: "https://toscrape.com/",
    format: "markdown",
  });

  // result.data is a URL pointing to the scraped output file
  return (
    <article className="prose mx-auto py-12">
      <h1>Scraped Content</h1>
      <p>
        Output file: <a href={result.data as string}>{result.data as string}</a>
      </p>
    </article>
  );
}
```

***

## Search

### Route Handler

```ts app/api/search/route.ts theme={null}
import { NextResponse } from "next/server";
import { geekflare } from "@/lib/geekflare";

export async function POST(request: Request) {
  const { query } = await request.json();

  if (!query) {
    return NextResponse.json({ error: "query is required" }, { status: 400 });
  }

  try {
    const result = await geekflare.search({
      query,
      limit: 10,
      location: "us",
      source: "web",
      format: "json",
    });

    return NextResponse.json(result);
  } catch (error: any) {
    return NextResponse.json(
      { error: error.message ?? "Search failed" },
      { status: error?.status ?? 500 },
    );
  }
}
```

### Server Action

```ts app/actions.ts theme={null}
"use server";

import { geekflare } from "@/lib/geekflare";

export async function searchWeb(query: string) {
  const result = await geekflare.search({
    query,
    limit: 10,
    location: "us",
    source: "web",
    format: "json",
  });

  return result.data ?? [];
}
```

### Server Component

```tsx app/search/page.tsx theme={null}
import { geekflare } from "@/lib/geekflare";

export default async function SearchPage({
  searchParams,
}: {
  searchParams: { q?: string };
}) {
  const query = searchParams.q ?? "Next.js best practices";

  const result = await geekflare.search({
    query,
    limit: 10,
    location: "us",
    format: "json",
  });

  return (
    <div className="max-w-2xl mx-auto py-12">
      <h1 className="text-2xl font-bold mb-6">Results for: {query}</h1>
      <ul className="space-y-4">
        {result.data?.map((item: any) => (
          <li key={item.url}>
            <a
              href={item.url}
              className="text-blue-600 hover:underline font-medium"
            >
              {item.title}
            </a>
            <p className="text-sm text-gray-600 mt-1">{item.snippet}</p>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

***

## Screenshot

### Route Handler

```ts app/api/screenshot/route.ts theme={null}
import { NextResponse } from "next/server";
import { geekflare } from "@/lib/geekflare";

export async function POST(request: Request) {
  const { url } = await request.json();

  if (!url) {
    return NextResponse.json({ error: "url is required" }, { status: 400 });
  }

  try {
    const result = await geekflare.screenshot({
      url,
      type: "png",
      fullPage: true,
      device: "desktop",
      viewportWidth: 1280,
      viewportHeight: 800,
      blockAds: true,
      hideCookie: true,
    });

    return NextResponse.json(result);
  } catch (error: any) {
    return NextResponse.json(
      { error: error.message ?? "Screenshot failed" },
      { status: error?.status ?? 500 },
    );
  }
}
```

### Server Component

Render the screenshot directly in a page using `next/image`:

```tsx app/preview/page.tsx theme={null}
import Image from "next/image";
import { geekflare } from "@/lib/geekflare";

export default async function PreviewPage() {
  const result = await geekflare.screenshot({
    url: "https://example.com",
    type: "png",
    fullPage: false,
    viewportWidth: 1280,
    viewportHeight: 800,
    blockAds: true,
    hideCookie: true,
  });

  // result.data is the screenshot URL directly
  const screenshotUrl = result.data as string;

  return (
    <div className="p-8">
      <h1 className="text-xl font-semibold mb-4">Site Preview</h1>
      {screenshotUrl && (
        <Image
          src={screenshotUrl}
          alt="Site screenshot"
          width={1280}
          height={800}
          className="rounded-lg border shadow"
        />
      )}
    </div>
  );
}
```

***

## Error handling

Handle errors consistently across Route Handlers and Server Actions.

### Common error codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `401` | Missing or invalid `x-api-key`    |
| `402` | API credits exhausted             |
| `403` | Endpoint requires a higher plan   |
| `404` | Wrong endpoint URL or HTTP method |
| `429` | Rate limit exceeded               |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

### Route Handler pattern

```ts theme={null}
try {
  const result = await geekflare.webScrape({ url });
  return NextResponse.json(result);
} catch (error: any) {
  const code = error?.apiCode ?? error?.status ?? 500;
  const message = error?.message ?? "An unexpected error occurred";

  if (code === 429) {
    return NextResponse.json(
      { error: "Rate limit exceeded. Please try again shortly." },
      { status: 429 },
    );
  }

  if (code === 402) {
    return NextResponse.json(
      { error: "API credits exhausted." },
      { status: 402 },
    );
  }

  return NextResponse.json({ error: message }, { status: code });
}
```

### Server Action pattern

```ts theme={null}
"use server";

export async function safeScrape(url: string) {
  try {
    const result = await geekflare.webScrape({ url, format: "markdown" });
    return { data: result.data, error: null };
  } catch (error: any) {
    return { data: null, error: error.message ?? "Failed to scrape" };
  }
}
```

Consume it safely in a Client Component:

```tsx theme={null}
const { data, error } = await safeScrape(url);

if (error) {
  return <p className="text-red-500">{error}</p>;
}
```

***

## Next steps

* [NestJS quickstart](/quickstart/nestjs) — Injectable services and modules
* [API Reference](/endpoint/reference) — Full endpoint documentation
* [SDK on npm](https://www.npmjs.com/package/@geekflare/api-node)


# Node.js
Source: https://docs.geekflare.com/quickstart/nodejs

Use Geekflare in Node.js or TypeScript project with the official SDK or raw fetch.

The official `@geekflare/api-node` SDK gives you full TypeScript support and handles auth, serialization, and response parsing out of the box. Raw `fetch` examples are included for dependency-free setups.

## Prerequisites

* Node.js **18+** (native `fetch` is stable from v18)
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Installation

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @geekflare/api-node
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install @geekflare/api-node
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @geekflare/api-node
    ```
  </Tab>
</Tabs>

## Set your API key

Create a `.env` file at your project root:

```bash .env theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

<Warning>Never commit your `.env` file. Add it to `.gitignore`.</Warning>

## Initialize the client

```ts theme={null}
import { GeekflareClient } from "@geekflare/api-node";

const client = new GeekflareClient({
  apiKey: process.env.GEEKFLARE_API_KEY!,
});
```

***

## Web Scraping

Scrape the full content of any URL. Returns HTML, Markdown, and more depending on the `format` you request.

<Tabs>
  <Tab title="SDK">
    ```ts theme={null}
    import { GeekflareClient } from "@geekflare/api-node";

    const client = new GeekflareClient({
      apiKey: process.env.GEEKFLARE_API_KEY!,
    });

    const result = await client.webScrape({
      url: "https://toscrape.com/",
      device: "desktop",
      renderJS: true,
      blockAds: true,
      format: "html,markdown",
    });

    console.log(result);
    ```
  </Tab>

  <Tab title="fetch">
    ```ts theme={null}
    const response = await fetch("https://api.geekflare.com/webscraping", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.GEEKFLARE_API_KEY!,
      },
      body: JSON.stringify({
        url: "https://toscrape.com/",
        device: "desktop",
        renderJS: true,
        blockAds: true,
        format: "html,markdown",
      }),
    });

    const result = await response.json();
    console.log(result);
    ```
  </Tab>
</Tabs>

**Key parameters:**

| Parameter      | Type                    | Description                         |
| -------------- | ----------------------- | ----------------------------------- |
| `url`          | `string`                | **Required.** The URL to scrape     |
| `device`       | `"desktop" \| "mobile"` | Emulate device type                 |
| `renderJS`     | `boolean`               | Wait for JavaScript to execute      |
| `blockAds`     | `boolean`               | Block ads before scraping           |
| `format`       | `string`                | Comma-separated: `html`, `markdown` |
| `proxyCountry` | `string`                | Route via country code, e.g. `"us"` |
| `stealth`      | `boolean`               | Enable stealth mode                 |
| `waitTime`     | `number`                | Extra wait time in seconds          |

**Example response:**

```json theme={null}
{
  "timestamp": 1779703261268,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "url": "https://toscrape.com/",
    "device": "desktop",
    "format": ["html-llm"],
    "blockAds": true,
    "renderJS": true,
    "stealth": false,
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": "https://example.com/9bulgk075ed9m3vhua5vcrp0.html"
}
```

The `data` field is a URL to the scraped output file. For full response details, see the [Web Scraping endpoint reference](https://docs.geekflare.com/api/endpoint/webscraping).

***

## Search

Run a web search and get ranked results with titles, URLs, and descriptions.

<Tabs>
  <Tab title="SDK">
    ```ts theme={null}
    import { GeekflareClient } from "@geekflare/api-node";

    const client = new GeekflareClient({
      apiKey: process.env.GEEKFLARE_API_KEY!,
    });

    const result = await client.search({
      query: "best static site generators",
      limit: 10,
      location: "us",
      source: "web",
      time: "m",     // past month
      format: "json",
    });

    console.log(result);
    ```
  </Tab>

  <Tab title="fetch">
    ```ts theme={null}
    const response = await fetch("https://api.geekflare.com/search", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.GEEKFLARE_API_KEY!,
      },
      body: JSON.stringify({
        query: "best static site generators",
        limit: 10,
        location: "us",
        source: "web",
        time: "m",
        format: "json",
      }),
    });

    const result = await response.json();
    console.log(result);
    ```
  </Tab>
</Tabs>

**Key parameters:**

| Parameter        | Type       | Description                                              |
| ---------------- | ---------- | -------------------------------------------------------- |
| `query`          | `string`   | **Required.** The search query                           |
| `limit`          | `number`   | Number of results (default: `10`)                        |
| `location`       | `string`   | Country code for localized results, e.g. `"us"`          |
| `source`         | `string`   | `"web"`, `"news"`, etc.                                  |
| `time`           | `string`   | Recency filter: `"d"` (day), `"w"` (week), `"m"` (month) |
| `includeDomains` | `string[]` | Only return results from these domains                   |
| `excludeDomains` | `string[]` | Exclude results from these domains                       |
| `groundedAnswer` | `boolean`  | Return an AI-grounded answer alongside results           |

**Example response:**

```json theme={null}
{
  "timestamp": 1779703261268,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "query": "best static site generators",
    "count": 10,
    "source": "web",
    "location": "us",
    "time": "m",
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": [
    {
      "title": "10 Best Static Site Generators in 2024",
      "url": "https://example.com/article",
      "snippet": "A comprehensive comparison of the top static site generators...",
      "date": "Dec 18, 2025",
      "position": 1,
      "content": "Full article cleaned for LLM consumption..."
    }
  ]
}
```

***

## Screenshot

Capture a screenshot of any URL. Returns a hosted image URL.

<Tabs>
  <Tab title="SDK">
    ```ts theme={null}
    import { GeekflareClient } from "@geekflare/api-node";

    const client = new GeekflareClient({
      apiKey: process.env.GEEKFLARE_API_KEY!,
    });

    const result = await client.screenshot({
      url: "https://example.com",
      type: "png",
      fullPage: true,
      device: "desktop",
      viewportWidth: 1280,
      viewportHeight: 800,
      blockAds: true,
      hideCookie: true,
      quality: 90,
    });

    console.log(result);
    ```
  </Tab>

  <Tab title="fetch">
    ```ts theme={null}
    const response = await fetch("https://api.geekflare.com/screenshot", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "x-api-key": process.env.GEEKFLARE_API_KEY!,
      },
      body: JSON.stringify({
        url: "https://example.com",
        type: "png",
        fullPage: true,
        device: "desktop",
        viewportWidth: 1280,
        viewportHeight: 800,
        blockAds: true,
        hideCookie: true,
        quality: 90,
      }),
    });

    const result = await response.json();
    console.log(result);
    ```
  </Tab>
</Tabs>

**Key parameters:**

| Parameter          | Type                       | Description                         |
| ------------------ | -------------------------- | ----------------------------------- |
| `url`              | `string`                   | **Required.** The URL to capture    |
| `type`             | `"png" \| "jpg" \| "webp"` | Output image format                 |
| `fullPage`         | `boolean`                  | Capture beyond the visible viewport |
| `device`           | `"desktop" \| "mobile"`    | Device emulation                    |
| `viewportWidth`    | `number`                   | Viewport width in pixels            |
| `viewportHeight`   | `number`                   | Viewport height in pixels           |
| `blockAds`         | `boolean`                  | Remove ads before capture           |
| `hideCookie`       | `boolean`                  | Hide cookie consent banners         |
| `skipCaptcha`      | `boolean`                  | Attempt to bypass CAPTCHA overlays  |
| `delay`            | `number`                   | Wait (seconds) before capture       |
| `quality`          | `number`                   | Image quality `1–100` (JPEG/WebP)   |
| `removeBackground` | `boolean`                  | Remove background (PNG only)        |

**Example response:**

```json theme={null}
{
  "timestamp": 1779703261268,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "url": "https://example.com",
    "type": "png",
    "device": "desktop",
    "fullPage": true,
    "blockAds": true,
    "hideCookie": true,
    "viewportWidth": 1280,
    "viewportHeight": 800,
    "quality": 90,
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": "https://geekflare.com/tests/screenshot/kbi6d206g87ituahb7icwtpr.png"
}
```

The `data` field is a direct URL to the screenshot image. See the [Screenshot endpoint reference](https://docs.geekflare.com/api/endpoint/screenshot).

***

## Error handling

The SDK throws on API errors. Wrap calls in `try/catch` and inspect the error for actionable codes.

```ts theme={null}
import { GeekflareClient } from "@geekflare/api-node";

const client = new GeekflareClient({
  apiKey: process.env.GEEKFLARE_API_KEY!,
});

try {
  const result = await client.webScrape({ url: "https://toscrape.com/" });
  console.log(result);
} catch (error: any) {
  console.error("API error:", error);

  const code = error?.apiCode ?? error?.status;

  switch (code) {
    case 401:
      console.error("Invalid or missing API key.");
      break;
    case 402:
      console.error("API credits exhausted. Top up at dash.geekflare.com.");
      break;
    case 403:
      console.error("This endpoint is not available on your current plan.");
      break;
    case 429:
      console.error("Rate limit exceeded. Back off and retry.");
      break;
    default:
      console.error(`Unexpected error [${code}]:`, error.message);
  }
}
```

### Common error codes

| Code  | Meaning                               |
| ----- | ------------------------------------- |
| `401` | Missing or invalid `x-api-key` header |
| `402` | API credits exhausted                 |
| `403` | Endpoint requires a higher plan       |
| `404` | Wrong endpoint URL or HTTP method     |
| `429` | Rate limit exceeded                   |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

***

## Next steps

* [Next.js quickstart](/quickstart/nextjs) — Server Actions and Route Handlers
* [NestJS quickstart](/quickstart/nestjs) — Injectable services and modules
* [API Reference](/endpoint/reference) — Full endpoint documentation
* [SDK on npm](https://www.npmjs.com/package/@geekflare/api-node)


# PHP
Source: https://docs.geekflare.com/quickstart/php

Use Geekflare in any PHP project with native cURL or the Guzzle HTTP client.

No official PHP SDK exists yet, but the Geekflare REST API is straightforward to call from PHP using either native cURL or the popular Guzzle HTTP client.

## Prerequisites

* PHP **8.0+**
* Composer
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Installation

No SDK is needed for cURL. To use Guzzle:

```bash theme={null}
composer require guzzlehttp/guzzle vlucas/phpdotenv
```

## Set your API key

```bash .env theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

Load it with `phpdotenv`:

```php theme={null}
require_once __DIR__ . '/vendor/autoload.php';

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

$apiKey = $_ENV['GEEKFLARE_API_KEY'];
```

<Warning>Never hardcode your API key. Add `.env` to `.gitignore`.</Warning>

***

## Web Scraping

<Tabs>
  <Tab title="cURL">
    ```php theme={null}
    <?php
    require_once __DIR__ . '/vendor/autoload.php';

    $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
    $dotenv->load();

    $apiKey = $_ENV['GEEKFLARE_API_KEY'];

    $payload = json_encode([
        'url'       => 'https://toscrape.com/',
        'renderJS'  => true,
        'blockAds'  => true,
        'format'    => 'html,markdown',
        'device'    => 'desktop',
    ]);

    $ch = curl_init('https://api.geekflare.com/webscraping');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'x-api-key: ' . $apiKey,
        ],
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        $error = json_decode($response, true);
        throw new RuntimeException("API error [{$error['apiCode']}]: {$error['message']}");
    }

    $result = json_decode($response, true);
    print_r($result['data']);
    ```
  </Tab>

  <Tab title="Guzzle">
    ```php theme={null}
    <?php
    require_once __DIR__ . '/vendor/autoload.php';

    use GuzzleHttp\Client;
    use GuzzleHttp\Exception\ClientException;

    $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
    $dotenv->load();

    $client = new Client([
        'base_uri' => 'https://api.geekflare.com',
        'headers'  => [
            'Content-Type' => 'application/json',
            'x-api-key'    => $_ENV['GEEKFLARE_API_KEY'],
        ],
    ]);

    $response = $client->post('/webscraping', [
        'json' => [
            'url'      => 'https://toscrape.com/',
            'renderJS' => true,
            'blockAds' => true,
            'format'   => 'html,markdown',
            'device'   => 'desktop',
        ],
    ]);

    $result = json_decode($response->getBody(), true);
    print_r($result['data']);
    ```
  </Tab>
</Tabs>

**Key parameters:**

| Parameter      | Type     | Description                         |
| -------------- | -------- | ----------------------------------- |
| `url`          | `string` | **Required.** The URL to scrape     |
| `renderJS`     | `bool`   | Wait for JavaScript to execute      |
| `blockAds`     | `bool`   | Block ads before scraping           |
| `format`       | `string` | Comma-separated: `html`, `markdown` |
| `device`       | `string` | `"desktop"` or `"mobile"`           |
| `proxyCountry` | `string` | Route via country code, e.g. `"us"` |
| `stealth`      | `bool`   | Enable stealth mode                 |
| `waitTime`     | `float`  | Extra wait in seconds               |

***

## Search

<Tabs>
  <Tab title="cURL">
    ```php theme={null}
    <?php
    require_once __DIR__ . '/vendor/autoload.php';

    $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
    $dotenv->load();

    $payload = json_encode([
        'query'    => 'best PHP frameworks 2024',
        'limit'    => 10,
        'location' => 'us',
        'source'   => 'web',
        'time'     => 'm',
        'format'   => 'json',
    ]);

    $ch = curl_init('https://api.geekflare.com/search');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'x-api-key: ' . $_ENV['GEEKFLARE_API_KEY'],
        ],
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $result = json_decode($response, true);

    foreach ($result['data'] as $item) {
        echo $item['title'] . ' — ' . $item['url'] . PHP_EOL;
        echo $item['snippet'] . PHP_EOL . PHP_EOL;
    }
    ```
  </Tab>

  <Tab title="Guzzle">
    ```php theme={null}
    <?php
    require_once __DIR__ . '/vendor/autoload.php';

    use GuzzleHttp\Client;

    $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
    $dotenv->load();

    $client = new Client([
        'base_uri' => 'https://api.geekflare.com',
        'headers'  => [
            'Content-Type' => 'application/json',
            'x-api-key'    => $_ENV['GEEKFLARE_API_KEY'],
        ],
    ]);

    $response = $client->post('/search', [
        'json' => [
            'query'    => 'best PHP frameworks 2024',
            'limit'    => 10,
            'location' => 'us',
            'source'   => 'web',
            'time'     => 'm',
            'format'   => 'json',
        ],
    ]);

    $result = json_decode($response->getBody(), true);

    foreach ($result['data'] as $item) {
        echo $item['title'] . ' — ' . $item['url'] . PHP_EOL;
        echo $item['snippet'] . PHP_EOL . PHP_EOL;
    }
    ```
  </Tab>
</Tabs>

***

## Screenshot

<Tabs>
  <Tab title="cURL">
    ```php theme={null}
    <?php
    require_once __DIR__ . '/vendor/autoload.php';

    $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
    $dotenv->load();

    $payload = json_encode([
        'url'            => 'https://example.com',
        'type'           => 'png',
        'fullPage'       => true,
        'device'         => 'desktop',
        'viewportWidth'  => 1280,
        'viewportHeight' => 800,
        'blockAds'       => true,
        'hideCookie'     => true,
        'quality'        => 90,
    ]);

    $ch = curl_init('https://api.geekflare.com/screenshot');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => $payload,
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'x-api-key: ' . $_ENV['GEEKFLARE_API_KEY'],
        ],
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $result = json_decode($response, true);
    // $result['data'] is the screenshot URL directly
    echo "Screenshot URL: " . $result['data'] . PHP_EOL;
    ```
  </Tab>

  <Tab title="Guzzle">
    ```php theme={null}
    <?php
    require_once __DIR__ . '/vendor/autoload.php';

    use GuzzleHttp\Client;

    $dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
    $dotenv->load();

    $client = new Client([
        'base_uri' => 'https://api.geekflare.com',
        'headers'  => [
            'Content-Type' => 'application/json',
            'x-api-key'    => $_ENV['GEEKFLARE_API_KEY'],
        ],
    ]);

    $response = $client->post('/screenshot', [
        'json' => [
            'url'            => 'https://example.com',
            'type'           => 'png',
            'fullPage'       => true,
            'device'         => 'desktop',
            'viewportWidth'  => 1280,
            'viewportHeight' => 800,
            'blockAds'       => true,
            'hideCookie'     => true,
            'quality'        => 90,
        ],
    ]);

    $result = json_decode($response->getBody(), true);
    // $result['data'] is the screenshot URL directly
    echo "Screenshot URL: " . $result['data'] . PHP_EOL;
    ```
  </Tab>
</Tabs>

***

## Error handling

<Tabs>
  <Tab title="cURL">
    ```php theme={null}
    <?php
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if (curl_errno($ch)) {
        throw new RuntimeException('cURL error: ' . curl_error($ch));
    }

    $result = json_decode($response, true);

    if ($httpCode !== 200 || $result['apiStatus'] !== 'success') {
        $code    = $result['apiCode'] ?? $httpCode;
        $message = $result['message'] ?? 'Unknown error';

        match ($code) {
            401 => throw new RuntimeException("Invalid or missing API key."),
            402 => throw new RuntimeException("API credits exhausted."),
            403 => throw new RuntimeException("Endpoint not available on your plan."),
            429 => throw new RuntimeException("Rate limit exceeded. Back off and retry."),
            default => throw new RuntimeException("API error [{$code}]: {$message}"),
        };
    }
    ```
  </Tab>

  <Tab title="Guzzle">
    ```php theme={null}
    <?php
    use GuzzleHttp\Exception\ClientException;
    use GuzzleHttp\Exception\ConnectException;

    try {
        $response = $client->post('/webscraping', ['json' => ['url' => 'https://toscrape.com/']]);
        $result = json_decode($response->getBody(), true);
        print_r($result['data']);

    } catch (ClientException $e) {
        $code = $e->getResponse()->getStatusCode();
        $body = json_decode($e->getResponse()->getBody(), true);
        $message = $body['message'] ?? 'Unknown error';

        match ($code) {
            401 => print("Invalid or missing API key.\n"),
            402 => print("API credits exhausted.\n"),
            403 => print("Endpoint not available on your plan.\n"),
            429 => print("Rate limit exceeded.\n"),
            default => print("API error [{$code}]: {$message}\n"),
        };

    } catch (ConnectException $e) {
        print("Connection error: " . $e->getMessage() . "\n");
    }
    ```
  </Tab>
</Tabs>

### Common error codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `401` | Missing or invalid `x-api-key`    |
| `402` | API credits exhausted             |
| `403` | Endpoint requires a higher plan   |
| `404` | Wrong endpoint URL or HTTP method |
| `429` | Rate limit exceeded               |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

***

## Next steps

* [Laravel quickstart](/quickstart/laravel) — Laravel HTTP client with service classes
* [API Reference](/endpoint/reference) — Full endpoint documentation


# Python
Source: https://docs.geekflare.com/quickstart/python

Use Geekflare in any Python project with the official SDK or the requests library.

The official `geekflare-api` SDK provides a Pythonic interface that handles auth and serialization. Raw `requests` examples are included for those who prefer no extra dependencies.

## Prerequisites

* Python **3.8+**
* `pip` or `uv`
* A Geekflare API key — [get one free](https://dash.geekflare.com)

## Installation

<Tabs>
  <Tab title="pip">
    ```bash theme={null}
    pip install geekflare-api
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv add geekflare-api
    ```
  </Tab>

  <Tab title="pip + requests (no SDK)">
    ```bash theme={null}
    pip install requests python-dotenv
    ```
  </Tab>
</Tabs>

## Set your API key

Create a `.env` file:

```bash .env theme={null}
GEEKFLARE_API_KEY=your_api_key_here
```

Load it in your script:

```python theme={null}
from dotenv import load_dotenv
import os

load_dotenv()
API_KEY = os.environ["GEEKFLARE_API_KEY"]
```

<Warning>Never hardcode your API key. Add `.env` to `.gitignore`.</Warning>

## Initialize the client

```python theme={null}
from geekflare_api.client import GeekflareClient

client = GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"])
```

The client is a context manager — use `with` to ensure the underlying HTTP session is closed:

```python theme={null}
with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
    # make calls here
    pass
```

***

## Web Scraping

<Tabs>
  <Tab title="SDK">
    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from geekflare_api.client import GeekflareClient
    from geekflare_api.models import WebScrapeDto

    load_dotenv()

    with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
        result = client.web_scrape(
            WebScrapeDto(
                url="https://toscrape.com/",
                renderJS=True,
                blockAds=True,
                format="html,markdown",
                device="desktop",
            )
        )
        print(result)
    ```
  </Tab>

  <Tab title="requests">
    ```python theme={null}
    import os
    import requests
    from dotenv import load_dotenv

    load_dotenv()

    response = requests.post(
        "https://api.geekflare.com/webscraping",
        headers={
            "Content-Type": "application/json",
            "x-api-key": os.environ["GEEKFLARE_API_KEY"],
        },
        json={
            "url": "https://toscrape.com/",
            "renderJS": True,
            "blockAds": True,
            "format": "html,markdown",
            "device": "desktop",
        },
    )

    response.raise_for_status()
    print(response.json())
    ```
  </Tab>
</Tabs>

**Key parameters:**

| Parameter      | Type    | Description                         |
| -------------- | ------- | ----------------------------------- |
| `url`          | `str`   | **Required.** The URL to scrape     |
| `renderJS`     | `bool`  | Wait for JavaScript to execute      |
| `blockAds`     | `bool`  | Block ads before scraping           |
| `format`       | `str`   | Comma-separated: `html`, `markdown` |
| `device`       | `str`   | `"desktop"` or `"mobile"`           |
| `proxyCountry` | `str`   | Route via country code, e.g. `"us"` |
| `stealth`      | `bool`  | Enable stealth mode                 |
| `waitTime`     | `float` | Extra wait time in seconds          |

**Example response:**

```json theme={null}
{
  "timestamp": 1779703261268,
  "apiStatus": "success",
  "apiCode": 200,
  "meta": {
    "url": "https://toscrape.com/",
    "device": "desktop",
    "format": ["html-llm"],
    "blockAds": true,
    "renderJS": true,
    "test": { "id": "mxqx9v9y0742lap6altwdteqd28t23nq" }
  },
  "data": "https://example.com/9bulgk075ed9m3vhua5vcrp0.html"
}
```

The `data` field is a URL to the scraped output file. See the [Web Scraping endpoint reference](https://docs.geekflare.com/api/endpoint/webscraping).

***

## Search

<Tabs>
  <Tab title="SDK">
    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from geekflare_api.client import GeekflareClient
    from geekflare_api.models import SearchDto

    load_dotenv()

    with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
        result = client.search(
            SearchDto(
                query="best Python web frameworks",
                limit=10,
                location="us",
                source="web",
                time="m",
                format="json",
            )
        )
        print(result)
    ```
  </Tab>

  <Tab title="requests">
    ```python theme={null}
    import os
    import requests
    from dotenv import load_dotenv

    load_dotenv()

    response = requests.post(
        "https://api.geekflare.com/search",
        headers={
            "Content-Type": "application/json",
            "x-api-key": os.environ["GEEKFLARE_API_KEY"],
        },
        json={
            "query": "best Python web frameworks",
            "limit": 10,
            "location": "us",
            "source": "web",
            "time": "m",
            "format": "json",
        },
    )

    response.raise_for_status()
    data = response.json()

    for item in data.get("data", []):
        print(f"{item['title']} — {item['url']}")
        print(item['snippet'])
    ```
  </Tab>
</Tabs>

**Key parameters:**

| Parameter        | Type        | Description                                              |
| ---------------- | ----------- | -------------------------------------------------------- |
| `query`          | `str`       | **Required.** The search query                           |
| `limit`          | `int`       | Number of results (default: `10`)                        |
| `location`       | `str`       | Country code for localized results, e.g. `"us"`          |
| `source`         | `str`       | `"web"`, `"news"`, etc.                                  |
| `time`           | `str`       | Recency filter: `"d"` (day), `"w"` (week), `"m"` (month) |
| `includeDomains` | `list[str]` | Only return results from these domains                   |
| `excludeDomains` | `list[str]` | Exclude results from these domains                       |

***

## Screenshot

<Tabs>
  <Tab title="SDK">
    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from geekflare_api.client import GeekflareClient
    from geekflare_api.models import ScreenshotDto

    load_dotenv()

    with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
        result = client.screenshot(
            ScreenshotDto(
                url="https://example.com",
                type="png",
                fullPage=True,
                device="desktop",
                viewportWidth=1280,
                viewportHeight=800,
                blockAds=True,
                hideCookie=True,
                quality=90,
            )
        )
        print(result)
    ```
  </Tab>

  <Tab title="requests">
    ```python theme={null}
    import os
    import requests
    from dotenv import load_dotenv

    load_dotenv()

    response = requests.post(
        "https://api.geekflare.com/screenshot",
        headers={
            "Content-Type": "application/json",
            "x-api-key": os.environ["GEEKFLARE_API_KEY"],
        },
        json={
            "url": "https://example.com",
            "type": "png",
            "fullPage": True,
            "device": "desktop",
            "viewportWidth": 1280,
            "viewportHeight": 800,
            "blockAds": True,
            "hideCookie": True,
            "quality": 90,
        },
    )

    response.raise_for_status()
    data = response.json()
    # data['data'] is the screenshot URL directly
    print("Screenshot URL:", data["data"])
    ```
  </Tab>
</Tabs>

***

## Error handling

<Tabs>
  <Tab title="SDK">
    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from geekflare_api.client import GeekflareClient
    from geekflare_api.models import WebScrapeDto
    from geekflare_api.exceptions import ApiException

    load_dotenv()

    try:
        with GeekflareClient(api_key=os.environ["GEEKFLARE_API_KEY"]) as client:
            result = client.web_scrape(WebScrapeDto(url="https://toscrape.com/"))
            print(result)

    except ApiException as e:
        print(f"API error {e.status}: {e.reason}")

        if e.status == 401:
            print("Invalid or missing API key.")
        elif e.status == 402:
            print("API credits exhausted. Top up at dash.geekflare.com.")
        elif e.status == 403:
            print("This endpoint is not available on your current plan.")
        elif e.status == 429:
            print("Rate limit exceeded. Back off and retry.")

    except Exception as e:
        print(f"Unexpected error: {e}")
    ```
  </Tab>

  <Tab title="requests">
    ```python theme={null}
    import os
    import requests
    from dotenv import load_dotenv

    load_dotenv()

    try:
        response = requests.post(
            "https://api.geekflare.com/webscraping",
            headers={
                "Content-Type": "application/json",
                "x-api-key": os.environ["GEEKFLARE_API_KEY"],
            },
            json={"url": "https://toscrape.com/"},
        )
        response.raise_for_status()
        print(response.json())

    except requests.HTTPError as e:
        code = e.response.status_code
        body = e.response.json()

        if code == 401:
            print("Invalid or missing API key.")
        elif code == 402:
            print("API credits exhausted.")
        elif code == 403:
            print("Endpoint not available on your plan.")
        elif code == 429:
            print("Rate limit exceeded. Back off and retry.")
        else:
            print(f"HTTP {code}: {body.get('message', 'Unknown error')}")

    except requests.ConnectionError:
        print("Network error. Check your internet connection.")
    ```
  </Tab>
</Tabs>

### Common error codes

| Code  | Meaning                           |
| ----- | --------------------------------- |
| `401` | Missing or invalid `x-api-key`    |
| `402` | API credits exhausted             |
| `403` | Endpoint requires a higher plan   |
| `404` | Wrong endpoint URL or HTTP method |
| `429` | Rate limit exceeded               |

<Tip>
  See [Rate Limit Exceeded](/rate-limit-exceeded) and [Credit
  Exhausted](/credit-exhausted) for strategies to handle these gracefully.
</Tip>

***

## Next steps

* [Django quickstart](/quickstart/django) — Views, services, and `python-decouple`
* [API Reference](/endpoint/reference) — Full endpoint documentation
* [SDK on PyPI](https://pypi.org/project/geekflare-api/)


# Rate Limit Exceeded Error
Source: https://docs.geekflare.com/rate-limit-exceeded

429 Too Many Requests (Rate Limit Exceeded)

When interacting with Geekflare, you might encounter an `HTTP 429 Too Many Requests` status code. This error indicates that you have sent too many requests in a given amount of time, exceeding the rate limits defined for your plan.

This document explains why you're seeing this error and what steps you can take to resolve and prevent it.

### Understanding Geekflare Rate Limits

To ensure fair usage and provide consistent performance for all users, Geekflare enforces rate limits on API requests. These limits specify the maximum number of requests you can make requests per second.

<Note> Your specific rate limit is determined by your active Geekflare plan — see the [per-plan RPS table](/intro#rate-limits) or [API Pricing](https://geekflare.com/api/pricing) for full plan details.</Note>

### When a 429 Error Occurs

When a `429 Too Many Requests` error occurs, Geekflare will return an HTTP 429 status code.

**Example API Response:**

```
HTTP/1.1 429 Too Many Requests
x-geekflare-ratelimit-second: 100
x-geekflare-ratelimit-remaining-second: 0
x-geekflare-ratelimit-reset: 1

{
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "apiStatus": "failure",
    "apiCode": 429
}
```

**Key Information in the Response:**

* **`x-geekflare-ratelimit-second` (Header)**: The maximum number of requests allowed per second for your plan.
* **`x-geekflare-ratelimit-remaining-second` (Header)**: The number of requests remaining in the current 1-second window. When this hits `0`, you'll likely receive a 429.
* **`x-geekflare-ratelimit-reset` (Header)**: How long until the current rate-limit window resets. Wait at least this long before retrying.

<Info>
  Every response also includes `x-geekflare-credits-used` and
  `x-geekflare-credits-remaining` so you can track your credit balance
  without a separate dashboard check — see [Best Practices](/best-practices#monitoring).
</Info>

### How to Resolve & Prevent 429 Errors

Encountering a 429 error is a signal to adjust your request patterns. Here are the recommended steps:

1. **Wait and Retry (Respect `x-geekflare-ratelimit-reset`)**
   * The simplest and most direct solution. When you receive a `429` error, **pause your requests for at least the duration specified in the `x-geekflare-ratelimit-reset` header.** After this period, you can safely retry your original request.
   * **Do NOT immediately retry** without waiting, as this will only exacerbate the problem and might lead to temporary IP blocking if repeated excessively.

2. **Implement Exponential Backoff with Jitter**
   * For more robust applications, especially when dealing with intermittent rate limits or other transient errors, implement an exponential backoff strategy.
   * **How it works:** If a request fails, wait a short period (e.g., 5 second) before retrying. If it fails again, double the wait time (10 seconds), then (15 seconds), and so on, up to a maximum number of retries or a maximum wait time.
   * **Add Jitter:** To prevent all your clients from retrying at the exact same moment, add a small random delay (jitter) to your backoff period. For example, instead of waiting exactly 2 seconds, wait between 1.5 and 2.5 seconds.

3. **Monitor Your Usage Proactively**
   * In your successful API responses, always look at the `x-geekflare-ratelimit-remaining-second` header. This tells you how many requests you have left in the current window.
   * By monitoring this header, you can anticipate hitting your limit and adjust your request pace *before* receiving a 429 error.

4. **Upgrade Your Plan**
   * If you consistently hit rate limits and your application genuinely requires higher throughput than your current plan allows, the most effective solution is to **upgrade your Geekflare plan.**
   * Higher-tier plans come with significantly increased rate limits.
   * **[Login to Dashboard and Upgrade](https://dash.geekflare.com/billing)**

5. **Contact Support**
   * If you believe you are encountering rate limits in error, or if you have a unique use case that requires custom rate limits beyond our standard plans, please don't hesitate to [contact our support team](https://geekflare.com/api/support).
   * Provide as much detail as possible, the approximate time of the errors, and your expected usage patterns.

See the [Error Code Reference](/error-codes) for other error codes, or [Best Practices](/best-practices) for retry and concurrency patterns that help avoid rate limits altogether.


# Teams & Workspaces
Source: https://docs.geekflare.com/teams

Teams features in Geekflare.

The Geekflare Teams feature allows you to collaborate with other developers and colleagues without sharing your personal login credentials.

By inviting team members to your workspace, developers can access API keys and view near real-time API logs for troubleshooting.

## Plan Availability & Limits

Teams are available on [all paid Geekflare plans](https://geekflare.com/api/pricing/). The maximum number of team members depends on your active subscription:

* **Free Plan:** 1 seat, personal use only
* **Starter Plan:** Up to 3 team members
* **Growth Plan:** Up to 5 team members
* **Business Plan:** Up to 25 team members

## Roles & Permissions

Geekflare uses a simple role-based access control (RBAC) system with two roles: **Owner** and **Member**.

| Permission              | Owner | Member |
| :---------------------- | :---: | :----: |
| View API Keys           |   ✅   |    ✅   |
| View API Audit Logs     |   ✅   |    ✅   |
| Switch Workspaces       |   ✅   |    ✅   |
| Invite / Remove Members |   ✅   |    ❌   |
| Rename Workspace        |   ✅   |    ❌   |
| View / Change Billing   |   ✅   |    ❌   |

## Managing Your Workspace

To manage your team, log in to the [Geekflare Dashboard](https://dash.geekflare.com/) and click on the **Members** tab in the left sidebar.

![API Members](https://cdn.geekflare.com/api-assets/api-members.png)

### Renaming Your Workspace

By default, your team is named **Personal Workspace**. To make it easier for your team to identify the account (e.g., "Acme Corp Dev"):

1. Go to the **Members** tab.
2. Hover over the workspace name at the top of the page.
3. Click the **Edit (Pencil) icon** next to the name.
4. Enter your new team name and save.

![Rename Workspace Name](https://cdn.geekflare.com/api-assets/rename-workspace.png)

### Inviting Team Members

*Note: Only Workspace Owners can invite new members.*

1. Navigate to the **Members** tab.
2. Click the **Invite Member** button in the top right.
3. Enter the colleague's email address and click **Send Invitation**.

![Invite Team Members](https://cdn.geekflare.com/api-assets/api-members-invite.png)

### The Invitation Process

Once invited, the user will receive an email with a link to join your workspace.

<Note>If the user does not already have a Geekflare account, they will be prompted to create one for free before joining.</Note>

## Switching Between Workspaces

If you are a member of multiple teams, you can switch between them using the **Workspace Switcher** located in the top header of the dashboard.

Geekflare dashboards are strictly context-aware. When you switch to a different workspace, the entire dashboard updates to reflect that specific team. This means:

* **API Keys:** You will only see the API keys for the currently active workspace.
* **API Logs:** The audit logs will only show requests made by the active workspace's API keys.
* **Usage Details:** The credit consumption and limits shown apply only to the active workspace.

Ensure you have the correct workspace selected in the header before copying an API key for your application!


# Unauthorized Error
Source: https://docs.geekflare.com/unauthorized

401 Unauthorized (Missing or Invalid API Key)

If your API requests are failing with the HTTP status code `401 Unauthorized`, it means the `x-api-key` header is either missing entirely or doesn't match a valid API key on your account.

## Sample Responses

**Missing API key:**

```json theme={null}
{
  "apiCode": 401,
  "message": "Missing x-api-key header"
}
```

**Invalid API key:**

```json theme={null}
{
  "apiCode": 401,
  "message": "Invalid x-api-key"
}
```

## How to Resolve

1. **Check the header name and casing.** The key must be sent in a header literally named `x-api-key` — not `Authorization`, `api-key`, or as a query parameter.

   ```bash theme={null}
   curl -X POST https://api.geekflare.com/webscraping \
     -H "x-api-key: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://example.com"}'
   ```

2. **Confirm the key itself is correct.** Copy it fresh from your [Dashboard](https://dash.geekflare.com/) rather than reusing a value from an old `.env` file or notes — a single missing character will trigger this error.

3. **Check for accidental whitespace or quotes.** A trailing newline or wrapping quotes copied from a config file can silently break the header value.

4. **Make sure the key belongs to the right workspace.** If you're a member of multiple [Teams & Workspaces](/teams), confirm you're using a key generated in the workspace you intend to bill against.

<Info>
  API keys are generated automatically when you create your Geekflare account
  and shown on your Dashboard. There is currently no key rotation or multiple-key
  support — each account has a single active key.
</Info>

## Need Help?

If you've confirmed your key is correct and still see this error, [contact support](https://geekflare.com/contact/?product=api).


# Using Proxies
Source: https://docs.geekflare.com/using-proxies

Geekflare Proxy Support

Bypass IP blocking and geo-restrictions by routing your requests through our premium proxies. This ensures high success rates for scraping and monitoring tasks.

The following Geekflare endpoints support the `proxyCountry` parameter:

* Web Scraping
* Meta Scraping
* Broken Link Check
* Lighthouse
* Mixed Content
* Screenshot
* Site Load Time
* Site Status
* URL Redirection Checker
* PDF Generator

<Note>
  Web Scraping also supports `proxyMode` (`false` / `auto` / `true`, default
  `false`) for finer-grained control over when the proxy is used. See [Proxy
  Routing](/guides/web-scraping#proxy-routing) in the Web Scraping guide.
</Note>

Supported Country Codes

* US (United States)
* GB (United Kingdom)
* DE (Germany)
* IN (India)
* View [complete country ISO code list](https://www.nationsonline.org/oneworld/country_code_list.htm).

An example of using Proxy in API requests.

```json theme={null}
{
    "url": "https://example.com",
    "proxyCountry": "de"
}
```


# Web Scraping Output Format
Source: https://docs.geekflare.com/web-scraping-output-format

Available output format types for Geekflare's Web Scraping API.

[Geekflare's Web Scraping API](/guides/web-scraping#output-formats) supports 7 output formats via the `format` parameter.

Whether you are archiving full web pages, extracting structured data, or feeding Retrieval-Augmented Generation (RAG) pipelines, you can request the exact data structure you need.

### The `-llm` Optimized Formats

For AI developers, we offer specialized `-llm` formats. These formats run our semantic cleaning engine before returning the response. They automatically strip out boilerplate, navigation bars, footers, sidebars, advertisements, and hidden elements, returning **only the primary content** of the page.

Using `-llm` formats dramatically reduces noise, improves LLM inference accuracy, and saves massive amounts of tokens.

## Format Reference

You can pass one of the following string values into the `format` parameter of your API request.

| Format         | Description                                                                                                         | Best For                                                        | Avg. Token Savings\*  |
| :------------- | :------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------- | :-------------------- |
| `markdown-llm` | **(Recommended for AI)** The primary content of the page, converted to clean Markdown.                              | RAG pipelines, AI Agents, LLM.                                  | **\~75%** vs raw HTML |
| `text-llm`     | The primary content of the page as raw text. Strips all HTML tags, Markdown formatting, and structural data.        | Vector embeddings, traditional NLP, maximum token efficiency.   | **\~85%** vs raw HTML |
| `html-llm`     | The primary content of the page in HTML format. Strips out all `<script>`, `<style>`, `<nav>`, and `<footer>` tags. | AI applications requiring DOM structure, semantic HTML parsing. | **\~60%** vs raw HTML |
| `markdown`     | The entire rendered page converted to Markdown, including navigation links, sidebars, and footer text.              | Full-page archiving, layout analysis.                           | **\~60%** vs raw HTML |
| `text`         | The entire rendered page as raw text. Contains no HTML tags, but includes all boilerplate text.                     | Keyword density checks, regex matching.                         | **\~70%** vs raw HTML |
| `html`         | The raw, unmodified HTML DOM of the page as it appears in the browser.                                              | Traditional web scraping, republishing.                         | -                     |
| `json`         | Structured JSON output alongside the DOM.                                                                           | Data analysts, structured databases.                            | -                     |

*\*Token savings are estimates based on average news articles and blog posts compared to processing the raw HTML DOM.*

## Example Usage

To request an LLM-optimized Markdown response, simply set the `format` parameter in your JSON payload.

**API request to get Markdown LLM format:**

```json theme={null}
POST https://api.geekflare.com/webscraping

{
  "url": "https://example.com/long-article",
  "format": "markdown-llm"
}
```

## Choosing the Right Format for AI

If you are building an AI application, choosing between the `-llm` formats depends on your specific pipeline:

1. **Use `markdown-llm`** when you need to chunk data for a Vector Database. Markdown preserves `## Headings`, which chunking algorithms use to keep contextual ideas together. It also preserves data tables.
2. **Use `text-llm`** when you are doing massive batch processing and need the absolute lowest token count possible, or when simply generating mathematical vector embeddings where structural tags are unnecessary.
3. **Use `html-llm`** when you are passing data to an LLM that has been specifically fine-tuned to read DOM structures and CSS classes.