> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/firecrawl/firecrawl/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Search the web and optionally scrape search results

## POST /v1/search

Search the web using Firecrawl's search engine and optionally scrape the content from the search results.

### Authentication

Requires Bearer token authentication. Include your API key in the Authorization header:

```
Authorization: Bearer fc-YOUR_API_KEY
```

## Request Body

<ParamField path="query" type="string" required>
  The search query
</ParamField>

<ParamField path="limit" type="integer" default="5">
  Maximum number of results to return. Minimum: 1, Maximum: 100
</ParamField>

<ParamField path="tbs" type="string">
  Time-based search parameter for filtering results by time period
</ParamField>

<ParamField path="location" type="string">
  Location parameter for search results
</ParamField>

<ParamField path="timeout" type="integer" default="60000">
  Timeout in milliseconds
</ParamField>

<ParamField path="ignoreInvalidURLs" type="boolean" default="false">
  Excludes URLs from the search results that are invalid for other Firecrawl endpoints. This helps reduce errors if you are piping data from search into other Firecrawl API endpoints.
</ParamField>

<ParamField path="scrapeOptions" type="object">
  Options for scraping search results

  <ParamField path="scrapeOptions.formats" type="array">
    Formats to include in the scraped output. Options: `markdown`, `html`, `rawHtml`, `links`, `screenshot`, `screenshot@fullPage`, `json`, `branding`
  </ParamField>
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates whether the request was successful
</ResponseField>

<ResponseField name="data" type="array">
  Array of search results

  <ResponseField name="data[].title" type="string">
    Title from search result
  </ResponseField>

  <ResponseField name="data[].description" type="string">
    Description from search result
  </ResponseField>

  <ResponseField name="data[].url" type="string">
    URL of the search result
  </ResponseField>

  <ResponseField name="data[].markdown" type="string" nullable>
    Markdown content if scraping was requested
  </ResponseField>

  <ResponseField name="data[].html" type="string" nullable>
    HTML content if requested in formats
  </ResponseField>

  <ResponseField name="data[].rawHtml" type="string" nullable>
    Raw HTML content if requested in formats
  </ResponseField>

  <ResponseField name="data[].links" type="array">
    Links found if requested in formats
  </ResponseField>

  <ResponseField name="data[].screenshot" type="string" nullable>
    Screenshot URL if requested in formats
  </ResponseField>

  <ResponseField name="data[].metadata" type="object">
    Metadata about the scraped page

    <ResponseField name="data[].metadata.title" type="string">
      Page title
    </ResponseField>

    <ResponseField name="data[].metadata.description" type="string">
      Page description
    </ResponseField>

    <ResponseField name="data[].metadata.sourceURL" type="string">
      Source URL
    </ResponseField>

    <ResponseField name="data[].metadata.statusCode" type="integer">
      HTTP status code
    </ResponseField>

    <ResponseField name="data[].metadata.error" type="string" nullable>
      Error message if scraping failed
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="warning" type="string" nullable>
  Warning message if any issues occurred
</ResponseField>

## Examples

### Basic Search

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.firecrawl.dev/v1/search' \
    -H 'Authorization: Bearer fc-YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "firecrawl web scraping",
      "limit": 5
    }'
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR_API_KEY")

  results = app.search("firecrawl web scraping", limit=5)
  for result in results.data:
      print(f"{result.title}: {result.url}")
  ```

  ```javascript JavaScript theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

  const results = await app.search('firecrawl web scraping', { limit: 5 });
  results.data.forEach(result => {
    console.log(`${result.title}: ${result.url}`);
  });
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "title": "Firecrawl - The Web Data API for AI",
      "description": "The web crawling, scraping, and search API for AI.",
      "url": "https://www.firecrawl.dev/"
    },
    {
      "title": "Firecrawl Documentation",
      "description": "Learn how to use Firecrawl to scrape and crawl websites.",
      "url": "https://docs.firecrawl.dev/"
    }
  ]
}
```

### Search with Content Scraping

Get the full content of search results:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://api.firecrawl.dev/v1/search' \
    -H 'Authorization: Bearer fc-YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "firecrawl pricing",
      "limit": 3,
      "scrapeOptions": {
        "formats": ["markdown", "links"]
      }
    }'
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  app = Firecrawl(api_key="fc-YOUR_API_KEY")

  results = app.search(
      "firecrawl pricing",
      limit=3,
      scrape_options={
          "formats": ["markdown", "links"]
      }
  )

  for result in results.data:
      print(f"Title: {result.title}")
      print(f"URL: {result.url}")
      if result.markdown:
          print(f"Content: {result.markdown[:200]}...")
  ```

  ```javascript JavaScript theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

  const results = await app.search('firecrawl pricing', {
    limit: 3,
    scrapeOptions: {
      formats: ['markdown', 'links']
    }
  });

  results.data.forEach(result => {
    console.log(`Title: ${result.title}`);
    console.log(`URL: ${result.url}`);
    if (result.markdown) {
      console.log(`Content: ${result.markdown.substring(0, 200)}...`);
    }
  });
  ```
</CodeGroup>

## Error Responses

<ResponseField name="408" type="object">
  **Request Timeout** - Request timed out

  ```json theme={null}
  {
    "success": false,
    "error": "Request timed out"
  }
  ```
</ResponseField>

<ResponseField name="500" type="object">
  **Server Error** - An unexpected error occurred on the server

  ```json theme={null}
  {
    "success": false,
    "error": "An unexpected error occurred on the server."
  }
  ```
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.