> For a complete page index of the Captain API documentation, fetch https://docs.filesearch.dev/llms.txt?excludeSpec=true

# Batch Search Datasets

POST https://api.filesearch.dev/v2/datasets/batch-search
Content-Type: application/json

Search for articles across multiple news datasets in a single request.

Searches the same query across all specified datasets simultaneously with
combined `site:` operators for efficient multi-source search.

**Supported Datasets:**
nytimes, washpost, sfstandard, sacbee, sfchronicle, newyorker, theatlantic, sjmercury, latimes

**Example:**

```json
POST /v2/datasets/batch-search
{
    "q": "artificial intelligence regulation",
    "datasets": ["nytimes", "washpost", "theatlantic"],
    "limit": 20
}
```

**Headers:**

* `Authorization`: Bearer \{api\_key}
* `X-Organization-ID`: Organization UUID

Reference: https://docs.filesearch.dev/reference/datasets/articles/batch-search-datasets

## Request

### Body (application/json)

This endpoint expects a BatchSearchRequest.

- `q` (string, required) — Search query
- `author` (string, optional, nullable) — Filter results by author/byline name. Appended as quoted phrase to search query.
- `datasets` (list of string, optional, nullable) — List of dataset names to search across. Defaults to all datasets if not provided.
- `limit` (integer, optional, default: 10) — Max results per dataset

## Response

### 200

Successful Response

- `query` (string, required)
- `datasets_searched` (list of string, optional)
- `errors` (map from string to string, optional)
- `results` (list of DatasetSearchResult, optional)
- `results_by_dataset` (map from string to list of DatasetSearchResult, optional)
- `total_results` (integer, optional, default: 0)

## Errors

### 400 Bad Request Error

Invalid request

- `error` (string, required)
- `message` (string, required)
- `details` (ErrorResponseV2Details, optional, nullable)
- `path` (string, optional, nullable)
- `success` (boolean, optional, default: false)

### 401 Unauthorized Error

Missing or invalid API key

- `error` (string, required)
- `message` (string, required)
- `details` (ErrorResponseV2Details, optional, nullable)
- `path` (string, optional, nullable)
- `success` (boolean, optional, default: false)

### 403 Forbidden Error

API key does not belong to organization

- `error` (string, required) — `datasets_access_denied` when the organization is not entitled to the dataset, `HTTP_ERROR` otherwise.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `reason` (string, optional) — Why access was denied, for example `not_enabled`. Present only on `datasets_access_denied`.
- `status_code` (integer, optional) — The HTTP status code. Present only on `HTTP_ERROR`.

### 500 Internal Server Error

Internal server error

- `error` (string, required)
- `message` (string, required)
- `details` (ErrorResponseV2Details, optional, nullable)
- `path` (string, optional, nullable)
- `success` (boolean, optional, default: false)

### 503 Service Unavailable Error

Search service not configured

- `error` (string, required)
- `message` (string, required)
- `details` (ErrorResponseV2Details, optional, nullable)
- `path` (string, optional, nullable)
- `success` (boolean, optional, default: false)

## Types

### DatasetSearchResult

Individual search result from a dataset search

- `title` (string, required)
- `url` (string, required)
- `author` (string, optional, nullable) — Article author/byline if available
- `date` (string, optional, nullable) — Publication date if available
- `snippet` (string, optional, nullable) — Text snippet from the search result
- `source` (string, optional, nullable) — Source display name

### ErrorResponseV2Details

## Examples

**Request**

```json
{
  "q": "BRCA1",
  "datasets": [
    "nejm"
  ],
  "limit": 2
}
```

**Response**

```json
{
  "query": "BRCA1",
  "datasets_searched": [
    "nejm"
  ],
  "errors": {},
  "results": [
    {
      "title": "Bevacizumab for BRCA1/2 -Mutated Triple-Negative Breast Cancer",
      "url": "https://clinician.nejm.org/nejm-jw.NA47412?show-author=true&author-id=AU1223",
      "author": null,
      "date": "06/27/2026, 07:00 PM, +0000 UTC",
      "snippet": null,
      "source": "NEJM"
    },
    {
      "title": "Adjuvant Olaparib for Patients with BRCA1 - or BRCA2 -Mutated Breast Cancer",
      "url": "https://www.nejm.org/doi/full/10.1056/NEJMoa2105215",
      "author": null,
      "date": "06/03/2021, 07:00 AM, +0000 UTC",
      "snippet": null,
      "source": "NEJM"
    }
  ],
  "results_by_dataset": {
    "nejm": [
      {
        "title": "Bevacizumab for BRCA1/2 -Mutated Triple-Negative Breast Cancer",
        "url": "https://clinician.nejm.org/nejm-jw.NA47412?show-author=true&author-id=AU1223",
        "author": null,
        "date": "06/27/2026, 07:00 PM, +0000 UTC",
        "snippet": null,
        "source": "NEJM"
      },
      {
        "title": "Adjuvant Olaparib for Patients with BRCA1 - or BRCA2 -Mutated Breast Cancer",
        "url": "https://www.nejm.org/doi/full/10.1056/NEJMoa2105215",
        "author": null,
        "date": "06/03/2021, 07:00 AM, +0000 UTC",
        "snippet": null,
        "source": "NEJM"
      }
    ]
  },
  "total_results": 2
}
```

**SDK Code**

```python Python REST
import requests

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"

headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.post(
    f"{BASE_URL}/v2/datasets/batch-search",
    headers=headers,
    json={"q": "BRCA1", "datasets": ["nejm"], "limit": 2},
    timeout=75.0
)
print(response.json())
```

```typescript TypeScript REST
const BASE_URL = "https://api.filesearch.dev";
const API_KEY = "your_api_key";

const response = await fetch(`${BASE_URL}/v2/datasets/batch-search`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({"q": "BRCA1", "datasets": ["nejm"], "limit": 2})
});
console.log(await response.json());
```