Serper.live API-Dokumentation

Schnellstart

Drei Schritte vom leeren Konto zum ersten Live-Ergebnis.

1. Erstellen Sie ein Konto und ein Token unter API-Tokens. Das vollständige Token wird einmal gezeigt, speichern Sie es also in Ihrem Secret-Manager.
2. Laden Sie unter Guthaben Guthaben in USDT oder USDC auf. Eine Live-Suche kostet $0.01.
3. Senden Sie die Anfrage unten mit Ihrem Token. Die Antwort sind die aktuellen Google-Ergebnisse für diesen Markt.

curl -X POST https://api.serper.live/v1/search \
  -H "Authorization: Bearer sl_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"best coffee shops","country":"DE"}'

const response = await fetch('https://api.serper.live/v1/search', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer sl_live_YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query: 'best coffee shops', country: 'DE' }),
    signal: AbortSignal.timeout(100000),
});
const result = await response.json();

console.log(result.organic);

import requests

response = requests.post(
    "https://api.serper.live/v1/search",
    headers={"Authorization": "Bearer sl_live_YOUR_TOKEN"},
    json={"query": "best coffee shops", "country": "DE"},
    timeout=100,
)
print(response.json()["organic"])

Eine Live-Suche antwortet meist in 2–3 Sekunden; die erste Anfrage an einen Markt nach einer Pause dauert länger, weil dort eine frische Google-Sitzung geöffnet wird. Behalten Sie ein Client-Timeout von mindestens 100 Sekunden, damit eine langsame erste Anfrage bei Ihnen nie fehlschlägt.

Authentifizierung

Jede Anfrage an /v1/search trägt Ihr Token im Authorization-Header:

Authorization: Bearer sl_live_YOUR_TOKEN

• Tokens beginnen mit sl_live_ und werden unter API-Tokens erstellt. Legen Sie pro Anwendung ein eigenes Token an, damit Sie es widerrufen können, ohne die anderen anzufassen.
• Behalten Sie Tokens auf Ihrem Server. Liefern Sie sie nie in einem Browser, einer mobilen App oder einem öffentlichen Repository aus.
• Ein widerrufenes Token funktioniert sofort nicht mehr; der Verlauf seiner Anfragen bleibt in Ihrem Konto.

Suche

POST https://api.serper.live/v1/search

Führt eine Live-Google-Suche aus und liefert die organischen Ergebnisse. Anfrage und Antwort sind JSON; der Anfragekörper ist auf 16 KB begrenzt.

Anfragekörper

Antwort

{
    "requestId": "0199860b-2f4e-7a1c-9b3d-5e6f70819a2b",
    "query": "best coffee shops",
    "country": "DE",
    "language": "en",
    "device": "desktop",
    "fetchedAt": "2026-09-28T14:00:00.000Z",
    "latencyMs": 1873,
    "price": 0.01,
    "currency": "USD",
    "organic": [
        {
            "position": 1,
            "title": "The 12 best coffee shops in town",
            "url": "https://example.com/guides/best-coffee-shops",
            "domain": "example.com",
            "snippet": "A curated list of specialty coffee shops, updated every month."
        },
        {
            "position": 2,
            "title": "Coffee shops near me",
            "url": "https://maps.example.org/coffee",
            "domain": "maps.example.org",
            "snippet": null
        }
    ]
}

Organische Ergebnisse: die Felder von organic[]

Jedes Element von organic[] ist ein organisches Ergebnis in der Reihenfolge, in der Google es zeigt. Googles eigene Navigationseinträge und Duplikate bleiben außen vor, und die Ergebnisse werden über mehrere Ergebnisseiten gesammelt, bis limit erreicht ist.

Die Felder sind für Desktop und Mobil und für jeden Markt dieselben:

Länder

GET https://api.serper.live/v1/countries

Öffentlich, ohne Token. Liefert die derzeit offenen Märkte und die Google-Standardsprache jedes Marktes; jeder Markt unterstützt desktop und mobile.

curl https://api.serper.live/v1/countries

{
    "countries": [
        {
            "code": "DE",
            "defaultLanguage": "de"
        },
        {
            "code": "FR",
            "defaultLanguage": "fr"
        },
        {
            "code": "GB",
            "defaultLanguage": "en"
        },
        {
            "code": "TR",
            "defaultLanguage": "tr"
        },
        {
            "code": "UA",
            "defaultLanguage": "uk"
        },
        {
            "code": "US",
            "defaultLanguage": "en"
        }
    ]
}

Derzeit offene Märkte mit der Google-Oberflächensprache, die ohne language verwendet wird:

Derzeit offen: Deutschland, Frankreich, Vereinigtes Königreich, Türkei, Ukraine und Vereinigte Staaten. Neue Märkte erscheinen hier und auf der Preisseite, sobald sie starten. Eine Anfrage für einen geschlossenen Markt liefert 422 country_unavailable zusammen mit der Liste der verfügbaren Codes.

Abrechnung

Ihr Konto führt ein Prepaid-Guthaben in USD. Vor dem Start der Suche reserviert jede Anfrage den aktuellen Preis ihres Marktes für jeden angefangenen Block von 10 Ergebnissen: limit 10 oder weniger reserviert einen Preis, limit 25 reserviert drei.

• Erfolgreiche Suche: der Preis wird für jeden Block von 10 berechnet, der Ergebnisse erhalten hat, mindestens einen, und der Rest der Reservierung kehrt sofort auf Ihr Guthaben zurück. limit 50 mit 12 Ergebnissen kostet zwei Preise, nicht fünf.
• Fehlgeschlagene Suche, also eine 408-, 424- oder 5xx-Antwort: die Reservierung wird automatisch freigegeben. Sie zahlen nie für ein Ergebnis, das Sie nicht erhalten haben.
• Preise können sich mit der Zeit ändern, der für eine laufende Anfrage reservierte Preis aber nie.
• Zu wenig Guthaben: 402 insufficient_balance. Laden Sie unter Guthaben auf; das Guthaben ist wenige Minuten nach Bestätigung der Einzahlung verfügbar.

Jede Anfrage, ihr Status und ihre Kosten stehen im Anfrageverlauf; jede Guthabenänderung steht im Buchungsverlauf auf der Guthabenseite.

Fehler

Fehler sind JSON mit einem maschinenlesbaren error-Code, einer lesbaren message und, sobald eine Anfrage angelegt wurde, ihrer requestId:

{
    "error": "insufficient_balance",
    "message": "The balance does not cover one request",
    "requestId": "0199860b-2f4e-7a1c-9b3d-5e6f70819a2b"
}

Sichere Wiederholungen

Optional. Sie brauchen das nur, wenn Ihr Client eine abgebrochene Anfrage wiederholen kann.

Eine Live-Suche läuft bis zu 90 Sekunden. Bricht Ihre Verbindung in dieser Zeit ab, wissen Sie nicht, ob die Suche abgeschlossen und berechnet wurde. Mit einem Idempotency-Key-Header wiederholen Sie, ohne zweimal zu zahlen:

• Gleicher Schlüssel: ist die erste Suche abgeschlossen, erhalten Sie dieselbe Antwort erneut mit dem Header Idempotent-Replayed: true und ohne zweite Abbuchung; eine fehlgeschlagene Suche gibt denselben Fehler zurück. Läuft sie noch, wartet die Wiederholung auf sie. Verwenden Sie den Schlüssel nur dann erneut, wenn Sie das Ergebnis nicht erhalten haben, nach einem Verbindungsabbruch oder einem Client-Timeout; nach einem 408, 424 oder 5xx senden Sie einen neuen Schlüssel.
• Der Schlüssel allein identifiziert die Suche: eine Wiederholung mit anderem Körper erhält die Antwort der ersten Anfrage; senden Sie eine neue Suche daher mit neuem Schlüssel.
• Ergebnisse werden bis zu 15 Minuten aufbewahrt. Danach liefert eine Wiederholung mit dem alten Schlüssel 409 idempotency_replay_unavailable; senden Sie eine neue Anfrage mit neuem Schlüssel.
• Ohne den Header ist jede Anfrage neu und wird separat berechnet.

curl -X POST https://api.serper.live/v1/search \
  -H "Authorization: Bearer sl_live_YOUR_TOKEN" \
  -H "Idempotency-Key: 0199860b-2f4e-7a1c-9b3d-5e6f70819a2b" \
  -H "Content-Type: application/json" \
  -d '{"query":"best coffee shops","country":"DE","limit":10}'

Der Schlüssel ist eine beliebige Zeichenkette aus 8–128 Zeichen aus A-Za-z0-9._:-. Eine neue UUID pro logischer Anfrage ist die einfachste Wahl; halten Sie sie über alle Wiederholungen dieser Anfrage gleich.

Limits und Wissenswertes

• query 2–120 Zeichen, limit 1–100, Anfragekörper bis 16 KB.
• Suchen laufen parallel bis zur Kapazität des Dienstes; darüber erhalten Sie 503 busy. Wiederholen Sie mit Backoff.
• Meist 2–3 Sekunden für 10 Ergebnisse und etwa eine Sekunde mehr je weiterer Seite; eine Suche, die nach 90 Sekunden noch läuft, endet mit 408 search_timeout. Setzen Sie Ihr Client-Timeout auf mindestens 100 Sekunden.
• Jede Antwort trägt einen X-Request-Id-Header. Behalten Sie ihn in Ihren Logs neben der requestId aus dem Körper.
• Nichts wird zwischengespeichert: zwei identische Anfragen sind zwei Live-Suchen und zwei Abbuchungen. Cachen Sie auf Ihrer Seite, wenn Sie Ergebnisse wiederverwenden.

Die Position einer Domain finden

Die API liefert die organischen Ergebnisse bis limit, standardmäßig die Top 10; eine Site darin zu finden ist eine Schleife über organic[] in Ihrem Code. Vergleichen Sie die domain jedes Eintrags mit dem Host, den Sie verfolgen; die position des ersten Treffers ist der Rang für dieses Keyword, Land und Gerät. Das Beispiel unten tut genau das, mit derselben Anfrage in curl, JavaScript und Python.

Drei Regeln halten den Vergleich sauber:

• Normalisieren Sie vor dem Vergleich: beide Seiten in Kleinbuchstaben, ein führendes www. entfernen und nur Hosts vergleichen, nie vollständige URLs.
• Legen Sie fest, wie Subdomains zählen. blog.example.com ist ein anderer Host als example.com; vergleichen Sie den exakten Host für einen strengen Tracker, oder behandeln Sie jeden Host, der auf .example.com endet, als dieselbe Site für einen Tracker auf Markenebene.
• Kein Treffer bedeutet außerhalb des angeforderten Bereichs für diese Prüfung, keinen Fehler. Speichern Sie es so: eine Anfrage liefert höchstens limit organische Ergebnisse, erhöhen Sie also limit (bis 100, ein Preis pro 10), wenn Sie Positionen jenseits der Top 10 verfolgen.

curl -s -X POST https://api.serper.live/v1/search \
  -H "Authorization: Bearer sl_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"best coffee shops","country":"DE","device":"desktop"}' \
  | jq '.organic[] | select(.domain == "example.com") | .position'

const response = await fetch('https://api.serper.live/v1/search', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer sl_live_YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({ query: 'best coffee shops', country: 'DE', device: 'desktop' }),
    signal: AbortSignal.timeout(100000),
});
const { organic } = await response.json();
const hit = organic.find(row => row.domain === 'example.com');

console.log(hit ? hit.position : 'outside the top 10');

import requests

response = requests.post(
    "https://api.serper.live/v1/search",
    headers={"Authorization": "Bearer sl_live_YOUR_TOKEN"},
    json={"query": "best coffee shops", "country": "DE", "device": "desktop"},
    timeout=100,
)
organic = response.json()["organic"]
position = next((row["position"] for row in organic if row["domain"] == "example.com"), None)
print(position or "outside the top 10")

Die Seite zur Rank-Tracking-API behandelt den vollen Zyklus eines Trackers: Keyword-Listen, Zeitplanung, Speicherung und was ein Monat an Prüfungen kostet.

Mit KI-Agenten nutzen (MCP)

Der MCP-Server von Serper.live gibt KI-Agenten wie Claude, OpenAI Codex, Cursor und VS Code Copilot über diese API eine Live-Google-Suche. Er läuft lokal mit npx, braucht Node.js 20 oder neuer und authentifiziert sich mit demselben API-Token in der Umgebungsvariable SERPER_LIVE_TOKEN; Suchen werden genau wie POST /v1/search abgerechnet.

• google_search: organische Live-Ergebnisse für ein Keyword, ein Land, eine Sprache und ein Gerät, bis zu 100 pro Aufruf.
• domain_position: auf welcher Position eine Domain für ein Keyword steht; eine Subdomain zählt als die Domain, und erscheint die Site mehrfach, wird jede Position geliefert.
• list_countries: die offenen Märkte und die Google-Standardsprache jedes Marktes; kostenlos, ohne Token.

claude mcp add serper-live -e SERPER_LIVE_TOKEN=sl_live_YOUR_TOKEN -- npx -y @serper-live/mcp

{
    "mcpServers": {
        "serper-live": {
            "command": "npx",
            "args": [
                "-y",
                "@serper-live/mcp"
            ],
            "env": {
                "SERPER_LIVE_TOKEN": "sl_live_YOUR_TOKEN"
            }
        }
    }
}

{
    "inputs": [
        {
            "type": "promptString",
            "id": "serper-live-token",
            "description": "Serper.live API token",
            "password": true
        }
    ],
    "servers": {
        "serper-live": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@serper-live/mcp"
            ],
            "env": {
                "SERPER_LIVE_TOKEN": "${input:serper-live-token}"
            }
        }
    }
}

[mcp_servers.serper-live]
command = "npx"
args = ["-y", "@serper-live/mcp"]

[mcp_servers.serper-live.env]
SERPER_LIVE_TOKEN = "sl_live_YOUR_TOKEN"

Das Paket heißt @serper-live/mcp auf npm und io.github.serper-live/serper-live-mcp in der offiziellen MCP Registry; die README im Repository beschreibt die Einrichtung für weitere Clients. Claude Desktop installiert ihn auch mit einem Klick aus dem .mcpb-Bundle und fragt das Token selbst ab, ganz ohne Node.js.