Python and Node.js SDKs

The official clients wrap the REST API with a typed method for every engine, bulk jobs, monitors, webhook verification, typed errors and automatic retries. They use the same API key and credits as raw HTTP calls, and failed calls are still free.

The PyPI and npm releases are rolling out now. If pip install gridlode or npm install gridlode can't find the package yet, call the REST API directly with the examples in the docs; every SDK method maps one-to-one to an endpoint.

Install

pip install gridlode

Create a key in the dashboard and set it as the GRIDLODE_API_KEY environment variable, or pass it to the client. See Authentication.

Quick start

from gridlode import Gridlode

client = Gridlode()  # reads GRIDLODE_API_KEY, or Gridlode(api_key="sk_live_...")

dns = client.domain.dns(domain="gridlode.com", types=["A", "MX"])
print(dns.data["records"])
print(dns.credits_charged, dns.balance)

page = client.url.markdown(url="https://example.com")
serp = client.serp.google(q="best crm for startups", gl="us")
places = client.places.google_maps(q="coffee", location="Austin, TX", limit=40)
reviews = client.reviews.trustpilot(domain="gridlode.com", limit=20)

# Any engine by slug or route, including engines newer than your SDK version
whois = client.run("domain.whois", domain="example.com", max_age=86400)

Every engine is a method named after its slug: domain.dns is client.domain.dns() and serp.bing is client.serp.bing(). Python uses snake_case method names and keyword arguments; Node.js uses camelCase method names and a parameters object. Parameter names are the same as in the API reference, and leaving one out uses the API default.

The namespaces are ai, apps, classifieds, code, contacts, domain, ecommerce, jobs, places, realestate, reviews, serp, social, travel, url and video. When a route starts differently from the slug, that prefix works too: client.search is client.serp (/v1/search/…), client.youtube is client.video and client.github is client.code.

Engines marked may be disabled are under legal review and off by default: calls fail with EngineDisabled, without charge, until the engine is enabled for your account. The AI engines (ai.extract, ai.review_insights) are billed by actual usage and never cost more than their max_credits parameter (150 by default).

Engine methods

The response

Engine methods return the standard response envelope. In Python it is a dict with shortcuts: res.data, res.request_id, res.credits_charged, res.balance, res.cached and res.parameters. In Node.js it is a typed object (EngineResponse<T>) where you read res.data, res.credits and res.cache directly.

Pass max_age (Python) or { maxAge } in the options argument (Node.js), in seconds, to accept a cached answer at a discount. See Credits and billing.

client.account()   # {"account_id": ..., "credits": {"available": 950.0, "held": 0.0}}
client.engines()   # every engine with route, credits, unit and params_schema

Bulk jobs

Run one engine over up to 10,000 inputs in the background. wait polls with a growing interval until the job is done, failed or cancelled; iter_results / iterResults yields one item per input with its params, status, data, error_code and credits_charged. See Bulk jobs and webhooks for limits and billing.

job = client.tasks.create(
    "domain.tech",
    inputs=["shopify.com", "wordpress.org", "vercel.com"],
    field="domain",
    name="Competitor stacks",
    webhook_url="https://example.com/hooks/gridlode",  # optional
)
secret = job.get("webhook_secret")  # returned once; store it

task = client.tasks.wait(job, timeout=900)  # polls with backoff until done, failed or cancelled
for item in client.tasks.iter_results(task):
    if item["status"] == "success":
        print(item["params"]["domain"], len(item["data"]["technologies"]))
    else:
        print(item["params"]["domain"], "failed:", item["error_code"])

csv_text = client.tasks.results(task, format="csv")

Send full parameter objects with items instead of inputs, and use tasks.get, tasks.list and tasks.cancel to manage jobs.

Monitors

A monitor re-runs one engine on a schedule (every 60 minutes or more), keeps a snapshot of the values you watch and records events: change when they differ, alert when a condition starts to hold, recovered when it clears, and error. Events are sent to a signed webhook and, unless you turn it off with notify_email, by email. Each run is billed like a normal request, and create returns estimated_credits_per_month.

client.monitors.templates()  # domain_expiry, ssl_expiry, dns_change, email_security, page_change, serp_rank, app_store_reviews, google_play_reviews, new_reviews

# From a template: alert 21 days before the certificate expires
ssl = client.monitors.create(
    template="ssl_expiry", target="gridlode.com", options={"days": 21},
    webhook_url="https://example.com/hooks/gridlode",
)
secret = ssl.get("webhook_secret")  # returned once; store it

# From any engine: what to run, which values to compare, when to alert
rdap = client.monitors.create(
    engine="domain.rdap",
    params={"domain": "example.com"},
    watch=["dates.expires", "registrar.name", "nameservers"],
    conditions=[{"path": "dates.expires", "op": "days_until_lt", "value": 30, "label": "Expires within 30 days"}],
    interval_minutes=1440,
)

client.monitors.run(rdap)                        # check now
client.monitors.update(rdap, status="paused")    # name, status, interval_minutes, notify_email, webhook_url
client.monitors.events(rdap, limit=20)           # or client.monitors.events() for every monitor
client.monitors.history(rdap)                    # snapshots of the watched values
client.monitors.delete(rdap)

Watch expressions pick values out of the engine's result: a.b.c (a dotted path, list indexes allowed), a[].b (a value across a list), @hash(path), @rank(array, field, needle), @ids(array, field) and @count(path). Condition operators are lt, lte, gt, gte, eq, ne, days_until_lt, contains, not_contains, is_true and is_false.

Verify webhooks

Jobs send task.completed, task.failed or task.cancelled with {"event":...,"task":{...}}. Monitors send monitor.change, monitor.alert, monitor.recovered or monitor.error with the monitor, a summary and the changes. Every delivery is signed with that job's or monitor's webhook_secret in the X-Gridlode-Signature header (t=timestamp,v1=hex). Verify the raw request body, not re-serialized JSON. Signatures older than five minutes are rejected by default.

from flask import Flask, abort, request
from gridlode import webhooks, WebhookVerificationError

app = Flask(__name__)

@app.post("/hooks/gridlode")
def gridlode_hook():
    try:
        event = webhooks.construct_event(
            request.get_data(),                         # the raw body, not parsed JSON
            request.headers.get("X-Gridlode-Signature"),
            WEBHOOK_SECRET,                             # whsec_... from tasks or monitors.create()
        )
    except WebhookVerificationError:
        abort(400)
    if event["event"] == "task.completed":
        download_results(event["task"]["id"])
    elif event["event"] == "monitor.alert":
        notify_on_call(event["monitor"]["name"], event["summary"])
    return "", 204

Use webhooks.verify(payload, header, secret) to get true or false instead of an exception, and webhooks.sign(payload, secret) to build a valid header when testing your endpoint locally.

Errors

Failed calls raise (Python) or reject with (Node.js) a subclass of APIError that carries the HTTP status, the error type, code, message, details and the request_id. All errors share the base class GridlodeError. See Errors for every code.

from gridlode import APIError, InsufficientCredits, RateLimited, TargetError

try:
    meta = client.url.metadata(url="https://example.com")
except TargetError as err:          # 424: the site failed or refused; not charged
    print("site failed:", err.code)
except InsufficientCredits:         # 402
    print("top up your balance")
except RateLimited as err:          # 429 after the automatic retries
    print("slow down, retry in", err.retry_after, "s")
except APIError as err:             # anything else from the API
    print(err.status_code, err.code, err.message, err.request_id)

Retries and timeouts

Engine calls, the search endpoint, job creation, monitors and the MCP server share your key's rate limit. Both clients retry HTTP 429 (waiting for Retry-After, up to 60 seconds), 500, 502, 503, 504 and connection failures, by default twice, with jittered exponential backoff. A request that may already have reached the server, such as one that timed out while waiting for the answer, is retried only for GET, so an engine call, job or monitor is never created twice. Target errors (424) and disabled engines are not retried automatically; retry target errors yourself if the site is likely to recover. See Rate limits.

client = Gridlode(timeout=120, max_retries=4)          # seconds
fast = client.with_options(timeout=10, max_retries=0)  # shares the connection pool

Async Python

import asyncio
from gridlode import AsyncGridlode

async def main():
    async with AsyncGridlode() as client:
        domains = ["stripe.com", "shopify.com", "vercel.com"]
        results = await asyncio.gather(*(client.domain.rdap(domain=d) for d in domains))
        for d, r in zip(domains, results):
            print(d, r.data.get("registrar"))

asyncio.run(main())

Configuration

No SDK for your language? Every engine is a plain HTTPS call, and the OpenAPI spec can generate a client. For no-code tools, see Integrations; for AI agents, the MCP server.