> For the complete documentation index, see [llms.txt](https://docs.pullbay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pullbay.com/api-reference/endpoints/duckduckgo.md).

# DuckDuckGo

DuckDuckGo: web search, images, news, videos. All endpoints are read-only `GET` requests and return public DuckDuckGo search results.

**Base URL:** `https://api.pullbay.com/`

## Endpoints

| Endpoint                 | Description                         | Pagination |
| ------------------------ | ----------------------------------- | ---------- |
| `GET /duckduckgo/search` | Search the web via DuckDuckGo       | Offset     |
| `GET /duckduckgo/images` | Search images via DuckDuckGo        | Offset     |
| `GET /duckduckgo/news`   | Search news articles via DuckDuckGo | Offset     |
| `GET /duckduckgo/videos` | Search videos via DuckDuckGo        | Offset     |

***

### Search Web

Returns web search results for `term`.

**Request**

```bash
GET /duckduckgo/search
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter    | Type   | Required | Description                                                               |
| ------------ | ------ | -------- | ------------------------------------------------------------------------- |
| `term`       | string | Yes      | Search term, 1–255 characters                                             |
| `region`     | string | Yes      | DuckDuckGo region code (e.g. `wt-wt`, `us-en`, `uk-en`)                   |
| `safeSearch` | string | Yes      | `false` (off), `moderate`, or `strict`                                    |
| `offset`     | number | No       | Result offset, 0 or greater                                               |
| `time`       | string | No       | Recency filter: `a` (any), `d` (day), `w` (week), `m` (month), `y` (year) |

**Example**

```bash
curl -G "https://api.pullbay.com/duckduckgo/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d term="OpenAI" \
  -d region=us-en \
  -d safeSearch=moderate \
  -d offset=0
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "OpenAI",
      "description": "We believe our research will eventually lead to artificial general intelligence, a system that can solve human-level problems.",
      "hostname": "openai.com",
      "icon": "https://external-content.duckduckgo.com/ip3/openai.com.ico",
      "url": "https://openai.com/"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of results returned, not the number of requests.

***

### Search Images

Returns image search results for `term`.

**Request**

```bash
GET /duckduckgo/images
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter    | Type   | Required | Description                                             |
| ------------ | ------ | -------- | ------------------------------------------------------- |
| `term`       | string | Yes      | Search term, 1–255 characters                           |
| `region`     | string | Yes      | DuckDuckGo region code (e.g. `wt-wt`, `us-en`, `uk-en`) |
| `safeSearch` | string | Yes      | `false` (off), `moderate`, or `strict`                  |
| `offset`     | number | No       | Result offset, 0 or greater                             |

**Example**

```bash
curl -G "https://api.pullbay.com/duckduckgo/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d term="wallpaper cat" \
  -d region=us-en \
  -d safeSearch=moderate \
  -d offset=0
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "Wallpaper Cat Photos, Download The BEST Free Wallpaper Cat Stock Photos",
      "image": "https://images.pexels.com/photos/20331914/pexels-photo-20331914.jpeg",
      "thumbnail": "https://tse1.mm.bing.net/th/id/OIP.oOmFm8pcnPy1pVPS46kxfQHaE8?r=0&pid=Api",
      "image_token": "a8b8c30ef6de5362d93dd6f5848ec661ae916727695b7e944138db4a60c5f6ca",
      "thumbnail_token": "036492c962e7830bd485903527a6caf439793418572197fbf6a743a8255f594b",
      "width": 6000,
      "height": 4000,
      "source": "Bing",
      "url": "https://www.pexels.com/search/Wallpaper%20cat/"
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of results returned, not the number of requests.

***

### Search News

Returns news articles for `term`. Use `time` to limit recency (`a`=any, `d`=day, `w`=week, `m`=month, `y`=year).

**Request**

```bash
GET /duckduckgo/news
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter    | Type   | Required | Description                                                               |
| ------------ | ------ | -------- | ------------------------------------------------------------------------- |
| `term`       | string | Yes      | Search term, 1–255 characters                                             |
| `region`     | string | Yes      | DuckDuckGo region code (e.g. `wt-wt`, `us-en`, `uk-en`)                   |
| `safeSearch` | string | Yes      | `false` (off), `moderate`, or `strict`                                    |
| `offset`     | number | No       | Result offset, 0 or greater                                               |
| `time`       | string | No       | Recency filter: `a` (any), `d` (day), `w` (week), `m` (month), `y` (year) |

**Example**

```bash
curl -G "https://api.pullbay.com/duckduckgo/news" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d term="Marvell Technology" \
  -d region=us-en \
  -d safeSearch=moderate \
  -d time=w
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "Why Marvell Technology Stock Just Dropped",
      "excerpt": "Why Marvell's mad at Poet. Seems somebody let the cat out of the bag too soon...",
      "url": "https://www.fool.com/investing/2026/04/27/why-marvell-technology-stock-just-dropped/",
      "image": "https://g.foolcdn.com/image/?url=https%3A%2F%2Fg.foolcdn.com%2Feditorial%2Fimages%2F867388%2F5-red-stock-market-arrows-pointing-down.jpg",
      "date": 1777303200,
      "relativeTime": "21 hours ago",
      "syndicate": "bing",
      "isOld": false
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of articles returned, not the number of requests.

***

### Search Videos

Returns video search results for `term`.

**Request**

```bash
GET /duckduckgo/videos
Authorization: Bearer YOUR_API_KEY
```

**Parameters**

| Parameter    | Type   | Required | Description                                             |
| ------------ | ------ | -------- | ------------------------------------------------------- |
| `term`       | string | Yes      | Search term, 1–255 characters                           |
| `region`     | string | Yes      | DuckDuckGo region code (e.g. `wt-wt`, `us-en`, `uk-en`) |
| `safeSearch` | string | Yes      | `false` (off), `moderate`, or `strict`                  |
| `offset`     | number | No       | Result offset, 0 or greater                             |

**Example**

```bash
curl -G "https://api.pullbay.com/duckduckgo/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d term="cooking skills" \
  -d region=us-en \
  -d safeSearch=moderate \
  -d offset=0
```

**Response**

```json
{
  "status": 200,
  "message": "OK",
  "success": true,
  "data": [
    {
      "title": "Gordon Ramsay's Top Basic Cooking Skills | Ultimate Cookery Course FULL EPISODE",
      "description": "Gordon Ramsay demonstrates some basic cooking skills as well as some easy to do recipes.",
      "url": "https://www.youtube.com/watch?v=FTociictyyE",
      "image": "https://tse4.mm.bing.net/th/id/OVP.dTE0hC-DCsYuM6UsczwKpgHgFo?pid=Api",
      "duration": "23:03",
      "publishedOn": "YouTube",
      "published": "2019-11-07T17:00:05.0000000",
      "publisher": "Gordon Ramsay",
      "viewCount": 9252292
    }
  ],
  "pricing": { "creditsCharged": 1 }
}
```

**Credit cost:** dynamic, returned in `pricing.creditsCharged`. Cost scales with the number of videos returned, not the number of requests.

***

## Object Schemas

### Search Result object

| Field         | Type   | Description                        |
| ------------- | ------ | ---------------------------------- |
| `title`       | string | Page title                         |
| `description` | string | Snippet/summary text from the page |
| `hostname`    | string | Domain the result was served from  |
| `icon`        | string | Favicon URL                        |
| `url`         | string | Link to the page                   |

### Image object

| Field              | Type    | Description                                    |
| ------------------ | ------- | ---------------------------------------------- |
| `title`            | string  | Image title                                    |
| `image`            | string  | Full-size image URL                            |
| `thumbnail`        | string  | Thumbnail image URL                            |
| `image_token`      | string  | Opaque token identifying the full-size image   |
| `thumbnail_token`  | string  | Opaque token identifying the thumbnail         |
| `width` / `height` | integer | Image dimensions in pixels                     |
| `source`           | string  | Originating image search backend (e.g. `Bing`) |
| `url`              | string  | Link to the page hosting the image             |

### News Article object

| Field          | Type    | Description                                                |
| -------------- | ------- | ---------------------------------------------------------- |
| `title`        | string  | Article headline                                           |
| `excerpt`      | string  | Short snippet of the article body                          |
| `url`          | string  | Link to the full article                                   |
| `image`        | string  | Associated image URL                                       |
| `date`         | integer | Publish timestamp, Unix seconds                            |
| `relativeTime` | string  | Human-readable relative publish time (e.g. `21 hours ago`) |
| `syndicate`    | string  | Syndication source (e.g. `bing`)                           |
| `isOld`        | boolean | Whether the article is flagged as stale/older content      |

### Video object

| Field         | Type               | Description                                       |
| ------------- | ------------------ | ------------------------------------------------- |
| `title`       | string             | Video title                                       |
| `description` | string             | Video description                                 |
| `url`         | string             | Link to the video                                 |
| `image`       | string             | Thumbnail/preview image URL                       |
| `duration`    | string             | Video duration, formatted `mm:ss` (or `hh:mm:ss`) |
| `publishedOn` | string             | Hosting platform (e.g. `YouTube`)                 |
| `published`   | string (date-time) | Publish timestamp                                 |
| `publisher`   | string             | Channel or publisher name                         |
| `viewCount`   | integer            | View count                                        |

***

## Errors

All non-2xx responses share the same envelope:

```json
{
  "status": 400,
  "message": "Bad request",
  "success": false,
  "error": { "code": "BAD_REQUEST" }
}
```

| Status | Meaning                                  |
| ------ | ---------------------------------------- |
| `400`  | Bad request — missing/invalid parameters |
| `402`  | Insufficient credits                     |
| `404`  | No results found                         |

## Region Codes

* `region` accepts a DuckDuckGo-specific region code, not a plain ISO country code — most are `<country>-<language>` pairs (e.g. `us-en`, `uk-en`, `de-de`, `jp-jp`), with a few exceptions (`wt-wt` for worldwide/no region, `ct-ca`, `xa-ar`).
* Use `wt-wt` when you don't want to bias results to a specific region.

## Safe Search Levels

* `safeSearch` takes one of three values: `false` (safe search off), `moderate` (default-style filtering), or `strict` (maximum filtering). Note that the "off" value is the literal `false`, not a string.

## Pagination and Recency

* All four endpoints page via `offset` — there is no `page`, `cursor`, or `maxItems` parameter on this service. Increase `offset` by the number of results already consumed to fetch the next batch.
* `time` (on `search` and `news` only) restricts results to a recency window (`a`/`d`/`w`/`m`/`y`) rather than paging through results — it is not available on `images` or `videos`.