Blog / API guides

DuckDuckGo Search API: Web Results as JSON

20 Aug 2026Perceptlayer6 min read

DuckDuckGo's only official API is the Instant Answer API, which returns topic summaries such as abstracts and related topics, not a ranked list of web results. For organic results as JSON, GET /v1/duckduckgo/search?q=... returns each result's position, title, link and snippet, plus paging and, for some queries, an AI answer. It takes a region (kl), a date filter (df), safe search and an offset (start), and costs 1 credit per successful query.

Does DuckDuckGo have an official search API?

It has one official API, and it isn't a web search API. The Instant Answer API at api.duckduckgo.com returns the answer boxes DuckDuckGo shows above results: abstracts, definitions and related topics, mostly for well-known entities (DuckDuckGo Instant Answer API, 2026). It covers well-known topics, so a specific query, such as a product comparison, often comes back with empty fields. It's free and needs no key, so for a quick topic summary it's a fine fit.

For a ranked list of links, DuckDuckGo publishes nothing. That's the gap the DuckDuckGo API covers: one endpoint, the same key as the rest of the search engine APIs, JSON out. Data is collected from publicly available sources and returned as found at the time of the call.

Which parameters does the search endpoint take?

GET /v1/duckduckgo/search takes q, the query, and four optional parameters. Types and allowed values come from the endpoint definition. kl and df mirror the region and date settings DuckDuckGo documents for its own search URLs (DuckDuckGo URL parameters, 2026); defaults for this endpoint aren't documented, so set what you need.

A search for news-like queries from the past week in the UK would pass kl=uk-en&df=w. We haven't recorded that request; the playground on the Search endpoint page runs it.

How do you get DuckDuckGo results as JSON?

Send q and, ideally, kl so results come from the region you mean. The request below is the exact one behind the recorded response. Put your key in the X-API-Key header; keys start with sk_live_, and the authentication docs cover the rest.

curl "https://api.perceptlayer.com/v1/duckduckgo/search?q=laravel+taylor+otwell&kl=us-en&start=0" \
  -H "X-API-Key: $API_KEY"

What does the response look like?

The recorded response holds search_parameters, organic_results, pagination and, for this query, a knowledge_graph with an ai_answer. Here is an excerpt, trimmed with …; the first result, a personal profile page, is cut:

{
  "success": true,
  "data": {
    "search_parameters": {
      "q": "laravel taylor otwell",
      "kl": "us-en",
      "safe": true,
      "start": 0
    },
    "organic_results": [
      …,
      {
        "position": 2,
        "title": "taylorotwell (Taylor Otwell) · GitHub",
        "link": "https://github.com/taylorotwell",
        "snippet": "Creator of @laravel. taylorotwell has 10 repositories available. Follow their code on GitHub.",
        "display_url": "github.com/taylorotwell",
        "favicon": "https://icons.duckduckgo.com/ip3/github.com.ico"
      }
    ],
    "pagination": {
      "current": 1,
      "has_more": true,
      "next_start": 10,
      "next": 2
    },
    "knowledge_graph": {
      "ai_answer": {
        "answer": "**Taylor Otwell** is the creator of **Laravel**, a PHP web application framework he started in **2011** as a side project for himself. …"
      }
    }
  },
  "meta": {
    "duration_ms": 2169,
    "endpoint_family": "web_search"
  }
}

Two details matter when you parse it. Snippets can carry HTML entities as found: the first result's snippet in the recording contains &, so unescape before display. And ai_answer.answer is markdown with **bold**, so render or strip it rather than showing it raw. The response echoes safe: true even though the request didn't send safe, so check search_parameters to see what was applied.

How do you page through results?

Use the pagination object. In the recording, the first page reports current: 1, has_more: true and next_start: 10, so the second page is the same request with start=10. Stop when has_more is false. Each page is one call and 1 credit.

import os
import requests

URL = "https://api.perceptlayer.com/v1/duckduckgo/search"
HEADERS = {"X-API-Key": os.environ["API_KEY"]}

def search(q, pages=3, kl="us-en"):
    results, start = [], 0
    for _ in range(pages):
        r = requests.get(URL, headers=HEADERS, params={"q": q, "kl": kl, "start": start}, timeout=60)
        r.raise_for_status()
        data = r.json()["data"]
        results.extend(data.get("organic_results", []))
        page = data.get("pagination", {})
        if not page.get("has_more"):
            break
        start = page["next_start"]
    return results

for row in search("laravel taylor otwell", pages=2):
    print(row["position"], row["link"])

This code follows the recorded response shape; we haven't run it against the live API for this article. The recording doesn't show whether position restarts on page two, so sort by page and position together. For retries and loop safety, see paginating a web data API in Python.

How do DuckDuckGo results differ from Bing's?

Expect overlap, not identity. DuckDuckGo says it runs its own crawler and indexes, and that most of its traditional links and images come from Bing (DuckDuckGo Help Pages, 2026). It also says it doesn't use Google's results. Instant Answers draw on other sources such as Wikipedia.

So DuckDuckGo is a reasonable second opinion on Bing-like results, with its own ranking and answer boxes on top. If you're replacing Microsoft's retired Bing Search API, the Bing Search API alternative guide compares the Bing, Brave and DuckDuckGo endpoints side by side, so this article doesn't repeat it. For Google results instead, see the Google Search API guide.

What does a DuckDuckGo query cost?

Each successful query costs 1 credit; failed calls cost nothing and return X-Credits-Used: 0. Every success returns X-Credits-Used and X-Credits-Remaining, so you can watch the balance from the response headers. The credits docs explain how billing works.

The 1,000 free credits you get every month after verifying an email address cover 1,000 queries. Daily tracking of 100 keywords, 3,000 credits a month, needs a pack: a Starter pack of 10,000 credits covers three months and a bit, and purchased credits last 12 months. See pricing for what credits cost. Free accounts run at 1 request a second; the rate limits docs list paid rates.

Can an AI agent use DuckDuckGo search?

Yes. The MCP server at https://api.perceptlayer.com/mcp exposes search_endpoints and get_endpoint, which are free catalogue lookups, and call_endpoint, which runs /v1/duckduckgo/search with the agent's query and spends 1 credit on success. The result comes back as JSON, so the agent reads titles, links and snippets instead of a page of HTML.

Two habits keep an agent's searches useful. Pass kl so results match the user's region. And for time-sensitive questions, add df=d or df=w so stale pages drop out. Setup is in the AI agents docs; errors return an HTTP status and a JSON code, listed in the errors docs. For a pattern that checks agent answers against search results, see grounding LLM answers with live search.

To try a query, get a free API key and run it in the playground on the DuckDuckGo API page.

duckduckgosearch apiserpweb searchjson