# DuckDuckGo API

> DuckDuckGo returns web search results and instant answers as a workflow and API.

DuckDuckGo, also called DDG, uses Search web to return ordered public web results and an instant answer when available. Search web needs search words and can also take a country or maximum result count.

- Page: https://fous.com/tools/duckduckgo
- Handle: `@duckduckgo`
- Category: [Search](https://fous.com/tools/category/search)
- Source website: https://duckduckgo.com
- Last verified: Sep 29, 2026

## Methods

### Search web

Operation `search_web`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Search the web privately with DuckDuckGo and return ordered public results without ads, plus an instant answer when available. Regions are limited to DuckDuckGo’s available country choices; a human-verification challenge may prevent a search.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `query` | string | yes | `"how to file a trademark"` | Search words, for example how to file a trademark. |
| `region` | string | no | `"United Kingdom"` | Country name or two-letter country code, for example United States or DE. |
| `max_results` | integer | no | `24` | Maximum number of organic results to return, for example 20. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "Search words, for example how to file a trademark.",
      "examples": [
        "how to file a trademark",
        "python programming language",
        "apple strudel recipe"
      ]
    },
    "region": {
      "type": "string",
      "default": "United States",
      "description": "Country name or two-letter country code, for example United States or DE.",
      "examples": [
        "United Kingdom",
        "DE"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 10,
      "maximum": 50,
      "minimum": 1,
      "description": "Maximum number of organic results to return, for example 20.",
      "x-fous-developer": true,
      "examples": [
        24,
        12,
        10
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "query": "how to file a trademark"
    },
    {
      "query": "python programming language",
      "region": "United Kingdom",
      "max_results": 24
    },
    {
      "query": "apple strudel recipe",
      "region": "DE",
      "max_results": 12
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `results` | array |  | Organic search results in displayed order. |
| `results[].link` | string | `"https://www.uspto.gov/trademarks/apply"` |  |
| `results[].snippet` | string | `"Apply for a trademark through Trademark Center. Pay application-related fees and use the docketing feature to track the` |  |
| `results[].position` | integer | `1` |  |
| `results[].page_title` | string | `"Apply online \| USPTO"` |  |
| `results[].website_name` | string | `"uspto.gov"` |  |
| `instant_answer` | string or null | `"Python is a high-level, general-purpose programming language that emphasizes code readability, simplicity, and ease-of-` | DuckDuckGo instant-answer text when available. |

**Example input**

```json
{
  "query": "how to file a trademark"
}
```

**Example output**

```json
{
  "results": [
    {
      "link": "https://www.uspto.gov/trademarks/apply",
      "snippet": "Apply for a trademark through Trademark Center. Pay application-related fees and use the docketing feature to track the status of applications filed through Trademark Center.",
      "position": 1,
      "page_title": "Apply online | USPTO",
      "website_name": "uspto.gov"
    },
    {
      "link": "https://www.uspto.gov/trademarks",
      "snippet": "Find out how to register and maintain a trademark in the U.S., apply for an international trademark , and about protecting your registered trademark .",
      "position": 2,
      "page_title": "Trademarks | USPTO",
      "website_name": "uspto.gov"
    },
    {
      "link": "https://trademarkcenter.uspto.gov/",
      "snippet": "Announcements On September 3, we retired the TEAS \"Order Trademark Presentation Copy of Registration Certificate\" form. Select \"Renew or maintain a registration\" under \"Manage trademarks \" above to or…",
      "position": 3,
      "page_title": "Trademark Center",
      "website_name": "trademarkcenter.uspto.gov"
    }
  ],
  "instant_answer": null
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@duckduckgo",
  "visibility": "public",
  "operation": "search_web",
  "version": 1,
  "input": {
    "query": "how to file a trademark"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@duckduckgo\",\n  \"visibility\": \"public\",\n  \"operation\": \"search_web\",\n  \"version\": 1,\n  \"input\": {\n    \"query\": \"how to file a trademark\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@duckduckgo",
  "visibility": "public",
  "operation": "search_web",
  "version": 1,
  "input": {
    "query": "how to file a trademark"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/duckduckgo`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `search_web`: Search web. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-duckduckgo https://api.fous.com/mcp/tools/duckduckgo --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Find public webpages for a research topic
- Review ordered results and their snippets
- Retrieve an instant answer when available

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this DuckDuckGo tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a DuckDuckGo account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from duckduckgo.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What pages appear for a search query?

Search web returns organic web results in displayed order, with titles, links, snippets, and positions.

### Can I choose a country for search results?

Yes. Search web accepts a country name or two-letter country code as the region.

### Does DuckDuckGo return instant answers?

Search web returns instant-answer text when available.

## Related

- [Google Search API](https://fous.com/tools/google-search.md): Google Search returns public web, image, job, event, related-question, and autocomplete results in Google’s order, with answers and details when available; results may be fewer, omit information, or be empty.
- [Bing API](https://fous.com/tools/bing.md): Bing returns ordered web results and recent news, plus AI answers with sources when available; news times are approximate, and images may be missing.
- [DoorDash API](https://fous.com/tools/doordash.md): DoorDash lists nearby restaurants and menus, prices, ratings, delivery fees, and estimated times; offers, availability, fees, and times can change.
- [The Guardian API](https://fous.com/tools/the-guardian.md): The Guardian provides news, sport, culture and opinion, ordered headlines, keyword-search results that may omit older or less prominent stories, and article details with available text; live blogs show the latest entries.
- [Goodreads API](https://fous.com/tools/goodreads.md): Goodreads returns public book searches, matched-book details with variable editions, popular or newest reviews, author books by popularity or date, and up to 100 quotes.
- [Apple App Store API](https://fous.com/tools/apple-app-store.md): Apple App Store returns public app listings, keyword search, ratings, prices, listed purchases, country-specific reviews and visible replies, and up to 200 ranked chart apps.
- [Wikipedia API](https://fous.com/tools/wikipedia.md): Wikipedia returns article summaries, images, facts, relevant search matches, readable text and daily historical events, plus human-view counts from July 2015 onward.
- [Spotify API](https://fous.com/tools/spotify.md): Spotify returns public artist profiles, album credits and ordered tracks, song details and play counts, up to 500 playlist songs, keyword results, and country-based podcast charts; dates and regional options vary.
- [All Search tools](https://fous.com/tools/category/search)