--- title: "DuckDuckGo Search API: Web Results as JSON | Perceptlayer" description: "DuckDuckGo's Instant Answer API returns topic summaries, not ranked links. GET /v1/duckduckgo/search returns organic results and paging at 1 credit per query." url: https://perceptlayer.com/blog/duckduckgo-search-api-json --- [Blog](https://perceptlayer.com/blog) / [API guides](https://perceptlayer.com/blog/category/api-guides) # DuckDuckGo Search API: Web Results as JSON 20 Aug 2026 Perceptlayer 6 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. ## Key takeaways - DuckDuckGo's Instant Answer API at `api.duckduckgo.com` answers well-known topics with abstracts and related links; specific queries often come back empty, and it has no ranked results. - `GET /v1/duckduckgo/search` needs only `q` (up to 499 characters) and accepts `kl`, `df` ( `d`, `w`, `m`, `y`), `safe` and `start`. - The recorded response returns `organic_results[]` with `position`, `title`, `link`, `snippet` and `display_url`, and a `pagination` object whose `next_start` is 10. - Each query costs 1 credit on success; tracking 100 keywords daily on the first page is 100 × 30 = 3,000 credits a month. - DuckDuckGo says most of its traditional links come from Bing, so expect overlap with Bing results but not identical rankings. ## 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](https://api.duckduckgo.com/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](https://perceptlayer.com/apis/duckduckgo) covers: one endpoint, the same key as the rest of the [search engine APIs](https://perceptlayer.com/verticals/search), JSON out. Data is collected from publicly available sources and returned as found at the time of the call. | Need | Instant Answer API | `/v1/duckduckgo/search` | | --- | --- | --- | | Topic summary for a known entity | Yes | `knowledge_graph` on some queries | | Ranked organic results | No | `organic_results[]` | | Paging | No | `start` and `pagination` | | Region and date filters | No | `kl`, `df` | | Key and cost | No key, free | API key, 1 credit per query | ## 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](https://duckduckgo.com/duckduckgo-help-pages/settings/params), 2026); defaults for this endpoint aren't documented, so set what you need. | Parameter | Type | Allowed values or notes | | --- | --- | --- | | `q` | string, required | Up to 499 characters | | `kl` | string | Region and language, up to 10 characters, for example `us-en` | | `df` | string | Date filter: `d` (day), `w` (week), `m` (month), `y` (year) | | `safe` | boolean | Safe search on or off | | `start` | integer | Result offset; the recorded first page uses `0` | 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](https://perceptlayer.com/apis/duckduckgo/search) 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](https://docs.perceptlayer.com/authentication) cover the rest. ```bash 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: ```json { "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. ```python 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](https://perceptlayer.com/blog/paginate-web-data-api-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](https://duckduckgo.com/duckduckgo-help-pages/results/sources), 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](https://perceptlayer.com/blog/bing-search-api-alternative-json) 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](https://perceptlayer.com/blog/google-search-api-json). ## 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](https://docs.perceptlayer.com/credits) explain how billing works. | Job | Calls | Credits | | --- | --- | --- | | One query, first page | 1 | 1 | | One query, three pages | 3 | 3 | | 100 keywords daily, first page, 30 days | 3,000 | 3,000 | | An agent answering 500 questions, 2 searches each | 1,000 | 1,000 | 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](https://perceptlayer.com/pricing) for what credits cost. Free accounts run at 1 request a second; the [rate limits docs](https://docs.perceptlayer.com/rate-limits) 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](https://docs.perceptlayer.com/ai-agents); errors return an HTTP status and a JSON `code`, listed in the [errors docs](https://docs.perceptlayer.com/errors). For a pattern that checks agent answers against search results, see [grounding LLM answers with live search](https://perceptlayer.com/blog/ground-agent-answers-live-search). To try a query, [get a free API key](https://perceptlayer.com/signup) and run it in the playground on the [DuckDuckGo API page](https://perceptlayer.com/apis/duckduckgo). ## APIs in this post - [DuckDuckGo **1 credit per call** · 1 endpoint](https://perceptlayer.com/apis/duckduckgo) ## Frequently asked questions ### Is the DuckDuckGo Instant Answer API a search API? No. It returns Instant Answers, such as an abstract, a definition or related topics, mostly for well-known entities; specific queries often come back with empty fields. It has no ranked web results or paging. For organic results as JSON, `GET /v1/duckduckgo/search` returns positions, titles, links and snippets at 1 credit per query. ### How much does the DuckDuckGo search endpoint cost? 1 credit per successful query, and failed calls cost nothing. Each further page is another call. Every account gets 1,000 free credits a month after verifying an email address, so 1,000 first-page queries a month cost no money. Prepaid packs start at 10,000 credits; the [pricing page](https://perceptlayer.com/pricing) has what they cost. ### How do I get the second page of results? Read `pagination.next_start` from the response and send it as `start`. In the recorded first page, `next_start` is 10, so page two is the same request with `start=10`. Keep going while `has_more` is true. Each page costs 1 credit. ### Can I filter DuckDuckGo results by date or region? Yes. `df` takes `d`, `w`, `m` or `y` for the past day, week, month or year, and `kl` takes a region and language code such as `us-en`. `safe` turns safe search on or off. Check `search_parameters` in the response to confirm what was applied. ### What happens if a query fails? You get an HTTP status and a JSON error with a `code`, `message` and `request_id`, and nothing is debited. A missing `q` returns `invalid_parameters` (422). Rate-limited (429) and temporarily unavailable (503) responses include `Retry-After` with the seconds to wait. The [errors docs](https://docs.perceptlayer.com/errors) list every code. duckduckgo search api serp web search json ## More from the blog 1. [API guides](https://perceptlayer.com/blog/category/api-guides) 5 Aug 2026 Perceptlayer 8 min read ## [Bing Search API Alternative: Web Results as JSON](https://perceptlayer.com/blog/bing-search-api-alternative-json) Replace Microsoft's retired Bing Search API with three search endpoints at 1 credit per call. Parameters compared, real responses, and where results differ. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 17 Aug 2026 Perceptlayer 7 min read ## [Brave Search API: Official Plans or One Multi-Source Key](https://perceptlayer.com/blog/brave-search-api-results-json) Brave's official Search API has freshness, country and Goggles filters. When it fits, and when one key for Brave, Google and Bing at 1 credit a query wins. 3. [API guides](https://perceptlayer.com/blog/category/api-guides) 10 Aug 2026 Perceptlayer 7 min read ## [Google Search API: Get Search Results as JSON](https://perceptlayer.com/blog/google-search-api-json) Call GET /v1/google-search/search for organic results as JSON at 1 credit a call. Parameters, a real recorded response and the cost in credits.