# 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/workflows/duckduckgo
- Handle: `@duckduckgo`
- Category: [Search](https://fous.com/workflows/category/search)
- Source website: https://duckduckgo.com
- Last verified: Sep 29, 2026
- Fous is not affiliated with DuckDuckGo.

## Methods

### Search web

Operation `search_web`, version 1. 1 credit per call.

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

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_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.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

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=120) 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.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_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);
```

Or describe the data in plain language: send `{"api":"@duckduckgo","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

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

## FAQ

### Is Fous affiliated with DuckDuckGo?

No. Fous is not affiliated with DuckDuckGo. This workflow reads the public duckduckgo.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. 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; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check 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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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/workflows/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 workflows](https://fous.com/workflows/category/search)