> 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://dashboard.pullbay.com/api`

## 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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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://dashboard.pullbay.com/api/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`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pullbay.com/api-reference/endpoints/duckduckgo.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.