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

# Batch Search

> Process large volumes of search queries asynchronously at a 50% cost reduction.

## Overview

The Batch Search API lets you submit a file containing multiple search queries and retrieve all results once processing is complete. Instead of making thousands of individual API calls, you upload a single `.jsonl` file, poll for completion, and download the results.

Ideal for financial institutions that want to stay up to date on the latest news and events related to their entire portfolio.

For example, you can schedule a daily batch of queries to run early in the morning, retrieve all the information that could impact your portfolio, and present it to your team right when they start their day.

## Key benefits

✅ **50% cost reduction**: \$0.0075 per query unit vs \$0.015 in fast mode <br />
✅ **No client-side scaling**: no rate limiting, connection pooling, or retry logic <br />
✅ **Single upload, single download**: one `.jsonl` file in, one `.jsonl` file out <br />
✅ **Same query capabilities**: supports all Search API filters of the `fast` search mode<br />

## How it works

The Batch Search workflow has four steps:

<Steps>
  <Step title="Create a batch job">
    The endpoint will return a `batch_id` and a `presigned_url` for uploading your input file.
  </Step>

  <Step title="Upload your input file">
    Upload your `.jsonl` file to the `presigned_url`.
  </Step>

  <Step title="Poll for completion">
    Check the job status using the `batch_id`.
    The status will progress through `pending` → `processing` → `completed`.
    During this time, you can monitor the `estimated_completion_time` which is a dynamic ISO 8601 timestamp that continuously updates to reflect when the job is expected to finish.
  </Step>

  <Step title="Download results">
    Once the status is `completed`, the response includes an `output_file_url` to download your results.
  </Step>
</Steps>

## Input file format

Your input file must be in `.jsonl` format (JSON Lines), where each line is a JSON object containing a `query` field with a standard [Search Documents](/api-reference/search/search-documents) request body.

```json theme={null}
{"query": {"text": "Impact of tariffs on semiconductor industry", "filters": {"timestamp": {"start": "2026-01-01", "end": "2026-02-24"}}, "max_chunks": 10}}
{"query": {"text": "Central bank interest rate decisions", "filters": {"timestamp": {"start": "2026-01-01", "end": "2026-02-24"}}, "max_chunks": 10}}
{"query": {"text": "Oil supply disruptions", "filters": {"timestamp": {"start": "2026-01-01", "end": "2026-02-24"}}, "max_chunks": 10}}
```

Each line is processed as an independent search request, so you can use different filters, topics, and time ranges across queries within the same batch.

## Output file format

The output file is also in `.jsonl` format. Each line contains:

| Field         | Description                                            |
| ------------- | ------------------------------------------------------ |
| `status`      | `success`, `error`, `timeout`, or `exception`          |
| `response`    | The Search response for this query                     |
| `line_number` | Matches the line number from your original input file  |
| `query`       | The original search query you submitted                |
| `error`       | Error description (only present if the request failed) |

### Output file example

The output file contains a JSON object for each line of the input file:

<img alt="Batch Search output file" src="https://mintcdn.com/ravenpackinternational/ar_vT1Y_C2qE1nuz/images/how-to-guides/search/batch-search/batch_search_output.png?fit=max&auto=format&n=ar_vT1Y_C2qE1nuz&q=85&s=36c3241a825f29945aaa0440d45c252d" width="700" data-path="images/how-to-guides/search/batch-search/batch_search_output.png" />

## Try it out

<Tabs>
  <Tab title="Postman">
    We provide a ready-to-use Postman collection that includes all Batch Search endpoints pre-configured.

    <Card title="Download Postman Collection" icon="rocket" href="https://github.com/Bigdata-com/bigdata-docs-resources/tree/main/how_to_guides/api_batch_search">
      Get the Postman collection and environment files from our GitHub repository.
    </Card>

    The collection includes four requests:

    <img alt="Batch Search Postman collection" src="https://mintcdn.com/ravenpackinternational/SmzZl_pmoQDpiF9j/images/how-to-guides/search/batch-search/batch-serach-postman.png?fit=max&auto=format&n=SmzZl_pmoQDpiF9j&q=85&s=681321c748a0a3784a69dbb475106648" width="450" data-path="images/how-to-guides/search/batch-search/batch-serach-postman.png" />

    1. **Create pre-signed URL to upload the batch**: Creates a new batch job
    2. **Upload search batch**: Uploads your `.jsonl` file
    3. **Get batch status**: Checks the current status
    4. **Get response**: Downloads the results

    <Tip>
      Import both the collection (`.postman_collection.json`) and the environment (`.postman_environment.json`) files into Postman. Set your API key in the environment variables before running the requests.
    </Tip>
  </Tab>

  <Tab title="Python">
    We provide a ready-to-use Python script that runs the complete Batch Search workflow end to end.

    <Card title="Download Python Script" icon="python" href="https://github.com/Bigdata-com/bigdata-docs-resources/blob/main/how_to_guides/api_batch_search/how-to-guide_batch-search.py">
      Get the Python script from our GitHub repository.
    </Card>

    **1. Install dependencies**

    ```bash theme={null}
    pip install requests
    ```

    **2. Set your API key**

    ```bash theme={null}
    export BIGDATA_API_KEY="your-api-key"
    ```

    **3. Run the script**

    ```bash theme={null}
    python how-to-guide_batch-search.py
    ```

    The script will create an example input file with three search queries, schedule the batch, monitor its status, and download the results once processing completes.

    <img alt="Batch Search Python sample output" src="https://mintcdn.com/ravenpackinternational/gsYM0v9gc2tE6I0f/images/how-to-guides/search/batch-search/batch_search_python_sample.png?fit=max&auto=format&n=gsYM0v9gc2tE6I0f&q=85&s=541563d0221a738a421728ae1492d7a9" width="700" data-path="images/how-to-guides/search/batch-search/batch_search_python_sample.png" />
  </Tab>
</Tabs>

## Related resources

* [Batch Search cookbook](/use-cases/search-service/one_job_for_thousands_of_companies): Real-world use case of Batch Search
* [Batch Search API Reference](/api-reference/batch-search/create-a-batch-job): Official API reference