Search API

Endpoint

POST https://api.serpex.dev/api/search
GET  https://api.serpex.dev/api/search

Both GET (query params) and POST (JSON body) are supported. POST is recommended for production.

Authentication

Pass your API key as a Bearer token in the Authorization header.

Authorization: Bearer sk_...

The x-api-key header is also accepted as a fallback.

Request Parameters

Code Examples

curl -X POST https://api.serpex.dev/api/search \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"q": "best JavaScript frameworks 2025"}'

import { SerpexClient } from "serpex";

const client = new SerpexClient("sk_your_api_key");

const results = await client.search({
  q: "best JavaScript frameworks 2025",
});

console.log(results.results[0].title);
console.log(results.metadata.credits_used);

from serpex import SerpexClient

client = SerpexClient("sk_your_api_key")

results = client.search({
    "q": "best JavaScript frameworks 2025",
})

print(results.results[0].title)
print(results.metadata.credits_used)

Response

{
  "id": "srp_01j9abc...",
  "query": "best JavaScript frameworks 2025",
  "engines": ["duckduckgo"],
  "results": [
    {
      "title": "Top JavaScript Frameworks in 2025",
      "url": "https://example.com/js-frameworks",
      "snippet": "React, Vue, and Svelte remain the top choices for JavaScript developers...",
      "position": 1,
      "engine": "duckduckgo",
      "content": "# Top JavaScript Frameworks in 2025\n\nReact, Vue, and Svelte remain the top choices for JavaScript developers heading into 2025..."
    },
    {
      "title": "2025 Frontend Framework Comparison",
      "url": "https://example.com/frontend-comparison",
      "snippet": "A deep dive into performance and DX across the major frameworks...",
      "position": 2,
      "engine": "duckduckgo",
      "content_error": "blocked"
    }
  ],
  "metadata": {
    "number_of_results": 10,
    "credits_used": 2,
    "from_cache": false,
    "status": "success",
    "response_time": 1240,
    "timestamp": "2025-06-21T10:30:00.000Z",
    "content_requested": 5,
    "content_delivered": 4
  }
}

The example above was requested with include_content: true and content_results: 5. The first result's page fetch succeeded (content holds the markdown); the second failed (content_error explains why) — a result only ever carries one of the two keys, never both, and both keys are omitted entirely on a plain search.

Response Fields

Credits

• 1 credit per fresh successful search.
• 0 credits when results are served from cache (from_cache: true).
• 0 credits when the query returns no results.
• Errors are never charged.
• With include_content: true: 2 credits for content_results: 5, 4 credits for content_results: 10 — instead of the usual 1. Page-content fetching is best-effort: in practice content is delivered for roughly 79% of requested results. Never expect 100% — some pages are blocked or disallowed by robots.txt and come back with content_error instead of content (results that fail content fetch still return their normal title/url/snippet; only the content fetch itself is best-effort, and a failed fetch is never billed on its own).
  • Charged by how much content was actually delivered, not just requested: 1-5 delivered → 2 credits, 6-10 delivered → 4 credits.
  • If content delivery fails for every requested result, you're only charged the plain-search rate of 1 credit — you're never charged the content rate for content you didn't get.