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

# Web Search

> Enable real-time web search capabilities in your AI applications

## Overview

The BLACKBOX AI API provides powerful web search capabilities through the `blackbox-search` model. This feature allows your AI applications to access real-time information from the web, providing up-to-date answers with cited sources.

## Key Features

* **Real-time Information**: Access current data from the web
* **Source Citations**: Get URLs and titles of sources used
* **Seamless Integration**: Works with the standard chat completions API
* **Automatic Context**: Web results are automatically incorporated into responses

## Using Web Search

To enable web search, simply use the `blackbox-search` model in your chat completion requests:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  # Public api users: use https://api.blackbox.ai/v1/chat/completions
  curl --location 'https://enterprise.blackbox.ai/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "blackbox-search",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant that provides accurate, up-to-date information."
      },
      {
        "role": "user",
        "content": "What are the latest developments in AI from OpenAI?"
      }
    ],
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  from openai import OpenAI
  import os

  client = OpenAI(
      api_key=os.environ.get("BLACKBOX_API_KEY"),
      # Public api users: use https://api.blackbox.ai
      base_url="https://enterprise.blackbox.ai",
  )

  response = client.chat.completions.create(
      model="blackbox-search",
      messages=[
          {
              "role": "system",
              "content": "You are a helpful assistant that provides accurate, up-to-date information."
          },
          {
              "role": "user",
              "content": "What are the latest developments in AI from OpenAI?"
          }
      ],
      stream=False
  )

  print(response.choices[0].message.content)

  # Access citations if available
  if hasattr(response.choices[0].message, 'annotations'):
      for annotation in response.choices[0].message.annotations:
          if annotation.type == 'url_citation':
              print(f"\nSource: {annotation.url_citation.title}")
              print(f"URL: {annotation.url_citation.url}")
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  import OpenAI from 'openai';

  const client = new OpenAI({
    apiKey: process.env.BLACKBOX_API_KEY,
    // Public api users: use https://api.blackbox.ai
    baseURL: 'https://enterprise.blackbox.ai',
  });

  async function searchWeb() {
    const response = await client.chat.completions.create({
      model: 'blackbox-search',
      messages: [
        {
          role: 'system',
          content: 'You are a helpful assistant that provides accurate, up-to-date information.'
        },
        {
          role: 'user',
          content: 'What are the latest developments in AI from OpenAI?'
        }
      ],
      stream: false
    });

    console.log(response.choices[0].message.content);

    // Access citations if available
    if (response.choices[0].message.annotations) {
      response.choices[0].message.annotations.forEach(annotation => {
        if (annotation.type === 'url_citation') {
          console.log(`\nSource: ${annotation.url_citation.title}`);
          console.log(`URL: ${annotation.url_citation.url}`);
        }
      });
    }
  }

  searchWeb();
  ```
</CodeGroup>

## Response Format

When using web search, the response includes an `annotations` array containing URL citations:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "gen-...",
  "created": 1757140020,
  "model": "blackbox-search",
  "object": "chat.completion",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Here's the latest news I found: OpenAI recently announced...",
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "url": "https://www.example.com/openai-news",
              "title": "Latest OpenAI Developments",
              "content": "Content of the web search result",
              "start_index": 100,
              "end_index": 200
            }
          }
        ]
      }
    }
  ],
  "usage": {
    "completion_tokens": 150,
    "prompt_tokens": 25,
    "total_tokens": 175
  }
}
```

## Annotations Structure

<ResponseField name="annotations" type="array">
  Array of annotation objects containing source citations.

  <Expandable title="Annotation Object">
    <ResponseField name="type" type="string">
      Type of annotation. Currently supports `url_citation`.
    </ResponseField>

    <ResponseField name="url_citation" type="object">
      Citation information for web sources.

      <Expandable title="URL Citation Object">
        <ResponseField name="url" type="string">
          The URL of the cited source.
        </ResponseField>

        <ResponseField name="title" type="string">
          The title of the web page or article.
        </ResponseField>

        <ResponseField name="content" type="string">
          Excerpt or summary of the content from the source (if available).
        </ResponseField>

        <ResponseField name="start_index" type="integer">
          The character index where the citation begins in the message content.
        </ResponseField>

        <ResponseField name="end_index" type="integer">
          The character index where the citation ends in the message content.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Use Cases

##### News and Current Events

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
response = client.chat.completions.create(
    model="blackbox-search",
    messages=[
        {"role": "user", "content": "What are today's top technology news?"}
    ]
)
```

##### Research and Fact-Checking

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
response = client.chat.completions.create(
    model="blackbox-search",
    messages=[
        {"role": "user", "content": "What is the current population of Tokyo?"}
    ]
)
```

##### Product Information

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
response = client.chat.completions.create(
    model="blackbox-search",
    messages=[
        {"role": "user", "content": "Compare the latest iPhone and Samsung Galaxy models"}
    ]
)
```

##### Market Data

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
response = client.chat.completions.create(
    model="blackbox-search",
    messages=[
        {"role": "user", "content": "What is the current price of Bitcoin?"}
    ]
)
```

## Best Practices

1. **Be Specific**: Provide clear, specific queries for better search results
2. **Use System Messages**: Set context about the type of information needed
3. **Handle Citations**: Always check for and display source citations to users
4. **Rate Limiting**: Be mindful of API rate limits when making frequent searches
5. **Verify Information**: While web search provides current data, always encourage users to verify critical information

## Streaming with Web Search

Web search works seamlessly with streaming responses:

```python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
stream = client.chat.completions.create(
    model="blackbox-search",
    messages=[
        {"role": "user", "content": "Latest AI breakthroughs in 2025"}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

## Pricing

The `blackbox-search` model includes web search capabilities at the following rates:

* **Input**: \$0.0002 per 1K tokens
* **Output**: \$0.0005 per 1K tokens
* **Web Search**: \$0.03 for 1 search query (includes X/Twitter search)

See the [Inference](/api-reference/models/chat-models) page for complete pricing information.

## Related Resources

<CardGroup cols={2}>
  <Card title="Chat Completions" icon="message" href="/api-reference/chat">
    Learn about the chat completions API
  </Card>

  <Card title="Chat Models" icon="brain" href="/api-reference/models/chat-models">
    Explore all available chat models
  </Card>

  <Card title="Sample Usage" icon="code" href="/api-reference/sample-usage">
    See more API usage examples
  </Card>

  <Card title="CLI Web Search" icon="terminal" href="/features/blackbox-cli/key-features#web-search--real-time-information">
    Use web search in BLACKBOX CLI
  </Card>
</CardGroup>