API Documentation

Get search results in under 2 minutes.

1. Get Your API Key

Sign up at dashboard.searlo.tech → Dashboard → API Keys → Create Key

You'll get a key like sk_abc123...

2. Make Your First Request

Include your API key in the x-api-key header:

All API requests require an API key, sent in the x-api-key header or as Authorization: Bearer sk_.... The same key works for the REST API and the MCP server.

Getting Your API Key

1. Sign in at dashboard.searlo.tech

2. Go to Dashboard → API Keys

3. Click Create New Key

4. Copy and save the key immediately (shown only once)

Using Your API Key

Keys start with sk_. Send it as the x-api-key request header on every call, or as Authorization: Bearer sk_....

A key is shown once, when you create it: we keep only a hash of it, and lists show a masked preview (sk_1a2b3c4d••••9f0e), never the key itself.

An API key is for the data API (search, SERP, AI answers, web data, MCP) and for read-only views of its own account: the balance (`GET /credits/balance`), usage, limits, history and GET /user/profile. Managing the account needs a dashboard login: creating or deleting API keys, exporting or deleting your data, payments and billing. An API key used on those routes gets 403 API_KEY_SCOPE_FORBIDDEN, and is not charged. A missing, invalid or expired key gets 401 UNAUTHORIZED.

Search the web and get ranked results with titles, URLs, and snippets.

Endpoint

GET /search/web

> GET /search is an alias for /search/web (it accepts q, limit, page, gl, hl only: no safe, lr, dateRestrict or cache).

Credits: 1 per request. A search that finds nothing, or fails, is not charged.

Parameters

Response

{
  "searchParameters": {
    "q": "machine learning",
    "type": "search",
    "gl": "us",
    "hl": "en",
    "num": 10,
    "page": 1
  },
  "page": 1,
  "nextPage": 2,
  "previousPage": null,
  "totalResults": 1250000,
  "searchTime": 0.42,
  "organic": [
    {
      "position": 1,
      "title": "Introduction to Machine Learning",
      "link": "https://example.com/ml-intro",
      "snippet": "Machine learning is a subset of AI...",
      "description": "An introduction to machine learning concepts and methods.",
      "displayedLink": "example.com",
      "domain": "example.com",
      "favicon": "https://www.google.com/s2/favicons?domain=example.com&sz=32"
    }
  ],
  "credits": 1
}

Responses also set X-Cache (HIT/MISS) and credit headers (X-Credits-Deducted, X-Credits-Remaining).

Pages

Web search serves results down to about result 101. A page whose first result would come after that returns 400 PAGE_OUT_OF_RANGE with the last page it can serve, and is not charged. At limit 10 the last page is 11, at limit 5 it is 21.

{
  "success": false,
  "errorCode": "PAGE_OUT_OF_RANGE",
  "message": "Search pages this query up to page 11 at this limit. Ask for page 11 or earlier.",
  "retryable": false,
  "maxPage": 11
}

Date filter

dateRestrict keeps the results from a recent window: d7 is the last 7 days, w2 the last 2 weeks, m1 the last month and y1 the last year. It works with gl and hl. News Search takes the same filter, and Advanced Search takes it as dateRestrict or dateRange.

A date filter cannot be combined with search operators in q: site:, inurl:, intitle:, filetype:, before: or after:, e-mail addresses and long OR chains. That request returns 400 DATE_FILTER_UNAVAILABLE with retryable: false, and is not charged: remove the filter or the operators. A value that is not one of d, w, m or y followed by a number returns 400 VALIDATION_ERROR.

{
  "success": false,
  "errorCode": "DATE_FILTER_UNAVAILABLE",
  "message": "This query cannot take a date filter: the lane that applies dates does not serve operator queries (site:, filetype:, OR chains, e-mail addresses). Remove the date filter or the operators.",
  "retryable": false
}

Google's Custom Search JSON API is closed to new customers, and existing customers lose it on January 1, 2027. Searlo answers the same request in the same JSON shape, so you move by changing the host and the key:

- https://www.googleapis.com/customsearch/v1?key=GOOGLE_API_KEY&cx=YOUR_CX&q=lectures
+ https://api.searlo.tech/customsearch/v1?key=SEARLO_API_KEY&cx=YOUR_CX&q=lectures

Step-by-step guides, with code we ran before publishing: Python, Node.js, PHP, LangChain, Open WebUI, n8n and WordPress. Google's dates and the full parameter table are on the migration page.

Endpoint

GET https://api.searlo.tech/customsearch/v1
GET https://api.searlo.tech/customsearch/v1/siterestrict
GET https://api.searlo.tech/api/v1/customsearch/v1

All three paths run the same search. /customsearch/v1 is Google's own path, so a client that lets you set the API host needs no other change.

Authentication: pass your Searlo API key (sk_…) in the key parameter, where Google takes its key. The x-api-key header and Authorization: Bearer sk_… also work, and keep the key out of URLs. Searlo strips key from its own logs.

Credits: a call is billed exactly as Web Search bills one: 1 credit per call, whatever num (1 to 10) and start are. A call with searchType=image is billed as Image Search: 1 credit. A call that returns an error is not charged.

Parameters

Response

The response has Google's customsearch#search shape:

{
  "kind": "customsearch#search",
  "url": {
    "type": "application/json",
    "template": "https://api.searlo.tech/customsearch/v1?q={searchTerms}&num={count?}&start={startIndex?}&…&alt=json"
  },
  "queries": {
    "request": [
      {
        "title": "Searlo Custom Search - lectures",
        "totalResults": "2410000",
        "searchTerms": "lectures",
        "count": 10,
        "startIndex": 1,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "cx": "YOUR_CX"
      }
    ],
    "nextPage": [{ "startIndex": 11, "count": 10, "…": "the same fields" }]
  },
  "context": { "title": "Searlo" },
  "searchInformation": {
    "searchTime": 0.21,
    "formattedSearchTime": "0.21",
    "totalResults": "2410000",
    "formattedTotalResults": "2,410,000"
  },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Lectures | MIT OpenCourseWare",
      "htmlTitle": "<b>Lectures</b> | MIT OpenCourseWare",
      "link": "https://ocw.mit.edu/…",
      "displayLink": "ocw.mit.edu",
      "snippet": "Video lectures from …",
      "htmlSnippet": "Video <b>lectures</b> from …",
      "formattedUrl": "https://ocw.mit.edu/…",
      "htmlFormattedUrl": "https://ocw.mit.edu/…"
    }
  ]
}

• •When nothing matches, items is left out, as Google does. queries.nextPage appears only when more results exist.
• •Image results add mime, fileFormat and image. The image object holds contextLink, plus width, height, thumbnailLink, thumbnailWidth and thumbnailHeight when the image source reports them. byteSize is not returned.
• •pagemap appears only when a result has a thumbnail (pagemap.cse_thumbnail). There is no cacheId, labels, promotions or spelling.
• •Every response carries X-Request-ID. Quote it when you contact support.

Errors

Errors use Google's envelope, so code that reads error.code, error.errors[0].reason or error.status keeps working:

{
  "error": {
    "code": 400,
    "message": "Request contains an invalid argument.",
    "errors": [
      { "message": "Request contains an invalid argument.", "domain": "global", "reason": "badRequest", "location": "num", "locationType": "parameter" }
    ],
    "status": "INVALID_ARGUMENT",
    "details": [{ "@type": "type.googleapis.com/google.rpc.RequestInfo", "requestId": "…" }]
  }
}

None of these is charged.

What differs from Google

• •cx has no effect: results come from the whole web, not from an engine's site list. /siterestrict works the same way.
• •Results come from Searlo's web search, so ranking, snippets and the totalResults estimate can differ from your Google engine.
• •Location is country level only, through gl or cr. Boolean cr and lr expressions are not supported.
• •Running out of credits is a 403 dailyLimitExceeded that clears when you top up, not at midnight.
• •Call the API from a server. Browsers on other sites are blocked by CORS, and JSONP (callback) is not supported.

Search for images with thumbnails and source URLs.

Endpoint

GET /search/images

Credits: 1 per request

Parameters

The four filters take effect and combine: size (or imgSize), imgType, imgColorType and imgDominantColor each narrow the results, and the ones applied are echoed in searchParameters. A value outside the lists above returns 400 VALIDATION_ERROR. A page past the last one Google serves ((page - 1) * limit above 200) returns 400 VALIDATION_ERROR that names the last page; it is answered at once and is not charged.

Response

{
  "searchParameters": { "q": "sunset", "type": "images", "gl": "us", "num": 10, "page": 1, "imgSize": "large", "imgType": "photo" },
  "page": 1,
  "nextPage": 2,
  "previousPage": null,
  "totalResults": 50000,
  "searchTime": 0.35,
  "images": [
    {
      "position": 1,
      "title": "Beautiful Sunset",
      "imageUrl": "https://example.com/sunset.jpg",
      "width": 1920,
      "height": 1080,
      "thumbnailUrl": "https://example.com/thumb.jpg",
      "thumbnailWidth": 300,
      "thumbnailHeight": 168,
      "link": "https://example.com/gallery",
      "sourceUrl": "https://example.com/gallery",
      "source": "example.com",
      "domain": "example.com",
      "format": "image/jpeg",
      "imageId": "ANd9GcQexample"
    }
  ],
  "credits": 1
}

• •imageUrl is the image itself, with its size in pixels in width and height. thumbnailUrl is Google's thumbnail, with its own thumbnailWidth and thumbnailHeight.
• •link and sourceUrl are the page the image is on (sourceUrl falls back to the image URL when Google names no page). source and domain name that page's site.
• •format is the image's MIME type, and imageId Google's id for it. A field Google does not give comes back null.

Search news articles from thousands of sources worldwide.

Endpoint

GET /search/news

Credits: 1 per request

Parameters

Response

{
  "searchParameters": { "q": "technology", "type": "news", "gl": "us", "num": 10, "page": 1 },
  "page": 1,
  "nextPage": 2,
  "previousPage": null,
  "totalResults": 12500,
  "searchTime": 0.28,
  "news": [
    {
      "position": 1,
      "title": "Tech News Article",
      "link": "https://news.example.com/article",
      "snippet": "Article summary...",
      "description": "A longer summary from the article's own metadata.",
      "source": "Example News",
      "date": "2026-09-28T10:30:00Z",
      "thumbnail": "https://news.example.com/article.jpg"
    }
  ],
  "credits": 1
}

Search for videos across the web.

Endpoint

GET /search/videos

Credits: 1 per request

Parameters

Response

The same envelope as Web Search, with the results in videos[]. Fields a video does not have come back as null.

{
  "searchParameters": { "q": "react tutorial", "type": "videos", "gl": "us", "num": 10, "page": 1 },
  "page": 1,
  "nextPage": null,
  "previousPage": null,
  "totalResults": 20,
  "searchTime": 1.1,
  "videos": [
    {
      "position": 1,
      "title": "React Tutorial for Beginners",
      "link": "https://video.example.com/watch?v=abc",
      "thumbnailUrl": "https://video.example.com/abc.jpg",
      "duration": "1:02:15",
      "durationSeconds": 3735,
      "source": "Example Channel",
      "sourceUrl": "https://video.example.com/@example",
      "publishedDate": "1 year ago",
      "views": "2.1M views",
      "viewCount": 2100000,
      "snippet": "Learn React in 1 hour...",
      "videoId": "abc"
    }
  ],
  "credits": 1
}

Restrict a web search to a single site or domain.

Endpoint

GET /search/site

Credits: 1 per request

Parameters

Response

The same response as Web Search (results in organic[]), scoped to the given site.

Run complex queries with filters: date range, file type, exact phrases, excluded terms and site restriction. Available as GET (query params) or POST (JSON body).

Endpoint

GET  /search/advanced
POST /search/advanced

Credits: 1 per request

Parameters

Provide the query as either query or q (one is required).

A date filter (dateRange, timeRange or dateRestrict) cannot be combined with site, fileType or search operators in q: that request returns 400 DATE_FILTER_UNAVAILABLE and is not charged. exactTerms and excludeTerms work with a date.

Response

The same response as Web Search (results in organic[]).

Search product/shopping results.

Endpoint

GET /search/shopping

Credits: 1 per request

Parameters

Response

{
  "success": true,
  "searchParameters": { "q": "wireless earbuds", "type": "shopping", "gl": "us", "hl": "en" },
  "shopping": [
    { "title": "Wireless Earbuds Pro", "price": "$79.99", "source": "example-store.com", "link": "https://..." }
  ],
  "source": "searlo.tech(google)"
}

If no products are found you get a 200 with "shopping": []. If results are temporarily unavailable you get a 503 with "retryable": true.

Local business data from Google Maps: search the map, list the businesses that match a query in a named place, read one place's reviews, and get one place's full details: its attributes (payments, service options, children…) and menu.

Endpoints

GET /search/maps
GET /search/places
GET /search/reviews
GET /search/place-details

Credits: 1 per request. These four endpoints also count against a tighter local rate-limit group, on top of the search group: a request must pass both (see Rate Limiting).

Maps Parameters

Maps Response

{
  "searchParameters": { "q": "coffee shops in austin", "type": "maps", "gl": "us", "hl": "en", "num": 20, "page": 1, "ll": "@39.5,-98.35,5z" },
  "lite": false,
  "page": 1,
  "totalResults": 20,
  "places": [
    {
      "position": 1,
      "title": "Example Coffee Roasters",
      "placeId": "ChIJ7cv00Dm1RIYRx5mHcIYlGmE",
      "cid": "0x8644b5a4e3d8f52b:0x5e1c2c3a4b5d6e7f",
      "featureId": "/g/11c5k8tq1n",
      "category": "Coffee shop",
      "categories": ["Coffee shop", "Cafe"],
      "rating": 4.7,
      "reviews": 1834,
      "price": "$$",
      "address": "123 Congress Ave, Austin, TX 78701",
      "latitude": 30.2672,
      "longitude": -97.7431,
      "website": "https://coffee.example.com/",
      "domain": "coffee.example.com",
      "phone": "(512) 555-0100",
      "timezone": "America/Chicago",
      "description": "Small-batch roaster with a patio.",
      "openState": "Open · Closes 6 PM",
      "openNow": true,
      "businessStatus": "OPERATIONAL",
      "hours": null,
      "openingDate": null,
      "openingDateText": null,
      "attributes": {
        "service_options": { "serves_dine_in": true, "has_takeout": true, "has_delivery": false },
        "payments": { "requires_cash_only": false, "pay_credit_card": true, "pay_mobile_nfc": true }
      },
      "thumbnailUrl": "https://lh5.googleusercontent.com/...",
      "reviewsLink": "https://www.google.com/maps/...",
      "bookingLink": null,
      "bookingLinks": null
    }
  ],
  "source": "searlo.tech(engine)",
  "credits": 1
}

• •lite: true means Google served its reduced record. Since October 2026 that is what Google Maps shows every signed-out visitor, so expect lite: true on maps and places: no price level, and accessibility as the only attribute group (the sample above shows the full record). A lite answer is never cached.
• •businessStatus says whether the place still trades: OPERATIONAL, CLOSED_TEMPORARILY or CLOSED_PERMANENTLY, as the Places API names them, or null when Google's record does not say. It is never guessed from missing data.
• •openNow is true or false for whether the place is open right now, or null when the record does not say. openState is Google's own state line, in the language of hl ("Abierto · Cierre: 21:30" with hl=es). A place that has closed (businessStatus CLOSED_TEMPORARILY or CLOSED_PERMANENTLY) has both set to null.
• •With no ll, lat or lng, gl also sets where the search looks: the main city of that country, for 51 countries (gl=es with farmacia answers from Spain, not the US). A place named in q (hoteles en tokio) decides for itself. gl=us, no gl, and a country without a default area keep the US-wide default. searchParameters.ll echoes the area used.
• •In a maps result, cid is the 0x…:0x… place id, featureId is a Knowledge Graph id (/g/…) and placeId is the Google Place ID (ChIJ…).
• •bookingLink is the single link to send a user to when the place takes bookings or orders; bookingLinks holds the full set.
• •attributes is Google's "About" list for the place, grouped as Google groups it (service_options, payments, children, parking, offerings…) and keyed by Google's own ids, the same in every language. A yes/no attribute is true or false (attributes.payments.requires_cash_only is true on a cash-only place, false where Google says it is not), a value attribute is a string (price_level), a list one an array (pay_credit_card_types_accepted). It is null when Google lists none, and a lite answer carries accessibility only.
• •A place listed before it opens has openingDateText, Google's text in your hl ("Opens 1 Nov"), and openingDate, the date read from it ("2026-11-01"). Both are null on a place that is open, and so is openState on one that is not open yet. /search/places carries the same two fields.
• •A maps query that finds nothing answers 200 with places: [], and is not charged.

Places Parameters

GET /search/places lists the businesses that match a query in a place you name, instead of a map viewport.

Places Response

{
  "searchParameters": { "q": "dentist", "type": "places", "location": "Austin, Texas", "gl": "us", "hl": "en", "num": 20, "page": 1 },
  "lite": false,
  "page": 1,
  "totalResults": 20,
  "places": [
    {
      "position": 1,
      "title": "Example Family Dental",
      "address": "456 Lamar Blvd, Austin, TX 78703",
      "latitude": 30.2849,
      "longitude": -97.7545,
      "rating": 4.9,
      "ratingCount": 412,
      "category": "Dentist",
      "categories": ["Dentist", "Cosmetic dentist"],
      "priceLevel": null,
      "phoneNumber": "(512) 555-0199",
      "website": "https://dental.example.com/",
      "domain": "dental.example.com",
      "openState": "Closed · Opens 8 AM",
      "openNow": false,
      "businessStatus": "OPERATIONAL",
      "hours": null,
      "openingDate": null,
      "openingDateText": null,
      "attributes": { "payments": { "pay_credit_card": true, "requires_cash_only": false } },
      "thumbnailUrl": "https://lh5.googleusercontent.com/...",
      "cid": "0x8644b5a4e3d8f52b:0x2f1e3d4c5b6a7980",
      "featureId": "0x8644b5a4e3d8f52b:0x2f1e3d4c5b6a7980",
      "knowledgeGraphId": "/g/1tf6yx2q",
      "placeId": "ChIJN1t_tDeuEmsRUsoyG83frY4"
    }
  ],
  "source": "searlo.tech(google_places)",
  "credits": 1
}

A places query that finds nothing returns 200 with places: [], and is not charged. openState, openNow, businessStatus and lite mean the same as on maps.

Reviews Parameters

GET /search/reviews returns the reviews for one place. Identify it one of four ways. placeId, featureId and cid are faster than q, which costs a place lookup first.

Reviews Response

{
  "searchParameters": { "type": "reviews", "featureId": "0x8644b5a4e3d8f52b:0x2f1e3d4c5b6a7980", "hl": "en", "gl": "us", "num": 10 },
  "place": {
    "title": "Example Family Dental",
    "address": "456 Lamar Blvd, Austin, TX 78703",
    "featureId": "0x8644b5a4e3d8f52b:0x2f1e3d4c5b6a7980",
    "rating": 4.9,
    "reviewCount": 412
  },
  "totalResults": 8,
  "hasMore": true,
  "hasNextPage": true,
  "nextPageToken": "CAESBkVnSUlDQQ",
  "reviews": [
    {
      "position": 1,
      "reviewId": "ChZDSUhNMG9nS0VJQ0FnSUNf",
      "rating": 5,
      "text": "Friendly staff and no wait.",
      "date": "2026-09-14T16:20:00.000Z",
      "timestamp": 1789402800,
      "relativeDate": "2 weeks ago",
      "language": "en",
      "author": "Jordan P.",
      "authorProfile": "https://www.google.com/maps/contrib/...",
      "authorPhoto": "https://lh3.googleusercontent.com/...",
      "authorId": "104512345678901234567",
      "authorReviewCount": 37,
      "isLocalGuide": true,
      "response": { "text": "Thank you, Jordan!", "relativeTime": "a week ago", "date": "2026-09-21T09:00:00.000Z", "language": "en" }
    }
  ],
  "source": "searlo.tech(google_reviews)",
  "credits": 1
}

• •Each call returns the first page of reviews Google serves with the place, about eight, in any language: hl sets the language of relativeDate, and language is the one each review was written in.
• •hasMore (also hasNextPage) is true when the place has more reviews than that page. Later pages cannot be fetched yet: nextPageToken, when present, is Google's token for them, and no parameter takes it. place.reviewCount is the lifetime count.
• •date is the ISO time, timestamp the same in Unix seconds and relativeDate Google's own text.
• •response is present only when the owner replied: text, relativeTime, date and language.
• •A place with no reviews answers 200 with reviews: [], and is not charged. A place Google reports reviews for but sent without them answers 503 REVIEWS_WITHHELD (retryable: true), also not charged: retry the request.

Place Details Parameters

GET /search/place-details returns everything Google's place panel holds for one place: every field a maps result has, plus the full attribute list and the menu. Identify the place as on reviews; a placeId costs no lookup.

Place Details Response

{
  "searchParameters": { "type": "place-details", "placeId": "ChIJV8rJWPR1nkcRfAVGOrZIeVs", "featureId": "0x479e75f458c9ca57:0x5b7948b63a46057c", "hl": "en", "gl": "de" },
  "lite": true,
  "place": {
    "title": "Augustiner Klosterwirt",
    "placeId": "ChIJV8rJWPR1nkcRfAVGOrZIeVs",
    "cid": "0x479e75f458c9ca57:0x5b7948b63a46057c",
    "featureId": "/g/1ptx9q8dt",
    "category": "Bavarian restaurant",
    "rating": 4.5,
    "reviews": 14740,
    "address": "Augustinerstraße 1, 80331 München-Altstadt-Lehel, Germany",
    "website": "http://augustiner-klosterwirt.de/",
    "phone": "+498955054466",
    "openState": "Open · Closes 12 AM",
    "openNow": true,
    "businessStatus": "OPERATIONAL",
    "hours": [{ "day": "Friday", "hours": ["9:30 AM–12 AM"] }],
    "attributes": {
      "accessibility": { "has_wheelchair_accessible_entrance": true, "has_wheelchair_accessible_restroom": true }
    },
    "menu": {
      "url": "https://augustiner-klosterwirt.de/index.php/speisen-getraenke/speisekarte",
      "sections": [
        {
          "name": "Soups",
          "items": [{ "name": "Bavarian Liver Dumpling Soup", "description": "With fresh parsley", "price": "€7.50" }]
        }
      ],
      "photos": []
    },
    "menuStatus": "found"
  },
  "source": "searlo.tech(google_place)",
  "credits": 1
}

• •place carries every field of a maps result (openState, openNow, businessStatus, openingDate, bookingLinks…) with the same meaning.
• •menu is the menu Google holds for the place: url (the restaurant's own menu page) and sections of items with descriptions and prices as Google shows them, in the language hl names. Since October 2026 Google Maps shows signed-out visitors no menu, so for a place that serves food the menu is read from the place's Google Search panel instead. photos is empty for now. Any part Google does not have is empty, and menu is null when it has none.
• •menuStatus says how the menu lookup went: found; none (Google holds no menu for the place); pending (still being read: ask again in a few minutes and it is there, which is how a large batch gets its menus, on a second pass); unavailable (the lookup failed: retry later). It is absent for a place that serves no food. A menu is kept for 7 days, so asking again costs no wait.
• •lite: true means Google answered its reduced place record: since October 2026 that is what Google Maps shows every signed-out visitor, with accessibility as the only attribute group and no price level. A lite answer is never cached.
• •A placeId that names no business (an address or plus-code id) or a q that matches nothing answers 400, an id Google does not know 404, both with errorCode: "PLACE_NOT_FOUND" and not charged.

Google Scholar and Google Patents results. Both use the same organic array as web results, with the scholarly or patent fields alongside.

Endpoints

GET /search/scholar
GET /search/patents

Credits: 1 per request

Scholar Parameters

Scholar Response

{
  "searchParameters": { "q": "transformer attention", "type": "scholar", "hl": "en", "num": 10, "page": 1, "yearFrom": 2020 },
  "page": 1,
  "totalResults": 128000,
  "hasNextPage": true,
  "organic": [
    {
      "position": 1,
      "title": "An example study of attention mechanisms",
      "link": "https://arxiv.org/abs/2001.00001",
      "snippet": "We study how attention...",
      "domain": "arxiv.org",
      "authors": ["A Author", "B Author"],
      "year": 2021,
      "publication": "arXiv preprint",
      "type": "PDF",
      "citedBy": 1520,
      "citedByLink": "https://scholar.google.com/scholar?cites=2960712678066186980",
      "pdfLink": "https://arxiv.org/pdf/2001.00001",
      "resultId": "u8Yx3kZ1abcJ",
      "citesId": "2960712678066186980",
      "clusterId": "2960712678066186980"
    }
  ],
  "source": "searlo.tech(google_scholar)",
  "credits": 1
}

• •citesId and clusterId come back on every result. Pass one back as cites or cluster to walk the citation graph.
• •totalResults is Scholar's own estimate for the whole query, not the page size.
• •type is Scholar's tag for the result (BOOK, PDF, HTML, CITATION) or null.
• •A query with no results returns 200 with an empty organic array.

Patents Parameters

Patents Response

{
  "searchParameters": { "q": "solid state battery", "type": "patents", "num": 10, "page": 1 },
  "page": 1,
  "totalResults": 23000,
  "totalPages": 100,
  "hasNextPage": true,
  "organic": [
    {
      "position": 1,
      "title": "Solid-state battery with an example electrolyte",
      "link": "https://patents.google.com/patent/US11000000B2/en",
      "snippet": "A solid-state battery comprising...",
      "patentId": "patent/US11000000B2/en",
      "publicationNumber": "US11000000B2",
      "inventor": "Jane Inventor",
      "assignee": "Example Corp",
      "priorityDate": "2019-05-14",
      "filingDate": "2020-05-12",
      "grantDate": "2021-05-11",
      "publicationDate": "2021-05-11",
      "language": "en",
      "pdfLink": "https://patentimages.storage.googleapis.com/.../US11000000.pdf",
      "thumbnailUrl": "https://patentimages.storage.googleapis.com/...",
      "figures": [
        { "thumbnail": "https://patentimages.storage.googleapis.com/...", "full": "https://patentimages.storage.googleapis.com/..." }
      ]
    }
  ],
  "source": "searlo.tech(google_patents)",
  "credits": 1
}

• •totalPages and hasNextPage come from Google Patents' own counts.
• •figures lists the drawings, each as a thumbnail and a full image URL.
• •A query with no results returns 200 with an empty organic array.

Legacy web search that returns a simplified, flat result format. Use Web Search for new integrations.

Endpoint

GET /search/simple

Credits: 1 per request

Parameters

Response

{
  "success": true,
  "data": { "results": [ { "title": "...", "link": "...", "snippet": "..." } ] },
  "message": "Simple search completed successfully"
}

Google Autocomplete: the suggestions Google offers while a query is being typed.

Endpoint

GET /search/suggestions

Credits: 0.5 per request

Parameters

Response

{
  "success": true,
  "data": {
    "query": "machine lear",
    "suggestions": ["machine learning", "machine learning python", "machine learning course"],
    "source": "searlo.tech(engine)",
    "timestamp": "2026-09-29T10:00:00.000Z"
  },
  "message": "Suggestions retrieved successfully"
}

The suggestions are in data.suggestions, as plain strings. An upstream failure returns 502 or 503 with success: false, and the credits are refunded.

Trending (not available)

GET /search/trending is not available. The route exists but has no data source behind it: it answers 200 with an error object in data instead of trending queries. Do not build on it.

Run multiple web searches in a single request.

Endpoint

POST /search/batch

Credits: 1 credit per distinct query that found something, up to 10 queries. A query that failed or found nothing costs nothing, and a query repeated in the batch (ignoring case) is charged once; each item's result.credits and data.credits say what was charged.

Body

Response

{
  "success": true,
  "data": {
    "success": true,
    "results": [
      { "query": "react", "result": { "searchParameters": { "q": "react" }, "organic": [ /* ... */ ], "credits": 1 }, "source": "searlo.tech(engine)", "timestamp": "2026-10-05T09:00:00.000Z" },
      { "query": "vue", "result": { "searchParameters": { "q": "vue" }, "organic": [ /* ... */ ], "credits": 1 }, "source": "searlo.tech(engine)", "timestamp": "2026-10-05T09:00:00.000Z" }
    ],
    "totalQueries": 2,
    "credits": 2
  },
  "message": "Batch search completed successfully"
}

Google's whole results page as JSON: organic results, videos, ads, People Also Ask, related searches, the knowledge graph and the AI Overview. Each page is fetched live from Google and parsed, in a few seconds, AI Overview included: the overview is read in full from the page as Google served it. An overview Google loads after the page is read from the rendered page instead, which adds several seconds. Web Search returns organic results only, for 1 credit, in about a second.

Endpoints

GET  /serp
POST /serp/batch
GET  /serp/features
GET  /search/news/serp

> GET /search/serp is an alias of GET /serp: same parameters, same price.

Credits: 3 per page delivered (pages asks for up to 10; a page Google does not have, or one that repeats the page before it, is not billed), +1 with rawHtml=true. A SERP with no results is not charged. An AI Overview read in full from the page as served is included at no extra charge. From 2026-11-01, a request whose AI Overview had to be completed by rendering the page costs 5 more (8 for a one-page request), and the response says aioverview.rendered: true; with aioverview=false it never does. Until then it stays 3. A cached result is billed like a live one, rendered or not. credits in the body and the X-Credits-Deducted header say what was charged.

Search operators (site:, intitle:, inurl:, filetype:, before:/after:), e-mail lookups and long OR chains are not served: they answer 422 QUERY_NOT_SERVED with retryable: false, not charged.

> Want Google's page itself rather than JSON, or the page an iPhone gets? See SERP HTML.

Parameters

Response

{
  "success": true,
  "searchParameters": { "q": "best running shoes", "gl": "us", "hl": "en", "page": 1, "pages": 1, "num": 10, "device": "desktop", "type": "serp" },
  "organic": [
    {
      "position": 1,
      "title": "The Best Running Shoes of 2026",
      "url": "https://www.example.com/best-running-shoes",
      "redirectUrl": null,
      "resolved": true,
      "displayedUrl": "https://www.example.com › reviews",
      "domain": "example.com",
      "snippet": "We ran more than 500 miles in 40 pairs...",
      "date": "Sep 12, 2026",
      "sitelinks": [{ "title": "Road shoes", "url": "https://www.example.com/road" }],
      "page": 1
    }
  ],
  "videos": [
    { "position": 1, "title": "Best Running Shoes 2026", "url": "https://www.youtube.com/watch?v=abc123", "redirectUrl": null, "resolved": true, "source": "YouTube", "channel": "Example Running" }
  ],
  "ads": [
    { "position": 1, "block": "top", "title": "Running Shoes Sale", "url": "https://shop.example.com/", "displayedUrl": "shop.example.com", "description": "Free shipping on all orders." }
  ],
  "peopleAlsoAsk": [{ "question": "What running shoes do podiatrists recommend?" }],
  "relatedSearches": [{ "query": "best running shoes for women" }],
  "knowledgeGraph": null,
  "aioverview": {
    "text": "The best running shoe depends on your gait and distance...",
    "markdown": "The best running shoe depends on your gait and distance...",
    "sources": [
      { "position": 1, "label": "Example Running", "title": "Best running shoes, tested", "supportingCount": 0, "url": "https://www.example.com/tested", "redirectUrl": null, "resolved": true, "domain": "example.com" }
    ],
    "complete": true
  },
  "aiModeAvailable": true,
  "pagesFetched": 1,
  "gotoResolved": 4,
  "fetchedAt": "2026-09-29T10:00:00.000Z",
  "source": "searlo.tech(google_serp)",
  "cached": false
}

• •Organic results carry the destination in url (Web Search uses link). When Google wrapped a result in a /goto redirect, redirectUrl holds that link and resolved says whether url is the final destination. gotoResolved counts the links resolved for you.
• •peopleAlsoAsk lists the questions only (question), not their answers. relatedSearches items carry query. knowledgeGraph (title, type, description, attributes, website) is null when the page has none.
• •aioverview is null when Google showed no AI Overview; its sources are the pages it cited. complete is true when the overview was read in full, from the page as served or from the rendered page, and false when only part of it could be read. pending: true with an empty text marks an overview Google loads after the page; GET /serp then reads it from the rendered page. rendered: true marks an overview completed that way, which from 2026-11-01 makes the request cost 5 more (see Credits). Its sources come back resolved: url is the cited page and redirectUrl Google's /goto link. aiModeAvailable says whether the page offered an AI Mode tab.
• •With pages above 1, organic results from the later pages are appended with continuing position values and their own page. Ads, videos, People Also Ask, related searches, the knowledge graph and the AI Overview come from the first page only.
• •position counts from 1 within the response: with page=3 the first organic result is position 1 on page 3.
• •pagesFetched can be lower than pages when a later page did not render. Billing follows the pages you requested.
• •Responses set X-Cache (HIT/MISS). Identical requests in flight at the same moment share one fetch, and each of them is billed.

Location

Every Google endpoint applies the country and the language: gl sets the country and hl the language. location takes a country too, by name or two-letter code, and becomes its gl.

City- and state-level location is not available yet. In our tests (September 2026) Google no longer localizes a results page by uule, so a city, a state or a non-country uule is refused, and not charged, rather than answered with results for somewhere else:

{
  "success": false,
  "code": "CITY_LOCATION_UNAVAILABLE",
  "retryable": false,
  "message": "City- and state-level location is not available yet. Country (gl) and language (hl) are applied: pass the country as gl, or as location (for example \"Germany\").",
  "location": "Austin,Texas,United States"
}

The same rule applies to POST /serp/batch, GET /serp/features, GET /search/news/serp, SERP HTML, Rank Checks and the serp, news/serp and rankings/check async tasks.

Errors

Failed calls are refunded. The account rate limit 429 (code 4201 or 4202) is separate from AT_CAPACITY.

Batch Endpoint

POST /serp/batch

Credits: 3 per distinct keyword per page delivered. The batch reserves 3 × keywords × pages when it is accepted (plus 5 per keyword with aioverview: true from 2026-11-01) and is charged what it delivered: a keyword that failed or found nothing costs nothing. Duplicate keywords (ignoring case) are billed once. 20 keywords at 1 page cost at most 60 credits without rendered overviews. From 2026-11-01, with aioverview: true, a keyword whose AI Overview had to be completed by rendering the page costs 5 more (aioverview.rendered: true on its row). Each row's credits and credits.used say what was charged.

Up to 20 keywords run synchronously in one request, with one set of settings for all of them; meta.max_sync_batch reports the cap in force. For larger runs, queue serp tasks with Async Tasks.

{
  "schema": "serp-batch.v1",
  "results": [
    {
      "keyword": "running shoes",
      "success": true,
      "searchParameters": { "q": "running shoes", "gl": "us", "hl": "en", "page": 1, "pages": 1, "num": 10, "device": "desktop", "type": "serp" },
      "organic": [{ "position": 1, "title": "Running Shoes", "url": "https://www.example.com/running" }],
      "videos": [],
      "ads": [],
      "peopleAlsoAsk": [{ "question": "How often should you replace running shoes?" }],
      "relatedSearches": [{ "query": "running shoes sale" }],
      "knowledgeGraph": null,
      "aiModeAvailable": true,
      "pagesFetched": 1,
      "gotoResolved": 0,
      "fetchedAt": "2026-09-29T10:00:00.000Z",
      "source": "searlo.tech(google_serp)",
      "cached": false
    },
    {
      "keyword": "trail running shoes",
      "success": false,
      "status": 429,
      "code": "AT_CAPACITY",
      "retryable": true,
      "message": "Google SERP is at capacity. Retry in 60s — immediate retries will be refused."
    }
  ],
  "credits": { "used": 6 },
  "meta": { "requested": 2, "distinct": 2, "succeeded": 1, "failed": 1, "pages": 1, "gl": "us", "hl": "en", "device": "desktop", "max_sync_batch": 20 }
}

A keyword that fails inside a 200 batch is not billed (since 2026-10-05). The batch answers 200 whenever it ran; read meta.failed and each failed row's retryable before you resubmit.

Features Endpoint

GET /serp/features

Credits: 3 per request (one results page). It only checks whether an AI Overview is present, so it never renders and never costs more.

Which features a query's results page shows, without the page itself. Parameters: q (required, 1–400 chars), gl, hl, location (a country) or uule, device, safe and cache, as on GET /serp.

{
  "schema": "serp-features.v1",
  "query": "best running shoes",
  "features": ["organic", "ads", "ai_overview", "people_also_ask", "related_searches", "video", "sitelinks"],
  "counts": { "organic": 10, "ads": 3, "shopping": 0, "videos": 3, "people_also_ask": 4, "related_searches": 8, "local_pack": 0, "top_stories": 0, "image_pack": 0 },
  "organic_count": 10,
  "credits": { "used": 3 },
  "meta": { "gl": "us", "hl": "en", "device": "desktop", "cached": false, "fetchedAt": "2026-09-29T10:00:00.000Z" }
}

Feature names come from this list: organic, ads, shopping, ai_overview, ai_mode, featured_snippet, people_also_ask, related_searches, knowledge_graph, video, local_pack, sitelinks, top_stories, image_pack, twitter, faq. The results-page parse does not currently return shopping, local pack, top stories, image pack, Twitter, FAQ or featured-snippet blocks, so those names do not appear today and their counts stay 0.

News Results Page

GET /search/news/serp

Credits: 2 per page requested.

Google's News tab, fetched live and parsed: cards with title, source, date, snippet and thumbnail, about a second per page. Parameters: q (required, 1–400 chars), gl, hl, location (a country) or uule, page (1–100), pages (1–10), tbs (e.g. qdr:d for the past day), googleGoto (default: true, resolves the cards' /goto links to the articles) and cache, as on GET /serp.

Cards come in Google's order, with continuing position values and the page each came from. For a developing story Google shows several articles as a group, and each is its own card, so a page can hold more than 10. snippet is empty for grouped articles, which Google shows without one. hasNextPage says whether Google offered a further page.

{
  "success": true,
  "searchParameters": { "q": "electric vehicles", "gl": "us", "hl": "en", "page": 1, "pages": 1, "type": "news", "mode": "serp" },
  "news": [
    { "position": 1, "title": "EV sales rise again", "url": "https://news.example.com/ev-sales", "redirectUrl": null, "resolved": true, "source": "Example News", "snippet": "Sales of electric vehicles...", "date": "3 hours ago", "thumbnail": "https://news.example.com/thumb.jpg", "page": 1 }
  ],
  "hasNextPage": true,
  "pagesFetched": 1,
  "gotoResolved": 18,
  "fetchedAt": "2026-09-29T10:00:00.000Z",
  "source": "searlo.tech(google_news_serp)",
  "cached": false
}

Google's results page as HTML, for callers that parse the page themselves. Two ways, one endpoint:

• •Without JavaScript (default): the full results page exactly as Google's server sent it. Nothing is extracted, rewritten or re-serialised: result links are Google's own /goto redirects, as on the page. Typically 2–3 seconds, about 1 MB of HTML.
• •With JavaScript (js=true): the same page rendered, with the AI Overview opened out: finished streaming, with its Show more and Show all sections expanded in the DOM that comes back. Typically 8–15 seconds. Images, fonts and media are not downloaded; the HTML references them.

Both work for desktop and for iOS (device=ios): the page Google serves to Safari on an iPhone.

Endpoint

GET /serp/html

Credits: 2 per page; 8 per page with js=true. Failed calls are refunded. Never cached: each call fetches the page at request time.

Parameters

One call is one results page: page=2 is results 11–20. Google serves about ten organic results a page and has not honoured a larger num since 2025, so there is no num here. Two identical calls are two fetches, and two pages.

Raw or rendered?

Raw is the choice for rank and SERP-feature data at volume. Rendered is for the AI Overview's full text and sources, or the page as a person sees it. For the overview as JSON rather than HTML, Full SERP reads it in full for 3 credits (from 2026-11-01, 8 when it has to render the page to complete the overview).

Response (format=json)

{
  "success": true,
  "searchParameters": { "q": "how does compound interest work", "type": "rendered", "gl": "us", "hl": "en", "page": 1, "device": "desktop" },
  "html": "<!doctype html><html itemscope=\"\" itemtype=\"http://schema.org/SearchResultsPage\" lang=\"en\">…",
  "url": "https://www.google.com/search?q=how+does+compound+interest+work&hl=en&gl=us",
  "empty": false,
  "rendered": true,
  "aio": { "present": true, "expanded": true, "sourcesOpened": true, "showAll": "pressed", "sourcesBefore": 7, "sources": 7, "sourcesVisible": 11 },
  "aiOverview": {
    "text": "Compound interest is interest earned on both the principal and the interest already added to it...",
    "markdown": "Compound interest is interest earned on both the principal and the interest already added to it...",
    "sources": [{ "position": 1, "label": "Investopedia", "url": "https://www.google.com/goto?url=…", "resolved": false }]
  },
  "bytes": 2089123,
  "fetchedAt": "2026-09-29T18:39:40.000Z",
  "source": "searlo.tech(google_serp_rendered)",
  "credits": { "used": 8 }
}

Response (format=raw)

The body is the page itself, Content-Type: text/html; charset=utf-8. The metadata moves to headers:

AI Overview notes

• •Google decides whether an AI Overview appears, per query and per request. aio.present tells you; the page is billed either way.
• •Desktop: the overview renders in two parts once opened; all of its sources are in the returned HTML, and Show all makes them visible. A short sources list is shown in full without one (showAll absent or complete).
• •iOS: the mobile overview has no Show all control (showAll: "absent", sourcesOpened: true); its sources are cards inside the overview, all in the HTML. Its Show more lifts a height limit rather than adding content, so on iOS aio.expanded means the tap went through. The overview's full text is in the HTML once it has finished streaming, which is what the render waits for.
• •An AI Overview is non-deterministic: the same query can return a different overview, with different sources, from one request to the next.

iOS

device=ios returns the mobile layout Google serves to Safari on an iPhone, from an emulated iPhone rather than a physical device.

Latency, capacity and timeouts

Measured through the public API (Cloudflare, our edge, the SERP hosts) in September 2026:

Pages are fetched on dedicated SERP hosts. One host sustains at least 5 raw pages a second (97% or better at 16 concurrent requests, the most we have driven it) and about 0.7 rendered pages a second (rendering is CPU-bound), and capacity grows by adding hosts. For sustained volume, tell us your daily volume and peak rate per mode, and capacity is reserved for your key before you ramp.

Set client timeouts of 30 s for raw pages and 90 s for rendered ones. The server gives up at about 92 s and answers either way: a call that runs out of time is a 503 and is not charged.

Retries

• •429 BUSY: the endpoint is at capacity (with js=true, rendering capacity). Wait Retry-After seconds (1–10) and retry.
• •503 with retryable: true (UPSTREAM_UNAVAILABLE): no usable page was available within the call. Retry with backoff, for example after 2, 5 and 10 seconds.
• •400 and 422: retrying the same request gives the same answer.
• •A failed call is never charged, so a retry cannot bill twice: you pay once, for the call that returns the page.

Errors

None of them is charged. A failure answers JSON even with format=raw:

{
  "success": false,
  "code": "QUERY_NOT_SERVED",
  "retryable": false,
  "message": "This query shape is not served as raw HTML: search operators (site:, inurl:, intitle:, filetype:, before:/after:), e-mail lookups and long OR chains."
}

Going to production

• •Use format=raw when you store or parse the page: it arrives as text/html with no JSON escaping, and the metadata is in the X-Searlo-* headers.
• •Send Accept-Encoding: gzip. A raw page is about 1 MB of HTML and compresses to a fraction of that.
• •Honour Retry-After on every 429, and retry 503s marked retryable: true with backoff.
• •Use the timeouts above: 30 s raw, 90 s rendered.
• •Track spend from X-Credits-Used (credits.used in JSON) and X-Credits-Remaining.
• •Read `GET /search/capabilities` for the endpoint's live state and its success rate over the last two hours.
• •A key's default caps are 20,000 requests a minute and 400,000 a day (Rate Limiting). Ask us for custom limits and reserved capacity before a large ramp.

Where a domain ranks for a keyword, read from a live Google results page: the position, the page that ranks and the domains above it. Every check is stored, so the history builds up from your own checks.

Endpoints

POST /rankings/check
POST /rankings/batch
GET  /rankings/history

Credits: 3 per 10 results of depth, because each 10 results is one results page read. The default depth of 100 costs 30 credits; depth 10 costs 3. A batch costs that for each distinct keyword. History is free.

Check Parameters

Check Response

{
  "schema": "ranking-check.v1",
  "result": {
    "keyword": "project management software",
    "domain": "example.com",
    "position": 4,
    "url": "https://www.example.com/features",
    "title": "Project management features | Example",
    "found": true,
    "search_depth": 30,
    "organic_count": 30,
    "pages_fetched": 3,
    "gl": "US",
    "hl": "en",
    "device": "desktop",
    "serp_features": ["organic", "ads", "people_also_ask", "related_searches", "sitelinks"],
    "competitors_above": ["asana.com", "monday.com", "clickup.com"],
    "checked_at": "2026-09-29T10:00:00.000Z",
    "cached": false
  },
  "credits": { "used": 9 }
}

• •found: false with position: null means the domain was not in the top search_depth results. search_depth is what was asked for, so a short results page does not change what found: false means.
• •competitors_above lists up to 20 domains ranking above yours, top first. When the domain was not found, it lists the domains on the page.
• •serp_features uses the SERP features vocabulary. A rank check skips the AI Overview, so ai_overview never appears here.
• •A failed results-page read returns 429 (AT_CAPACITY) or 503 (UPSTREAM_UNAVAILABLE), as on /serp, and is refunded. An unparseable domain is 400 INVALID_DOMAIN.

Batch Endpoint

POST /rankings/batch

One domain, up to 20 keywords: keywords (1–20, each 1–400 chars) and domain, plus the same depth, gl, hl, device, location and cache fields as a check. Each keyword is a separate check and a separate history entry. meta.max_sync_batch reports the cap in force.

{
  "schema": "ranking-batch.v1",
  "results": [
    { "success": true, "keyword": "project management software", "domain": "example.com", "position": 4, "url": "https://www.example.com/features", "title": "Project management features | Example", "found": true, "search_depth": 30, "organic_count": 30, "pages_fetched": 3, "gl": "US", "hl": "en", "device": "desktop", "serp_features": ["organic", "ads"], "competitors_above": ["asana.com"], "checked_at": "2026-09-29T10:00:00.000Z", "cached": false },
    { "keyword": "kanban board software", "success": false, "code": "UPSTREAM_UNAVAILABLE", "retryable": true, "message": "Google SERP is temporarily unavailable. Please try again shortly." }
  ],
  "credits": { "used": 18 },
  "meta": { "domain": "example.com", "requested": 2, "distinct": 2, "measured": 1, "ranking": 1, "failed": 1, "max_sync_batch": 20 }
}

A keyword that fails inside a 200 batch is still billed.

History Endpoint

GET /rankings/history

Credits: Free (0).

{
  "schema": "ranking-history.v1",
  "series": [
    { "keyword": "project management software", "domain": "example.com", "gl": "US", "hl": "en", "device": "desktop", "position": 4, "url": "https://www.example.com/features", "search_depth": 30, "serp_features": ["organic", "ads"], "checked_at": "2026-09-29T10:00:00.000Z" },
    { "keyword": "project management software", "domain": "example.com", "gl": "US", "hl": "en", "device": "desktop", "position": 6, "url": "https://www.example.com/features", "search_depth": 30, "serp_features": ["organic", "ads"], "checked_at": "2026-09-28T10:00:00.000Z" }
  ],
  "change": { "delta": 2, "from": 6, "to": 4 },
  "credits": { "used": 0 },
  "meta": { "domain": "example.com", "returned": 2, "limit": 100 }
}

change appears when keyword is set and the series has at least two checks. A positive delta means the domain moved up. When one of the two checks found nothing, delta is null and event is entered or dropped_out. History holds only the checks you ran (batch rows and async rankings/check tasks included). It is not a back-filled index, and it is kept for a configurable retention period.

Answers from AI assistants and the sources they cited: ChatGPT, Microsoft Copilot and Google Gemini. Perplexity answers are paused: GET /search/ai/perplexity answers 403 FEATURE_NOT_AVAILABLE and is not charged. Each answer is generated live for your prompt, with no account history shaping it: the answer the engine's own users see.

Searlo is independent and not affiliated with OpenAI, Microsoft, Google or Perplexity.

Endpoint

GET /search/ai/{engine}

> engine is one of chatgpt, copilot or gemini; GET /search/ai?engine=chatgpt is the same route, and GET /search/ai without an engine asks ChatGPT. perplexity (paused), aimode (Google AI Mode) and grok are switched off in production: they answer 403 FEATURE_NOT_AVAILABLE and are not charged.

Credits: per answer: Gemini 4, ChatGPT 8, Copilot 8. A cached answer is billed at the full rate.

Parameters

Structured output (schema) is not available on this endpoint yet. Do not send it: a JSON value is rejected with 400, and a bracketed schema[field]=type is dropped.

These engines take no location beyond gl: location and uule are ignored.

Response

{
  "success": true,
  "searchParameters": { "q": "best crm for startups", "type": "ai", "engine": "chatgpt", "mode": "ui", "gl": "us", "hl": "en" },
  "answer": "For most early-stage startups, a free tier is enough to begin with...",
  "answerMarkdown": "For most early-stage startups, a **free tier** is enough to begin with...",
  "citations": [
    { "index": 1, "url": "https://www.example.com/best-crm-startups", "title": "The best CRMs for startups", "domain": "example.com" },
    { "index": 2, "url": "https://blog.example.org/crm-guide", "title": "Choosing a CRM", "domain": "blog.example.org" }
  ],
  "sources": ["example.com", "blog.example.org"],
  "citationPills": [],
  "related": ["Which CRM is free for small teams?"],
  "model": "",
  "threadUrl": null,
  "complete": true,
  "via": "dom",
  "fetchedAt": "2026-09-29T10:00:00.000Z",
  "source": "searlo.tech(chatgpt)",
  "cached": false
}

Responses also set X-AI-Engine.

Latency, Caching and Variance

• •A live answer typically takes 10–30 seconds. Set a generous client timeout.
• •Answers are non-deterministic: the same prompt can return different text and different citations from one run to the next. That variance is part of what you are measuring.
• •A repeat of the same prompt (ignoring case and extra spaces) on the same engine, with the same gl, hl and mode, within about an hour is served from cache and billed at the full rate. Pass cache=false to force a new run.
• •Identical requests in flight at the same moment, cache=false ones included, are merged into one run: every call is billed and all of them get the same answer. Parallel identical calls are not independent samples, so space your samples out.
• •ChatGPT and Gemini show sources only when they searched the web, so citations can be empty on a valid answer.
• •html=true always runs the engine (a snapshot is never cached), and a snapshot request is merged only with identical snapshot requests in flight.

Errors

Failed calls are refunded.

The retrieval half of the API: read a page, list a site's URLs, crawl a site, or pull structured records out of pages. Pages that render client-side are rendered automatically. That automatic rendering is for accounts that have bought credits; on sign-up credits alone, pass render: true to render a page.

Endpoints

POST   /scrape
POST   /scrape/batch
POST   /map
POST   /crawl
GET    /crawl
GET    /crawl/{jobId}
GET    /crawl/{jobId}/results
DELETE /crawl/{jobId}
POST   /extract
POST   /search-and-scrape
GET    /search/webpage

Credits:

From 2026-11-01: pages that needed a browser cost 5. On every row above except /map, a page that had to be rendered costs 4 credits more than the table says: 5 instead of 1 per page. That covers render: true, actions, and automatic rendering when a plain fetch returns no usable content, such as a JavaScript-only page. The page's via says which it was: browser or http. A cached copy costs the same as the page it copies; a failed fetch is never charged; the live-fetch surcharge is added on top, not multiplied (a forced live fetch that needed a browser is 2 + 4 = 6). render: false keeps every page at the plain price. Until 2026-11-01 a browser page costs the same as any other.

Freshness and the Live-Fetch Surcharge

/scrape, /map and /search-and-scrape keep a cache, controlled by two fields:

• •Omit both, and any cached copy is used. The call costs 1 whether or not it was cached (from 2026-11-01, 5 for a page that needed a browser, cached or not).
• •maxAge (seconds, 0–2592000): use a cached copy only if it is at most this old.
• •cache: false is the same as maxAge: 0: always fetch live.

When your maxAge or cache: false makes Searlo fetch the page live, the call costs 2 and the response carries X-Cache-Bypass: CHARGED. If a cached copy satisfied your maxAge, it costs 1. X-Credits-Deducted always shows the total, and a cached answer carries _cacheAgeSec.

URLs

Every url and urls field takes an http or https URL of up to 2,048 characters. An internationalised domain name works as you write it on scrape, map, crawl, scrape/batch and extract: https://www.löschwagen.com/preise is fetched, cached and billed under its encoded form, https://www.xn--lschwagen-07a.com/preise, and so is a path in any script. (GET /search/webpage takes the encoded xn-- form only.)

A URL that cannot be fetched as written is a 400 VALIDATION_ERROR (url must be an http(s) URL), answered before anything is fetched and never charged: a control character or a space anywhere in it, an escaped one in the host (%00), a scheme other than http or https, or a URL that cannot be parsed. A private or reserved address is 422 TARGET_NOT_ALLOWED.

Scrape

POST /scrape

{
  "searchParameters": { "url": "https://example.com/pricing", "type": "scrape", "formats": ["markdown", "links"] },
  "url": "https://example.com/pricing",
  "requestedUrl": "https://example.com/pricing",
  "statusCode": 200,
  "via": "http",
  "bytes": 48213,
  "markdown": "# Pricing\n\nStart free, then pay as you go...",
  "metadata": {
    "title": "Pricing | Example",
    "description": "Plans and prices.",
    "author": null,
    "publishedDate": null,
    "language": "en",
    "canonicalUrl": "https://example.com/pricing",
    "robots": null,
    "wordCount": 812,
    "openGraph": { "title": "Pricing", "image": "https://example.com/og.png" },
    "twitter": null
  },
  "links": [{ "url": "https://example.com/signup", "text": "Sign up", "internal": true }],
  "source": "searlo.tech(scrape)",
  "credits": 1
}

url is the final URL after redirects and requestedUrl is what you sent. via is http or browser (serp for a Google results page). A page that comes back empty is returned but not cached.

Map

POST /map

Every URL a site publishes, before you pay to crawl it: robots.txt, then its sitemaps (sitemap indexes included), then the homepage's links when there is no sitemap.

{
  "searchParameters": { "url": "https://example.com", "type": "map", "limit": 1000 },
  "origin": "https://example.com",
  "discovery": "sitemap",
  "sitemaps": ["https://example.com/sitemap.xml"],
  "robots": { "present": true, "sitemapCount": 1 },
  "totalResults": 214,
  "urls": [
    { "url": "https://example.com/pricing", "lastModified": "2026-09-01" },
    { "url": "https://example.com/blog/launch", "lastModified": null }
  ],
  "source": "searlo.tech(map)",
  "credits": 1
}

discovery is sitemap, links (homepage links, when the site publishes no sitemap) or none.

Crawl

POST /crawl

Queue a crawl of one site and get a job id back at once. Starting needs a minimum balance (configurable); after that, credits are charged per page as the crawl runs, so a job with limit: 500 on a twelve-page site costs 12 (from 2026-11-01, plus 4 for each of those pages that needed a browser). robots.txt is obeyed by default.

The snake_case spellings (max_depth, include_paths, exclude_paths, allow_subdomains, allow_external, respect_robots, use_sitemap, only_main_content, store_content) are accepted too.

{
  "success": true,
  "jobId": "crawl_0123456789abcdef01234567",
  "status": "queued",
  "url": "https://example.com/docs",
  "options": { "maxDepth": 2, "limit": 50, "includePaths": ["/docs/*"], "excludePaths": [], "formats": ["markdown"], "allowSubdomains": false, "allowExternal": false, "respectRobots": true, "concurrency": 3, "render": null, "onlyMainContent": true, "useSitemap": true, "storeContent": true },
  "maxCredits": 50,
  "statusUrl": "/api/v1/crawl/crawl_0123456789abcdef01234567",
  "resultsUrl": "/api/v1/crawl/crawl_0123456789abcdef01234567/results",
  "createdAt": "2026-09-29T10:00:00.000Z"
}

The response is 202. maxCredits is a ceiling, not a quote; from 2026-11-01 it allows 5 per page unless the job sets render: false.

Batch Scrape

POST /scrape/batch

Up to 1000 URLs as one job, with no discovery: the job fetches exactly the URLs you send. They are normalised and de-duplicated first, so compare submitted with urlCount. Like a crawl, it needs a minimum balance to start and then bills 1 credit per page fetched (from 2026-11-01, 5 for a page that needed a browser). Status, results, cancellation and webhooks use the crawl endpoints below.

maxAge, cache, includeLinks and excludeSelectors are accepted on a batch but have no effect: every page is fetched live, at 1 credit (5 from 2026-11-01 if it needed a browser).

The 202 response has the crawl shape plus mode: "batch", urlCount (what was queued) and submitted (what you sent).

Job Status and Results

GET /crawl/{jobId}
GET /crawl/{jobId}/results
GET /crawl
DELETE /crawl/{jobId}

All free, for crawls and batches alike.

{
  "success": true,
  "jobId": "crawl_0123456789abcdef01234567",
  "status": "completed",
  "url": "https://example.com/docs",
  "options": { "maxDepth": 2, "limit": 50, "includePaths": ["/docs/*"], "excludePaths": [], "formats": ["markdown"], "allowSubdomains": false, "allowExternal": false, "respectRobots": true, "concurrency": 3, "render": null, "onlyMainContent": true, "useSitemap": true, "storeContent": true },
  "progress": { "discovered": 64, "completed": 50, "failed": 2, "skipped": 3 },
  "creditsCharged": 50,
  "stopReason": "page limit reached",
  "webhook": { "url": "https://example.com/hooks/crawl", "deliveredAt": "2026-09-29T10:04:10.000Z", "attempts": 1 },
  "createdAt": "2026-09-29T10:00:00.000Z",
  "startedAt": "2026-09-29T10:00:02.000Z",
  "finishedAt": "2026-09-29T10:04:09.000Z"
}

status is queued, running, completed, failed or cancelled. stopReason says how a job ended: page limit reached, all urls processed (a batch), credit balance exhausted, job deadline reached (jobs run for a configurable maximum time) or cancelled by caller. A job that runs out of credits keeps the pages it already fetched.

GET /crawl/{jobId}/results pages through what was fetched:

{
  "success": true,
  "jobId": "crawl_0123456789abcdef01234567",
  "status": "completed",
  "totalResults": 50,
  "hasMore": false,
  "nextCursor": null,
  "pages": [
    {
      "url": "https://example.com/docs/intro",
      "finalUrl": null,
      "depth": 1,
      "parentUrl": "https://example.com/docs",
      "status": "completed",
      "statusCode": 200,
      "via": "http",
      "title": "Introduction",
      "description": "Get started with Example.",
      "language": "en",
      "canonicalUrl": "https://example.com/docs/intro",
      "wordCount": 640,
      "markdown": "# Introduction\n...",
      "fetchedAt": "2026-09-29T10:00:05.000Z"
    }
  ]
}

totalResults counts the pages in this response, not the whole job. Skipped pages carry a reason (e.g. disallowed by robots.txt) and failed ones an error. GET /crawl lists your jobs, newest first (limit 1–100, default 20; optional status). DELETE /crawl/{jobId} stops a job; pages already fetched stay billed and readable. Jobs and their pages are kept for a configurable retention period.

Job Webhooks

When a crawl or batch ends, Searlo POSTs once to webhook.url:

{
  "jobId": "crawl_0123456789abcdef01234567",
  "event": "crawl.completed",
  "status": "completed",
  "url": "https://example.com/docs",
  "stopReason": "page limit reached",
  "progress": { "discovered": 64, "completed": 50, "failed": 2, "skipped": 3 },
  "creditsCharged": 50,
  "resultsUrl": "https://api.searlo.tech/api/v1/crawl/crawl_0123456789abcdef01234567/results",
  "startedAt": "2026-09-29T10:00:02.000Z",
  "finishedAt": "2026-09-29T10:04:09.000Z"
}

Headers: X-Searlo-Job-Id, X-Searlo-Timestamp, X-Searlo-Event and, when you set a secret, X-Searlo-Signature, signed the same way as Async Tasks webhooks. The URL must be HTTPS and publicly reachable. A job webhook is attempted once and not retried: webhook.attempts and webhook.deliveredAt on the job show whether it landed.

Extract

POST /extract

URLs plus a field schema in, one record per URL out. The URLs are fetched several at a time inside one overall time budget (75 seconds by default), so a long list takes about as long as its slowest pages, not the sum of them. Pages that arrive in time are served and billed; the rest come back as rows that say why.

Values come first from what the page declares (schema.org JSON-LD, then Open Graph and meta tags), then from unambiguous patterns in the text (prices, currencies, emails, phone numbers), then from the model if it is enabled. That first pass recognises common field names (name, description, price, currency, rating, reviews, image, sku, brand, author, datePublished, availability, url, email, phone, address and their usual aliases); other names are filled only by the model. A field nothing can fill comes back null and is listed in missingFields: it is not guessed. Your balance must cover one credit per URL before the call starts (402 otherwise). Billing is one credit per page actually fetched, or from 2026-11-01, 5 for a row whose via is browser: a row that failed, timed out or was never reached is free.

{
  "searchParameters": { "type": "extract", "urls": 3, "fields": ["name", "price", "currency", "availability"] },
  "mode": "structured+llm",
  "llmAvailable": true,
  "totalResults": 3,
  "partial": true,
  "data": [
    {
      "url": "https://shop.example.com/p/widget",
      "success": true,
      "data": { "name": "Widget Pro", "price": 49.99, "currency": "USD", "availability": null },
      "_sources": { "name": "json-ld", "price": "json-ld", "currency": "json-ld" },
      "missingFields": ["availability"],
      "via": "http",
      "llmUsed": false,
      "llmSkipped": "time budget"
    },
    {
      "url": "https://shop.example.org/p/gadget",
      "success": false,
      "data": null,
      "errorCode": "TARGET_REFUSED",
      "error": "target site refused the request (HTTP 403)",
      "retryable": false,
      "targetStatus": 403
    },
    {
      "url": "https://slow.example.net/p/thing",
      "success": false,
      "data": null,
      "errorCode": "NOT_FETCHED",
      "error": "not fetched: the request's time budget ran out before this URL's turn",
      "retryable": true
    }
  ],
  "source": "searlo.tech(extract)",
  "credits": 1
}

_sources gives each filled field's origin: json-ld, meta, text or llm. credits is the number of pages fetched. Every row has url, success and data; the rest depends on the row:

A private or reserved address among the urls fails the whole call with 422 TARGET_NOT_ALLOWED before anything is fetched.

Search and Scrape

POST /search-and-scrape

A web search, then the result pages scraped, in one call.

{
  "searchParameters": { "q": "vector database benchmarks", "type": "search-and-scrape", "limit": 3, "scrape": true },
  "totalResults": 3,
  "scrapedCount": 2,
  "results": [
    {
      "position": 1,
      "title": "Vector database benchmarks, 2026",
      "link": "https://www.example.com/benchmarks",
      "snippet": "We ran each database on the same hardware...",
      "domain": "example.com",
      "scraped": true,
      "via": "http",
      "statusCode": 200,
      "metadata": { "title": "Vector database benchmarks, 2026", "language": "en", "wordCount": 2310 },
      "markdown": "# Vector database benchmarks, 2026\n..."
    },
    { "position": 3, "title": "Benchmark notes", "link": "https://unreachable.example.net/post", "snippet": "...", "domain": "unreachable.example.net", "scraped": false, "error": "scrape failed" }
  ],
  "source": "searlo.tech(search-and-scrape)",
  "credits": 3
}

Each row is a web search result (position, title, link, snippet, domain, …) with its page attached. A page that could not be scraped comes back with scraped: false and an error, and is not billed.

Webpage Fetch (GET or POST)

GET /search/webpage reads one page from a query string, for clients that can only send GET: one URL, one format, the page's metadata. POST /search/webpage takes the same fields as a JSON body, plus excludeSelectors (up to 20 CSS selectors to remove before extraction). 1 credit; from 2026-11-01, 5 when the page needed a browser (via: "browser"). A repeat call can be answered from cache (X-Cache: HIT) and is billed the same; to control freshness, use POST /scrape with maxAge.

{
  "searchParameters": { "url": "https://example.com/blog/benchmarks", "type": "webpage", "format": "markdown" },
  "url": "https://example.com/blog/benchmarks",
  "requestedUrl": "https://example.com/blog/benchmarks",
  "domain": "example.com",
  "statusCode": 200,
  "via": "http",
  "bytes": 48213,
  "title": "Vector database benchmarks, 2026",
  "description": "We ran each database on the same hardware...",
  "author": null,
  "publishedDate": "2026-03-02",
  "openGraph": { "title": "Vector database benchmarks, 2026", "image": "https://example.com/og.png" },
  "wordCount": 2310,
  "content": "# Vector database benchmarks, 2026\n...",
  "source": "searlo.tech(webpage)",
  "credits": 1
}

url is where the page ended up after redirects; requestedUrl is what you sent. via is http for a plain fetch and browser for a rendered one.

A site that refuses the fetch is 422 TARGET_REFUSED (targetStatus is the site's own status), a private or reserved address is 422 TARGET_NOT_ALLOWED, and a site no attempt could fetch is 422 TARGET_UNREACHABLE, as on POST /scrape. None is charged.

Queue a request, get a task id back at once, and collect the result later by polling or by webhook. The task runs the same service the synchronous route uses.

Endpoints

POST   /async/task
POST   /async/task/batch
GET    /async/task/{taskId}
GET    /async/status
DELETE /async/queue

Credits: the endpoint's price, deducted when the task is queued. Kept when the task completes; refunded when it fails or is cancelled. Reading tasks and status is free.

Request

The field is endpoint, not type, and the webhook is webhook: { url, secret }, not webhookUrl. Unknown top-level fields are stripped without an error: a request that sends webhookUrl is queued with no webhook, and one that sends type instead of endpoint is rejected with 400.

The validator also accepts keywords/…, domain/…, ai/aimode and ai/grok; those endpoints are switched off in production, so do not queue them.

Response

POST /async/task answers 202 with the queued task:

{
  "success": true,
  "duplicate": false,
  "task": {
    "taskId": "5f0c2b1e-7a3d-4c1b-9d0e-2a6f8b9c1d3e",
    "endpoint": "serp",
    "status": "QUEUED",
    "priority": 50,
    "attempts": 0,
    "creditsHeld": 6,
    "creditsUsed": 0,
    "creditsRefunded": false,
    "request": { "q": "best running shoes", "gl": "us", "pages": 2 },
    "webhook": { "url": "https://example.com/hooks/searlo", "attempts": 0, "lastStatus": null, "deliveredAt": null },
    "queuedAt": "2026-09-29T10:00:00.000Z",
    "startedAt": null,
    "completedAt": null,
    "durationMs": null,
    "expiresAt": "2026-10-06T10:00:00.000Z"
  }
}

GET /async/task/{taskId} returns { "success": true, "task": { … } } in the same shape, or 404 for an unknown id. status is QUEUED, PROCESSING, COMPLETED, FAILED or CANCELLED.

• •result appears once the task is COMPLETED. For serp, news/serp and ai/… it is the body the synchronous route returns; for rankings/check it is the check's result object with success: true.
• •error (code, message, retryable) appears when the task is FAILED.
• •A retryable failure (capacity, an unusable upstream page) is queued again after a delay, the engine's Retry-After when it gave one, up to a configurable number of attempts. After that, or on a non-retryable error, the task is FAILED and its credits are refunded (creditsRefunded: true). Errors in the request itself (VALIDATION_ERROR, CITY_LOCATION_UNAVAILABLE, UNKNOWN_LOCATION, INVALID_DOMAIN, a query shape Google refuses on sight) fail at once, without retries.
• •A result larger than a configurable size has its bulkiest top-level fields removed, listed in result._trimmed.
• •Tasks are deleted after a configurable retention period; expiresAt says when.

Batch

POST /async/task/batch takes { "tasks": [ … ] } with 1–500 task objects, each shaped like a single request. Each task is charged when it is queued. The response is 202 when at least one task was accepted, 400 otherwise:

{
  "success": true,
  "accepted": 2,
  "total": 3,
  "tasks": [
    { "accepted": true, "duplicate": false, "taskId": "5f0c2b1e-7a3d-4c1b-9d0e-2a6f8b9c1d3e", "status": "QUEUED", "creditsHeld": 8 },
    { "accepted": true, "duplicate": false, "taskId": "9b1d7e0a-2c4f-4e8b-a6d3-1f2e3d4c5b6a", "status": "QUEUED", "creditsHeld": 2 },
    { "accepted": false, "error": "request.q is required", "endpoint": "ai/copilot" }
  ]
}

If your credits run out part-way, the batch stops there: the remaining tasks are not queued and do not appear in tasks, so compare tasks.length with total. A task that fails validation (an unknown endpoint, say) rejects the whole batch with 400.

Queue Status

GET /async/status returns your queue: queued, processing, priorityBreakdown ([{ "priority": 50, "count": 12 }]), last24h (completed, failed) and worker (the answering process's inflight and concurrency per lane). DELETE /async/queue cancels every task still QUEUED and refunds it: { "success": true, "cleared": 12, "creditsRefunded": 36 }.

Webhooks

When a task ends as COMPLETED or FAILED (not when it is queued again for a retry), Searlo POSTs to webhook.url:

{
  "taskId": "5f0c2b1e-7a3d-4c1b-9d0e-2a6f8b9c1d3e",
  "endpoint": "serp",
  "status": "COMPLETED",
  "result": { "success": true, "organic": [], "peopleAlsoAsk": [] },
  "creditsUsed": 6,
  "completedAt": "2026-09-29T10:01:12.000Z"
}

A failed task sends error instead of result. Headers:

• •X-Searlo-Task-Id, and X-Searlo-Event (task.completed or task.failed)
• •X-Searlo-Timestamp: milliseconds since the epoch
• •X-Searlo-Signature (when you set a secret): v1= followed by the hex HMAC-SHA256, keyed with your secret, of <timestamp>.<raw body>

Any 2xx counts as delivered; redirects are not followed. A failed delivery (another status, or no answer within a configurable timeout) is retried after 5 minutes, 30 minutes, 2 hours and 12 hours, then given up. The URL must be HTTPS and resolve to a public address; it is checked when you queue the task and again before each delivery.

Retrieve analytics about your own search usage. Free (0 credits).

Endpoint

GET /search/analytics

Parameters

Response

{
  "success": true,
  "data": {
    "totalSearches": 1284,
    "searchesByType": { "web": 900, "image": 200, "news": 184 },
    "recentSearches": [ { "query": "...", "searchType": "web", "createdAt": "..." } ],
    "popularQueries": [ { "query": "react", "count": 42 } ],
    "creditsUsed": 1284,
    "averageResponseTime": 412
  },
  "message": "Analytics retrieved successfully"
}

Validate an email address's deliverability.

Verify Endpoint

POST /email-verifier/verify

Credits: 5 per request. Rate-limited by the separate email_verifier tier group (see Rate Limiting). Verification is also paced: when it is busy the call answers 429 VERIFIER_BUSY with a Retry-After (30 seconds by default), and is not charged.

Body

Response

Responses use the standard envelope (statusCode, success, message, data).

{
  "statusCode": 200,
  "success": true,
  "message": "Email verified",
  "data": {
    "email": "[email protected]",
    "status": "valid",
    "domain": "example.com",
    "message": "Mailbox exists",
    "details": {
      "format": true,
      "mailboxStatus": "...",
      "mailboxType": "...",
      "mailboxExchange": "..."
    },
    "verifiedAt": "2026-05-20T10:30:00.000Z",
    "source": "searlo"
  }
}

status is one of: valid, invalid, accept_all, unknown, error.

History Endpoint

GET /email-verifier/history

Credits: Free (0). Returns your past verifications, paginated.

Your balance, and what this API serves right now. All free (0 credits); each needs your API key, like every other call.

Endpoints

GET /credits/balance
GET /credit/balance
GET /search/capabilities
GET /search/countries
GET /search/states

Credit Balance

GET /credits/balance returns the credits available to your account, and nothing else about it. It works with an API key (x-api-key, or Authorization: Bearer sk_...) and with a dashboard login. It is free, and like any call it counts against your request limits.

{
  "success": true,
  "credits": {
    "available": 2500,
    "reserved": 6,
    "expiresAt": "2027-09-01T10:00:00.000Z",
    "expiringCredits": 2500
  }
}

The answer is never cached (Cache-Control: no-store).

GET /credit/balance is the fuller view: the same balance with a low-balance flag and the expiry of each grant.

{
  "statusCode": 200,
  "data": {
    "balance": 2500,
    "available": 2500,
    "isLowBalance": false,
    "lastUpdated": "2026-09-29T08:12:03.000Z",
    "expiry": {
      "policyApplies": true,
      "durationDays": 365,
      "totalExpiringAmount": 2500,
      "nonExpiringAmount": 0,
      "nextExpiryAt": "2027-09-01T10:00:00.000Z",
      "daysUntilNextExpiry": 336,
      "nextExpiryAmount": 2500,
      "breakdown": [
        { "sourceType": "purchase", "amount": 2500, "grantedAt": "2026-09-01T10:00:00.000Z", "expiresAt": "2027-09-01T10:00:00.000Z", "daysRemaining": 336, "status": "active" }
      ]
    }
  },
  "message": "Credit balance retrieved successfully",
  "success": true
}

Every metered response also carries X-Credits-Deducted and X-Credits-Remaining, so a client rarely needs to poll this.

Capabilities

GET /search/capabilities lists every endpoint this deployment serves, what it costs, whether it is switched on, and how it has done over the last two hours. Read it instead of hard-coding which endpoints are available: a switched-off endpoint answers 403 FEATURE_NOT_AVAILABLE (not charged), and this tells you before you pay the round trip.

{
  "success": true,
  "generatedAt": "2026-09-29T17:20:00.000Z",
  "capabilities": [
    {
      "id": "serp/html",
      "method": "GET",
      "path": "/serp/html",
      "credits": 2,
      "creditsNote": "per page; 8 with js=true (rendered, AI Overview opened out)",
      "group": "google",
      "enabled": true,
      "state": "live",
      "health": { "window": "2h", "ok": 412, "fail": 6, "successRate": 0.99 }
    },
    {
      "id": "backlinks",
      "method": "GET",
      "path": "/backlinks",
      "credits": 0,
      "group": "backlinks",
      "enabled": false,
      "reason": "No backlink provider is bound to this deployment. The endpoints answer 501 rather than returning synthesised link data.",
      "state": "off",
      "health": { "window": "2h", "ok": 0, "fail": 0, "successRate": null }
    }
  ],
  "states": { "live": "serving", "degraded": "on, but most recent calls failed", "off": "switched off here" }
}

state is off when the endpoint is switched off (reason says why), degraded when at least 3 calls in the window and fewer than half of them succeeded, and live otherwise. successRate is a fraction (0–1), null with no calls in the window. The response may be cached for 30 seconds.

Countries and States

GET /search/countries lists the countries the AI answer endpoints accept as gl. The search endpoints accept any two-letter gl, applied as the results country.

{
  "success": true,
  "engine": "all",
  "countries": [
    { "code": "US", "name": "United States", "states": true, "exit": true },
    { "code": "GB", "name": "United Kingdom", "states": false, "exit": true }
  ]
}

GET /search/states lists the US states with Google's name and uule token for each. State- and city-level location is not available yet (Location): the response says targeting: false, and a state passed as location or uule returns 400 CITY_LOCATION_UNAVAILABLE. Only country=US is available; any other country returns 400.

{
  "success": true,
  "country": "US",
  "exitPinning": false,
  "targeting": false,
  "message": "State- and city-level location is not available yet: a state passed as location returns 400 CITY_LOCATION_UNAVAILABLE. Country (gl) and language (hl) are applied.",
  "states": [
    { "code": "TX", "name": "Texas", "location": "Texas,United States", "uule": "w+CAIQICIT..." }
  ]
}

exitPinning: false: results are not localized to the state.

API requests are rate-limited per user with sliding windows. Every account gets the same limits, free credits included: buying credits does not change them.

Limits are tracked per endpoint group, and each group has its own buckets:

local is a tighter cap inside the search budget: a maps, places, reviews or place-details call must pass both. API-key and dashboard requests share one bucket per user. On top of the windows, an account can have at most 64 web, image, site, advanced and batch searches in flight at once (see Searches in Flight).

Per API Key

Each API key also has its own caps, inside the account's budget: 20,000 requests a minute and 400,000 a day by default for a new key. The dashboard shows each key's caps. They are fixed windows that start with the key's first request in each window. An account can hold several keys, and all of them draw on the account's limits above.

High-volume accounts get custom limits for the account and for each key, and reserved capacity on the SERP hosts: ask support with your expected daily volume and peak rate.

Searches in Flight

Web, image, site, advanced and batch search (and the GET /search alias) also cap how many of an account's requests may run at once. Past the cap a request is refused at once with 429, code 4203 and errorCode CONCURRENCY_LIMIT, a Retry-After of 1 second and an X-Concurrency-Limit header that carries the cap: 64 in flight per account, on every plan. It is refused before any credit is reserved, so it is never charged. A slot frees as soon as a response finishes: retry after the second.

{
  "success": false,
  "message": "Too many searches in flight for this account (at most 64 at once). Retry in 1s.",
  "code": 4203,
  "errorCode": "CONCURRENCY_LIMIT",
  "retryable": true,
  "retryAfter": 1,
  "limit": 64
}

Rate Limit Headers

Every rate-limited response carries the state of each window, and the Unix time (seconds) at which the earliest one resets:

X-RateLimit-Limit-Second: 600
X-RateLimit-Remaining-Second: 599
X-RateLimit-Limit-Minute: 20000
X-RateLimit-Remaining-Minute: 19987
X-RateLimit-Limit-Hour: 400000
X-RateLimit-Remaining-Hour: 399421
X-RateLimit-Limit-Day: 1800000
X-RateLimit-Remaining-Day: 1771305
X-RateLimit-Reset: 1790690460

Handling Rate Limits

A 429 Too Many Requests from the account limits has code: 4201:

{
  "success": false,
  "message": "Rate limit exceeded. Please slow down and try again later.",
  "code": 4201,
  "retryAfter": 60,
  "limits": { "perSecond": { "limit": 600, "remaining": 0, "resetAt": 1790690000 } }
}

Wait retryAfter seconds (the same value is in the Retry-After header) before retrying. limits shows each window's state; the example is trimmed. A key's own cap answers the same way with code: 4202 and "message": "API key rate limit exceeded.". The in-flight cap answers code: 4203 (above).

A 429 can also mean a lane is full rather than a limit reached: AT_CAPACITY (Full SERP, AI answers, shopping), BUSY (SERP HTML) and VERIFIER_BUSY (e-mail verifier) carry a Retry-After too, and are not charged. See Error Handling.

Every error answers JSON with success: false and a human-readable message, and almost every one adds a stable machine-readable name for the failure. Branch on that name and the status, not on message, which may be reworded. The name is in code; on a few errors, marked † below, it is in errorCode instead, so read code and fall back to errorCode.

Error Response Format

{
  "success": false,
  "code": "AT_CAPACITY",
  "message": "Google SERP is at capacity. Retry in 60s — immediate retries will be refused.",
  "retryable": true,
  "retryAfterSec": 60
}

• •retryable says whether the same request can succeed later. When it is true, wait Retry-After (header) or retryAfterSec (body) before retrying.
• •Validation errors add an errors array of { field, message }:

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "Query validation failed: \"q\" is required",
  "errors": [{ "field": "q", "message": "\"q\" is required" }]
}

• •Insufficient-credit errors (402) add details:

{
  "success": false,
  "error": "Insufficient credits",
  "code": "INSUFFICIENT_CREDITS",
  "details": { "required": 5, "available": 2, "shortfall": 3 },
  "message": "This request requires 5 credit(s), but you only have 2 credit(s) available. Please purchase more credits to continue.",
  "topUpUrl": "https://dashboard.searlo.tech/credits?tab=buy&source=api_402"
}

Codes

Every status and code the API answers, in one table. A call that answers with one of them is never charged: it releases the credits it held, and the 429s for rate limits and searches in flight are refused before any credit is reserved. A 200 that finds nothing (an empty list) is not charged either. The one exception is a failed row inside a 200 POST /rankings/batch, which is billed with the batch (see Refunds). † marks a name carried in errorCode.

The rate-limit 429s carry a numeric code (4201, 4202, 4203); every other code is a string. Errors are JSON on every status, a 5xx included: we answer 503 rather than 502 or 504, which the network in front of us would replace with its own HTML page. Every retryable 503 carries Retry-After.

Idempotency keys

Send X-Idempotency-Key (or Idempotency-Key), up to 255 characters, to make a retry of a paid call safe. Within an hour of the first use:

• •the same key with the same request returns the stored response, marked Idempotent-Replayed: true, without running or charging again;
• •the same key with a different request is 422 IDEMPOTENCY_KEY_REUSED, not charged;
• •the same key while the first request is still running is 409 IDEMPOTENCY_REQUEST_IN_PROGRESS: retry shortly (Retry-After: 2).

A request that failed is not kept, so you can retry it with the same key. A key longer than 255 characters is 400 INVALID_IDEMPOTENCY_KEY. Async tasks take their own idempotencyKey in the body (Async Tasks).

Refunds

A call that fails is not charged: any response with status 400 or above, or with success: false, releases the credits it reserved. An answer with no results (an empty organic, news, videos, images, places, reviews or shopping list) is not charged either, and the body's credits always equals the X-Credits-Deducted header. In POST /search/batch and POST /serp/batch a failed or empty row costs nothing; a row inside a 200 POST /rankings/batch is billed like the rest of that batch (read each row's success and retryable). A failed async task is refunded.

Retrying

Retry only what says it can succeed later: 429s, and 5xx responses with retryable: true. Wait Retry-After when it is present, and back off otherwise (for example 2, 5, then 10 seconds). Because failures are refunded, a retry never bills twice.

Connect AI agents like Claude, Cursor, VS Code Copilot, and Windsurf to Searlo via Model Context Protocol (MCP).

Endpoint

https://api.searlo.tech/api/v1/mcp

Transport

Streamable HTTP — the latest MCP specification. No stdio, no Docker, no local bridge needed.

Authentication

Use your API key in the X-API-Key header. The same key works for both MCP and the REST API.

Server Info

GET /mcp/info (no key needed) returns the server's name, version and transport, and the tools it exposes with their credit costs. Read it rather than hard-coding the list below.

Available Tools

A failed tool call is not charged. toon output (the default on the search tools) is a compact tabular format that takes about 63% fewer tokens than the same results as JSON.

Tool Parameters

• •web_search: query (required, 1–2048 chars), num (1–10, default 10), page (default 1), gl (2-letter country), lr (results language, e.g. en), safe (off, medium, high), format (toon, json or enhanced)
• •news_search: query (required), num (1–10), page (1–100), gl, hl, dateRestrict (d7 = last 7 days; also w, m, y), format (toon or json)
• •image_search: query (required), num (1–10), page (1–100), size (icon to huge), imgType (photo, clipart, lineart, face, stock, animated), imgColorType (color, gray, mono, trans), gl, hl, format
• •shopping_search: query (required, 1–500 chars), num (1–60, default 55), gl, hl, format
• •maps_search: query (required, 1–500 chars), num (1–20, default 20), page, gl, hl, ll (Google's @lat,lng,zoomz form, e.g. @30.27,-97.74,13z) or lat / lng / zoom (1–21), format
• •scholar_search: query (required, 1–500 chars), num (1–20, default 10), page, hl, yearFrom, yearTo, sortByDate, includePatents, includeCitations, cluster (all versions of a work), cites (works citing it), format
• •ai_answer: query (required, 1–500 chars), engine (chatgpt, the default, copilot or gemini; perplexity is paused, and aimode and grok are switched off), cache (default true)
• •scrape: url (required), formats (up to 8 of markdown, text, html, links, images, headings, tables, json_ld; default ["markdown"]), onlyMainContent (default true), render, includeLinks, includeImages, excludeSelectors (up to 20), waitForSelector, timeout (1000–60000 ms), cache (default true), maxChars (500–200000)
• •site_map: url (required), limit (1–5000, default 1000), search (keep URLs containing this), includeSubdomains, sitemapOnly, cache
• •search_and_scrape: query (required, 1–500 chars), limit (results to read, 1–20, default 5), scrape (false returns the search only, for 1 credit), formats (markdown, text, html, json_ld), onlyMainContent, render, gl, hl, cache, maxChars
• •get_usage_stats: days (1–365, default 30)
• •get_search_history: limit (1–10, default 10), page (default 1), searchType (web, image or news)
• •get_search_stats: startDate, endDate (ISO dates), groupBy (hour, day, week or month; default day)
• •get_transaction_history: limit (1–10, default 10), page (default 1), type (deduction, grant, refund or purchase)
• •check_balance, list_api_keys: no parameters

Quick Setup

Paste the config into your AI client's MCP settings file and replace sk_your_api_key with your key.

Changes to the API's behaviour and contract, newest first. Additive fields are listed too, so a strict client knows what to expect.

2026-10-20

• •Pricing may change during November–December 2026. What it costs us to serve some requests changes at the turn of the year, so we may adjust prices in those two months. Any change is announced in advance here and by email. Credits you have already bought keep working, and packs stay valid for 12 months from purchase.
• •Full SERP: rendered AI Overview costs 8 from 2026-11-01. GET /serp, GET /search/serp, POST /serp/batch and async serp tasks cost 3 credits per page as today, or 8 when the AI Overview had to be completed by rendering the page in a browser. The response says aioverview.rendered: true when that happened (live now, so you can see which of your calls it affects). A page whose overview arrives complete, or a request with aioverview=false, stays 3. GET /serp/features stays 3 and never renders; GET /serp/html stays 2 (8 with js=true).
• •Web data: a page that needed a browser costs 5 from 2026-11-01. On POST /scrape, GET|POST /search/webpage, POST /extract, POST /search-and-scrape, POST /crawl and POST /scrape/batch, a page that had to be rendered (render: true, actions, or automatic rendering when a plain fetch returns no usable content, such as a JavaScript-only page) costs 5 credits instead of 1. Pages fetched without a browser stay 1. Responses already say via: "browser" or via: "http". A cached copy costs the same as the page it copies, a failed fetch is never charged, and the live-fetch surcharge (maxAge or cache: false) still applies on top. A crawl's maxCredits ceiling allows for the browser price unless the job sets render: false. POST /map is unchanged.
• •Accounts that have never bought credits. Every endpoint works on the sign-up credits, but the automatic browser fallback is off (an explicit render: true or actions still renders) and a web search that comes back thin is not topped up with live results. Both switch on with the first purchase. In effect now.

2026-10-15

• •Place details menus from Google Search. Google Maps now shows signed-out visitors a reduced place record without the menu, so menu came back null. For a place that serves food, GET /search/place-details reads the menu (url, sections of items with prices) from the place's Google Search panel. Adds place.menuStatus (found, none, pending, unavailable) and the parameter menu=false to skip the lookup. menu.photos is empty for now. Same price.

2026-10-04 to 2026-10-05

• •Credit balance. GET /credits/balance returns { success, credits: { available, reserved?, expiresAt?, expiringCredits? } } for an API key or a dashboard login. Free. available is the balance GET /user/profile shows (Account & Utilities).
• •API keys. A key is for the data API and read-only views of its account. Creating or deleting keys, data export, account deletion and payments need a dashboard login (403 API_KEY_SCOPE_FORBIDDEN); GET /user/profile stays open to keys. Keys are stored hashed, and lists show a masked preview.
• •Errors. One table of every status and code (Error Handling). New: 400 PAGE_OUT_OF_RANGE, DATE_FILTER_UNAVAILABLE and INVALID_IDEMPOTENCY_KEY, 422 TARGET_UNREACHABLE, 429 4203 (CONCURRENCY_LIMIT), 503 CREDIT_SYSTEM_UNAVAILABLE and REVIEWS_WITHHELD. A switched-off endpoint answers 403 FEATURE_NOT_AVAILABLE (was 503); a site that refuses the fetch answers 422 TARGET_REFUSED (was 503). No 502 or 504 leaves the API: both are answered as 503 JSON. None of these is charged.
• •Idempotency keys are bound to the request they came with: the same key and request replays the stored response (Idempotent-Replayed: true, no charge), the same key with a different request is 422 IDEMPOTENCY_KEY_REUSED.
• •SafeSearch on the SERP. safe=active or off (and true or false) is accepted on GET /serp and GET /search/serp. POST /serp/batch and GET /serp/features honour safe, which they ignored before.
• •Date filter. dateRestrict (d7, w2, m1, y1) works on GET /search/web together with gl and hl, on GET /search/news and on GET /search/advanced. Combined with search operators it returns 400 DATE_FILTER_UNAVAILABLE, not charged.
• •Fresh answers. cache=false forces a fresh answer on web, image, news, maps and places search. Same credits.
• •Web search pages. A page that starts past result 101 returns 400 PAGE_OUT_OF_RANGE with maxPage at once, instead of a slow failure.
• •Image search. Results carry width, height, thumbnailUrl with its size, link and sourceUrl (the page the image is on), source, domain, format and imageId. size (also imgSize), imgType, imgColorType and imgDominantColor now take effect.
• •Maps, places and place details. New businessStatus (OPERATIONAL, CLOSED_TEMPORARILY, CLOSED_PERMANENTLY or null) and openNow. openState comes back in the language of hl. With no ll, gl sets where the search looks (51 countries). A lite answer is never cached.
• •Reviews. The first page of reviews (about eight) comes back in any language, with hasMore. New timestamp (Unix seconds); an owner's reply carries date and language. A place Google sent without its reviews answers 503 REVIEWS_WITHHELD, not charged.
• •Extract. URLs are fetched in parallel inside one time budget. A failed row carries errorCode and retryable; partial says the budget ran out before every URL was fetched; llmSkipped says the model was not asked. One credit per page fetched; failed rows are free.
• •Web data. scrape, map, crawl, scrape/batch and extract accept internationalised domain names (https://www.löschwagen.com). A malformed URL, or one with a control character, is a 400.
• •Searches in flight. An account can have a limited number of web, image, site, advanced and batch searches running at once; past it, 429 4203 (Rate Limiting).
• •No charge for nothing. An answer with no results is free on every endpoint, SERP pages are billed per page delivered, and a failed row inside a 200 POST /serp/batch costs nothing.

2026-10-02

• •Place details. GET /search/place-details returns one place's full record by placeId (ChIJ…), featureId, cid or q: every maps field plus all of Google's attributes and the menu (url, sections of items with prices, photos). 1 credit.
• •Attributes on maps and places. GET /search/maps and GET /search/places add attributes, Google's "About" list keyed by Google's own ids (attributes.payments.requires_cash_only).
• •Reviews by Place ID. GET /search/reviews accepts placeId.
• •Opening date on maps and places. GET /search/maps and GET /search/places add openingDate (2026-11-01) and openingDateText (Opens 1 Nov, in your hl) to a place listed before it opens; null otherwise. Same price.
• •SERP HTML price. GET /serp/html costs 2 credits per page (was 1), and 8 per page with js=true (was 4). Failed calls are still refunded.
• •Full SERP AI Overview from the served page. GET /serp reads the AI Overview in full from the page as Google served it, so most overviews no longer wait for a rendered page: about 2 s instead of 8-10 s. An overview Google loads after the page comes back as pending: true and is still read from the rendered page. Overview sources come back resolved (url the cited page, redirectUrl the /goto, resolved: true). Same price.

2026-09-30

• •Credits are valid for one year per grant (was 90 days) on accounts created after the policy launch; existing credits were moved to one year from when they were granted. GET /credit/balance reports expiry.durationDays: 365. Legacy accounts keep unlimited credits.
• •Google News results page from the live page. GET /search/news/serp (and the news/serp async task and the Cloro-compatible news monitor) is fetched live and parsed like Full SERP: about a second per page, cards with title, source, date, snippet, thumbnail and resolved article links.
• •Location. location takes a country by name or two-letter code on every Google endpoint and applies it as gl; a country's uule is applied the same way. City- and state-level location, and any other uule, return 400 CITY_LOCATION_UNAVAILABLE and are not charged: Google no longer localizes results by uule (Location). GET /serp/html accepts a country location. GET /search/states adds targeting: false.
• •Error codes. Error bodies carry a stable code on search, SERP, SERP HTML, AI answer, rank check and validation errors (Error Handling). Failed batch rows carry the same code.
• •Async tasks. Errors in the request itself (a location, a domain, a query shape) fail at once and are refunded, instead of being retried.
• •Full SERP. Each page is fetched live and parsed; the AI Overview is read in full from the rendered page, and aioverview.complete says whether it was. aiModeAvailable reports the page's AI Mode tab. A multi-page request with a failed page is no longer cached.
• •SERP HTML. aio.showAll (pressed, absent, complete, failed) and show-all in X-Searlo-Aio.
• •Web data. POST /search/webpage accepts excludeSelectors; a page whose plain fetch returns no usable content is rendered.

2026-09-29

• •SERP HTML (GET /serp/html): Google's results page as served (1 credit at launch; 2 since 2026-10-02) or rendered with the AI Overview opened out (js=true, 4 credits at launch; 8 since 2026-10-02), desktop or iOS, as JSON or format=raw.
• •AI answer snapshots: html=true on GET /search/ai/{engine} adds the answer page's HTML (html, pageUrl) at no extra charge.
• •Full SERP: rawHtml=true returns the page alongside the JSON (+1 credit).
• •Account & Utilities: GET /credit/balance, GET /search/capabilities, GET /search/countries, GET /search/states documented.
• •MCP: all 16 tools documented.