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

# Search Dataset

GET https://api.captain.dev/v2/datasets/{dataset}/search

Search for articles within a news dataset.

Performs search constrained to the dataset's domain.

**Supported Datasets:**

* `nytimes`: New York Times (nytimes.com)
* `washpost`: Washington Post (washingtonpost.com)
* `sfstandard`: SF Standard (sfstandard.com)
* `sacbee`: Sacramento Bee (sacbee.com)
* `sfchronicle`: San Francisco Chronicle (sfchronicle.com)
* `newyorker`: The New Yorker (newyorker.com)
* `theatlantic`: The Atlantic (theatlantic.com)
* `sjmercury`: San Jose Mercury News (mercurynews.com)
* `latimes`: Los Angeles Times (latimes.com)
* `wired`: WIRED (wired.com)
* `scientificamerican`: Scientific American (scientificamerican.com)

**Headers:**

* `Authorization`: Bearer \{api\_key} - Captain API key for authentication
* `X-Organization-ID`: Organization UUID

**Query Parameters:**

* `q`: Search query (required)
* `limit`: Maximum results to return (default: 10, max: 100)

**Returns:**
List of search results with title, URL, snippet, and date.

**Example:**

```
GET /v2/datasets/nytimes/search?q=artificial+intelligence&limit=5
```

Reference: https://docs.captain.dev/reference/datasets/articles/search-dataset

## Request

### Path parameters

- `dataset` (string, required) — The news dataset to search

### Query parameters

- `q` (string, required) — Search query
- `limit` (integer, optional, default: 10) — Maximum number of results to return
- `author` (string, optional, nullable) — Filter by author/byline name (appended as quoted phrase to search)

## Response

### 200

Successful Response

- `dataset` (string, required)
- `query` (string, required)
- `error` (string, optional, nullable) — Error message if search failed
- `limit` (integer, optional, default: 10)
- `results` (list of DatasetSearchResult, optional)
- `total_results` (integer, optional, default: 0)

## Errors

### 400 Bad Request Error

Invalid dataset or 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)

### 502 Bad Gateway Error

Search service 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)

### 504 Gateway Timeout Error

Search request timed out

- `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

### Search Dataset

**Response**

```json
{
  "dataset": "nytimes",
  "query": "artificial intelligence",
  "limit": 5,
  "results": [
    {
      "title": "Meta Lays Off 700 Employees, While Rewarding Top Executives",
      "url": "https://www.nytimes.com/2026/03/25/technology/meta-layoffs-ai-executives.html",
      "author": "Eli Tan",
      "date": "03/25/2026, 07:22 PM, +0000 UTC",
      "snippet": null,
      "source": "New York Times"
    },
    {
      "title": "People Loved the Dot-Com Boom. The A.I. Boom, Not So Much.",
      "url": "https://www.nytimes.com/2026/03/15/technology/ai-boom-dot-com.html",
      "author": "David Streitfeld",
      "date": "03/15/2026, 08:00 AM, +0000 UTC",
      "snippet": null,
      "source": "New York Times"
    }
  ],
  "total_results": 100
}
```

**SDK Code**

```python Search Dataset
import requests
import json

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

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

# Search a single dataset
response = requests.get(
    f"{BASE_URL}/v2/datasets/nytimes/search",
    headers=headers,
    params={"q": "artificial intelligence", "limit": 5},
    timeout=75.0
)

print(json.dumps(response.json(), indent=2))
```

```typescript Search Dataset
const BASE_URL = "https://api.captain.dev";
const API_KEY = "your_api_key";

const params = new URLSearchParams({ q: "artificial intelligence", limit: "5" });
const response = await fetch(
    `${BASE_URL}/v2/datasets/nytimes/search?${params}`,
    { headers: { "Authorization": `Bearer ${API_KEY}` } }
);

const data = await response.json();
console.log(JSON.stringify(data, null, 2));
```

### Search by Author

**Response**

```json
{
  "dataset": "nytimes",
  "query": "climate change",
  "limit": 10,
  "results": [
    {
      "title": "Trump Is Gutting Weather Science and Reducing Disaster Response",
      "url": "https://www.nytimes.com/2025/07/13/climate/floods-trump-cuts-disaster-preparedness-fema.html",
      "author": "Lisa Friedman, Megan Mineiro, C. Davenport",
      "date": "07/13/2025, 07:00 AM, +0000 UTC",
      "snippet": null,
      "source": "New York Times"
    },
    {
      "title": "Climate Change Can Cause Bridges to 'Fall Apart Like Tinkertoys,' Experts Say",
      "url": "https://www.nytimes.com/2024/09/02/climate/climate-change-bridges.html",
      "author": "C. Davenport",
      "date": "09/12/2024, 07:00 AM, +0000 UTC",
      "snippet": null,
      "source": "New York Times"
    }
  ],
  "total_results": 10
}
```

**SDK Code**

```python Search by Author
import requests
import json

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

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

# Filter by author/byline within a dataset
response = requests.get(
    f"{BASE_URL}/v2/datasets/nytimes/search",
    headers=headers,
    params={"q": "climate change", "author": "Coral Davenport", "limit": 10},
    timeout=75.0
)

print(json.dumps(response.json(), indent=2))
```

```typescript Search by Author
const BASE_URL = "https://api.captain.dev";
const API_KEY = "your_api_key";

const params = new URLSearchParams({ q: "climate change", author: "Coral Davenport", limit: "10" });
const response = await fetch(
    `${BASE_URL}/v2/datasets/nytimes/search?${params}`,
    { headers: { "Authorization": `Bearer ${API_KEY}` } }
);

const data = await response.json();
console.log(JSON.stringify(data, null, 2));
```