# GridRouter > GridRouter is the OpenRouter for go-to-market data: one API, one key and an MCP server for enrichment, email, phone, signals, ads, SEO and CRM tools, with quality scores measured on real traffic. GridRouter is built by Relaygrid, Inc. The catalog lists 59 capabilities from 439 providers across 22 categories. Machine-readable API links are in the [API catalog](https://gridrouter.io/.well-known/api-catalog). API base URL: https://api.gridrouter.io. Money is integer micro-USD (1,000,000 = $1). Every docs page is also Markdown at its URL plus `.md`; every guide in one file: https://gridrouter.io/llms-full.txt. ## Site - [Overview](https://gridrouter.io/product): Product - [API and routing](https://gridrouter.io/product/api): Product - [MCP server](https://gridrouter.io/product/mcp): Product - [Waterfalls](https://gridrouter.io/product/waterfalls): Product - [Waterfall templates](https://gridrouter.io/waterfalls/templates): Product - [Logs](https://gridrouter.io/product/logs): Product - [Billing checks](https://gridrouter.io/product/billing-verification): Product - [Private cache](https://gridrouter.io/product/cache): Product - [Alerts](https://gridrouter.io/product/alerts): Product - [Security and governance](https://gridrouter.io/product/security): Product - [Demo](https://gridrouter.io/demo): Product - [Pricing](https://gridrouter.io/pricing): Product - [Providers](https://gridrouter.io/providers): Data - [Capabilities](https://gridrouter.io/capabilities): Data - [Catalog](https://gridrouter.io/catalog): Data - [Rankings](https://gridrouter.io/rankings): Data - [Leaderboards](https://gridrouter.io/leaderboards): Data - [The Grid](https://gridrouter.io/grid): Data - [Apps](https://gridrouter.io/apps): Data - [Activity](https://gridrouter.io/activity): Data - [Status](https://gridrouter.io/status): Data - [List your API](https://gridrouter.io/vendors): Vendors - [Comparisons](https://gridrouter.io/compare/gridrouter-vs-clay): Vendors - [Alternatives](https://gridrouter.io/alternatives): Vendors - [Field directory](https://gridrouter.io/fields): Vendors - [Use cases](https://gridrouter.io/use-cases): Vendors - [Docs](https://gridrouter.io/docs): Company - [Blog](https://gridrouter.io/blog): Company - [Changelog](https://gridrouter.io/changelog): Company - [Security](https://gridrouter.io/security): Company - [Terms](https://gridrouter.io/terms): Company - [Privacy](https://gridrouter.io/privacy): Company ## Docs - [API reference](https://gridrouter.io/docs/api.md): Every GridRouter route, generated from the gateway's OpenAPI document. Base URL, authentication and conventions. - [CLI](https://gridrouter.io/docs/cli.md): The grid command line tails and prints your live log from a terminal. - [Alerts](https://gridrouter.io/docs/concepts/alerts.md): Rules over your calls, budgets, vendor keys, billing checks and deliveries. Alerts open, repeat, get acknowledged and resolve, and notify the destinations you choose. - [Vendor billing verification](https://gridrouter.io/docs/concepts/billing-verification.md): Every call on your own vendor key says whether the provider billed it the way its published rules say it should. - [Build a waterfall](https://gridrouter.io/docs/concepts/build-a-waterfall.md): Start from a template or from scratch, choose steps and speed, set stop rules and per-step limits, test on the sandbox, publish and run. - [Capabilities and endpoints](https://gridrouter.io/docs/concepts/capabilities-and-endpoints.md): A capability is a task, such as finding a work email. An endpoint is one provider's API call for it. Both live in one typed catalog. - [Execution options](https://gridrouter.io/docs/concepts/execution-options.md): One typed options object for timeouts, cost caps, cache, storage and logging, set per request, key, preset or workspace. - [Integrations](https://gridrouter.io/docs/concepts/integrations.md): Send alerts to email, your own webhook endpoints, Slack, Discord, Microsoft Teams, PagerDuty and Opsgenie. Where to find each credential, what the message looks like and how to test it. - [Logs, live tail and drains](https://gridrouter.io/docs/concepts/logs-and-drains.md): Every call is logged and streamed as it happens. Search it, tail it from the CLI, SDK or MCP, and drain it to your own stack. - [Merge rules](https://gridrouter.io/docs/concepts/merge-rules.md): How a waterfall picks each field's value when providers disagree, records provenance and conflicts, and builds one golden record across stages. - [Plans and pricing](https://gridrouter.io/docs/concepts/plans.md): Every workspace is on Free at launch. What Free includes, what is always free, and how metered plans will work. - [Private cache](https://gridrouter.io/docs/concepts/private-cache.md): Your workspace's encrypted cache of what it already fetched. Repeats are free, and partly known records only fetch the missing fields. - [Routing and fallbacks](https://gridrouter.io/docs/concepts/routing.md): How /v1/run picks providers for a capability, falls through on misses and errors, and how to steer it. - [Security](https://gridrouter.io/docs/concepts/security.md): How GridRouter protects API keys, vendor credentials, your workspace's data and the dashboard. - [Waterfall templates](https://gridrouter.io/docs/concepts/waterfall-templates.md): Every built-in waterfall template, its inputs, outputs, capabilities, speed, run mode and list-price cost, generated from the template library. - [Waterfalls](https://gridrouter.io/docs/concepts/waterfalls.md): Save an ordered set of providers, a speed profile, stop rules and a per-field merge as your own versioned endpoint. - [Webhooks](https://gridrouter.io/docs/concepts/webhooks.md): Signed HTTPS events for calls, jobs, lists, waterfall runs, alerts, vendor keys, billing checks, budgets, keys and members. Standard Webhooks signatures, retries for about a day, a delivery log and replay. - [Discovery documents](https://gridrouter.io/docs/discovery.md): Every machine-readable document GridRouter publishes for agents and tools, with its URL and media type. - [Errors](https://gridrouter.io/docs/errors.md): One error envelope for every route and MCP tool, with stable codes, HTTP statuses and what to do about each. - [Create an API key](https://gridrouter.io/docs/getting-started/api-keys.md): One GridRouter key reaches every provider you have connected. Scope it, cap it, and keep a backup. - [Connect an MCP client](https://gridrouter.io/docs/getting-started/connect-mcp.md): Connect an MCP 2026-07-28 client to GridRouter over stateless Streamable HTTP. - [Make a first call](https://gridrouter.io/docs/getting-started/first-call.md): Find a work email with one endpoint, then let GridRouter route the same call across providers. - [Quickstart](https://gridrouter.io/docs/getting-started.md): From sign-up to a first enrichment call in five steps. - [Create a workspace](https://gridrouter.io/docs/getting-started/sign-up.md): Sign up, verify your email and land in your own workspace on the Free plan. - [Add a vendor key](https://gridrouter.io/docs/getting-started/vendor-keys.md): Bring your own key (BYOK) for a provider. GridRouter stores it encrypted and never charges for calls made with it. - [GridRouter docs](https://gridrouter.io/docs.md): One API, one key and an MCP server for every go-to-market data provider, with quality scores measured on real traffic. - [MCP server](https://gridrouter.io/docs/mcp.md): Every GridRouter operation as an MCP tool, plus catalog resources, a live log subscription and prompts. - [Rate limits](https://gridrouter.io/docs/rate-limits.md): The limits that apply to your requests, the headers that describe them, and how to handle a 429. - [TypeScript SDK](https://gridrouter.io/docs/sdk.md): The @relaygrid/sdk client for calls, routed runs, waterfalls and the live log. - [Agent skills](https://gridrouter.io/skills): Downloadable SKILL.md files - [Security policy](https://gridrouter.io/security): Vulnerability disclosure ## API reference - [Search the catalog](https://gridrouter.io/docs/api/catalog/catalog_search.md): Find vendor endpoints by keyword (capability, vendor, what they return). Returns price and quality. - [Get an endpoint](https://gridrouter.io/docs/api/catalog/catalog_get.md): Full definition of one endpoint: input JSON Schema, pricing model and quality. - [Search vendors](https://gridrouter.io/docs/api/catalog/vendor_search.md): Every GTM data vendor GridRouter knows about (integrated or researched): API access, spec status, published rate limits and marketplace listings. - [Get a vendor](https://gridrouter.io/docs/api/catalog/vendor_get.md): One vendor's sourced record: company, API surface, docs, pricing, data, compliance, relationships and marketplace listings, each with sources and confidence. - [Get a vendor's OpenAPI spec](https://gridrouter.io/docs/api/catalog/vendor_openapi.md): The stored OpenAPI document for a vendor: the vendor's official spec, or one GridRouter reconstructed from its docs (x-reconstructed, x-confidence, x-source-url on every operation). - [Get a vendor's rate limits](https://gridrouter.io/docs/api/catalog/vendor_rate_limits.md): Published rate limits (per window, concurrency, headers, 429 behaviour) with source and check date, and the pacing GridRouter derives from them. - [List capabilities](https://gridrouter.io/docs/api/catalog/capabilities_list.md): Capabilities (normalized tasks like people.email.find) and the endpoints that serve each. - [List categories](https://gridrouter.io/docs/api/catalog/categories_list.md): Top-level GTM data categories. - [Quality leaderboard](https://gridrouter.io/docs/api/catalog/leaderboard_get.md): Endpoints for a capability ranked by usage-derived quality (Wilson lower bound). - [Quote a call](https://gridrouter.io/docs/api/catalog/quote.md): Worst-case cost of calling an endpoint with this input, without calling it. - [Apps showcase](https://gridrouter.io/docs/api/catalog/apps_directory.md): Public apps built on GridRouter (owners opted in), ranked by calls with their top capabilities and providers. - [Public app profile](https://gridrouter.io/docs/api/catalog/app_profile_get.md): One public app: 30-day usage by day, top capabilities and providers. - [Endpoint activity and uptime](https://gridrouter.io/docs/api/catalog/activity_get.md): Per-endpoint uptime (share of calls without a vendor-side failure), p50/p95 latency and volume over time for a capability or provider, plus the top public apps using it. - [Export tool definitions](https://gridrouter.io/docs/api/catalog/tools_export.md): Endpoint and capability tools in OpenAI, Anthropic or MCP format. - [Validate a vendor definition](https://gridrouter.io/docs/api/catalog/registry_validate.md): Lint a provider + endpoints YAML submission against the registry schema and margin guard. - [Submit a vendor definition](https://gridrouter.io/docs/api/catalog/registry_submit.md): Submit catalog YAML (validated as in registry_validate) for review by the GridRouter team. - [Review an endpoint](https://gridrouter.io/docs/api/catalog/review_create.md): Leave a rating backed by your verified call count. (planned) - [Call an endpoint](https://gridrouter.io/docs/api/calls/call.md): Call one vendor endpoint. Reserves the worst-case cost, charges the actual cost. Async vendors return a job. - [Run the best capability for your inputs](https://gridrouter.io/docs/api/calls/run_auto.md): Auto router: GridRouter picks the capability from the input fields you have (and the output fields you ask for), then routes it like run. The chosen capability and the alternatives are returned. - [Run a capability](https://gridrouter.io/docs/api/calls/run.md): Routed call: GridRouter picks vendors (waterfall/cheapest/best) until one hits. Only hits are charged on per-success vendors. - [Look up a call](https://gridrouter.io/docs/api/calls/call_get.md): Cost, timings (total, upstream, overhead, TTFB, queue), provider, outcome and every routed attempt of one call, like OpenRouter's generation lookup. Keys without logs:read only see calls they made. Available a few seconds after the call. - [List presets](https://gridrouter.io/docs/api/calls/presets_list.md): Saved routing presets for this org: provider preferences, field selection, max cost and stop rule. Use one as preset: "@slug" on run. - [Save a preset](https://gridrouter.io/docs/api/calls/presets_create.md): Create or replace a routing preset shared within the org (order/only/ignore/sort/max price/data policy, credential, fields, max cost, stop rule). - [Get a preset](https://gridrouter.io/docs/api/calls/presets_get.md): One saved routing preset. - [Delete a preset](https://gridrouter.io/docs/api/calls/presets_delete.md): Delete a preset. Requests that name it fail with not_found afterwards. - [Get the execution options schema](https://gridrouter.io/docs/api/calls/options_schema.md): JSON Schema of ExecutionOptions: timing, concurrency, rate limits, cost, routing, data and cache, delivery, identity and observability. Every request body accepts it as `options`. - [Preview effective options](https://gridrouter.io/docs/api/calls/options_resolve.md): What a request would run with: request options over the preset, your key's defaults and the workspace defaults, clamped by your plan. Returns where each value came from and what was clamped. - [Get workspace default options](https://gridrouter.io/docs/api/calls/options_defaults_get.md): The workspace's default ExecutionOptions (the lowest precedence layer). - [Set workspace default options](https://gridrouter.io/docs/api/calls/options_defaults_put.md): Replace the workspace's default ExecutionOptions (cache TTLs per field class, log level, timeouts…). Applies to every key within 30 seconds. - [Queue a call](https://gridrouter.io/docs/api/async/job_create.md): Run any endpoint in the background through the job queue, with per-vendor pacing. - [Get a job](https://gridrouter.io/docs/api/async/job_get.md): Status and result of a queued or async job. - [Enrich a list](https://gridrouter.io/docs/api/async/list_create.md): Run an endpoint or capability over up to 10,000 rows in the background. - [Get a list](https://gridrouter.io/docs/api/async/list_get.md): Progress and cost of a list run. - [List results page](https://gridrouter.io/docs/api/async/list_rows.md): One page of per-row results for a list. - [Get balance](https://gridrouter.io/docs/api/account/balance_get.md): Prepaid balance, amount held for in-flight calls, and what is available. - [List budgets](https://gridrouter.io/docs/api/account/budgets_list.md): Every spend cap (workspace, key, agent) with its period and what it used in the current window. - [Remove a budget](https://gridrouter.io/docs/api/account/budget_remove.md): Remove the spend cap for the org, one key, or one agent. - [Set a budget](https://gridrouter.io/docs/api/account/budget_set.md): Cap spend for the org, one key, or one agent per day, month or total. - [Get org settings](https://gridrouter.io/docs/api/account/settings_get.md): Org data settings, such as whether request/response bodies are stored. - [Update org settings](https://gridrouter.io/docs/api/account/settings_update.md): Turn body storage on or off (off stops new bodies from being kept) and set how many days of call log members and keys can read (30, 90, 180 or 360). - [Usage by tag](https://gridrouter.io/docs/api/account/usage_by_tag.md): Spend and calls grouped by a meta tag over a window (reads the Postgres mirror). (planned) - [List plans](https://gridrouter.io/docs/api/account/plans_list.md): Every GridRouter plan with its price, limits, features and managed-call markup, plus the shared overage rates and always-free list. - [Get entitlements](https://gridrouter.io/docs/api/account/entitlements_get.md): This org's plan, resolved limits (null means no cap), features and usage this month, including logged calls and overage blocks. - [Get billing overview](https://gridrouter.io/docs/api/account/billing_get.md): Billing mode, plan and subscription status, balance (with any simulated test credit), auto-recharge and receipts. - [Start a checkout](https://gridrouter.io/docs/api/account/billing_checkout_create.md): Buy credits (amount_usd, the 5.5% top-up fee is added) or upgrade to a paid plan. Returns a URL: Stripe Checkout, or the test purchase page when billing is simulated. - [Get a checkout](https://gridrouter.io/docs/api/account/billing_checkout_get.md): One checkout session and its status (open, completed, declined, requires_action). - [Complete a test purchase](https://gridrouter.io/docs/api/account/billing_checkout_complete.md): Simulated billing only: approve, decline or require card action on a test checkout. Emits the same events Stripe would; no card is charged. - [Downgrade or cancel a plan](https://gridrouter.io/docs/api/account/billing_plan_change.md): Move to a lower plan, or to Free to cancel. Upgrades go through billing_checkout_create. - [Set auto-recharge](https://gridrouter.io/docs/api/account/billing_autorecharge_set.md): Top up by amount_usd whenever the balance drops below threshold_usd. - [Simulate a billing event](https://gridrouter.io/docs/api/account/billing_simulate.md): Test and simulated modes only: payment failure, dispute (freezes the org), refund, renewal, downgrade, cancel, auto-recharge, grant expiry, or reset simulated state. - [List API keys](https://gridrouter.io/docs/api/access/keys_list.md): API keys for this org (never the secret). - [Create an API key](https://gridrouter.io/docs/api/access/keys_create.md): Mint a scoped key. The secret is returned once. - [Revoke an API key](https://gridrouter.io/docs/api/access/keys_revoke.md): Revoke a key. Billable calls stop immediately. - [Create recovery codes](https://gridrouter.io/docs/api/access/recovery_codes_create.md): Owner only (a * key): issue 10 one-time recovery codes that can mint a new owner key if every key is lost. Replaces earlier codes; shown once. - [Rotate an API key](https://gridrouter.io/docs/api/access/keys_rotate.md): Mint a replacement key with the same scopes and limits; the old key keeps working for grace_seconds (default 24 h), then expires. - [Set a key's credit limit](https://gridrouter.io/docs/api/access/keys_limit_set.md): Cap what one key can spend, resetting daily, weekly, monthly or never. null removes the cap. Calls over the cap fail with budget_blocked. - [Create an agent](https://gridrouter.io/docs/api/access/agents_create.md): Create an agent with its own budget and mint an agent key for it. - [List vendor credentials](https://gridrouter.io/docs/api/access/credentials_list.md): Your own vendor keys (BYOK) stored for this org: provider, slot, label, field names, the key's last four characters and its last test result. Secrets are write-only and never returned. - [Remove a vendor credential](https://gridrouter.io/docs/api/access/credentials_remove.md): Delete one slot of your own key for a provider. Calls fall back to the next slot. - [Add a vendor credential](https://gridrouter.io/docs/api/access/credentials_put.md): Store your own key for a provider as the primary or fallback slot, envelope-encrypted. BYOK calls are never charged by GridRouter. - [Test a vendor credential](https://gridrouter.io/docs/api/access/credentials_test.md): Call the provider's free, read-only test endpoint (for example a credit balance) with your stored key. Never charged; the call is logged. - [Test a vendor key before saving it](https://gridrouter.io/docs/api/access/credentials_verify.md): Call the provider's free, read-only test endpoint with a key that is not stored yet. Nothing is saved; the key is used for this one call. Never charged; the call is logged. - [Rename a vendor credential](https://gridrouter.io/docs/api/access/credentials_update.md): Set or clear the label of a stored key. The secret is not touched. - [Swap primary and fallback keys](https://gridrouter.io/docs/api/access/credentials_swap.md): Make the fallback key the primary and the primary the fallback for one provider. Takes effect on the next call. - [List your apps](https://gridrouter.io/docs/api/access/apps_list.md): Apps attributed on your calls (X-Grid-App, or HTTP-Referer + X-Title like OpenRouter) with 30-day usage, plus how each is listed. - [Register an app](https://gridrouter.io/docs/api/access/apps_put.md): Name an attributed app and opt it in (or out) of the public rankings and showcase. A domain-style id must match its URL; another org's public id is refused. - [Authorize a third-party app](https://gridrouter.io/docs/api/access/auth_code_create.md): Consent step of Sign in with GridRouter (OAuth PKCE, S256): a signed-in member approves an app and gets a one-time code (10 minutes) to redirect back with. - [Exchange an app code for a key](https://gridrouter.io/docs/api/access/auth_keys_exchange.md): Final step of Sign in with GridRouter: exchange the one-time code and its PKCE code_verifier for a user-controlled key with call/run scopes and any credit limit the user set. - [Set a key's default options](https://gridrouter.io/docs/api/access/keys_options_set.md): Default ExecutionOptions for one API key, between the preset and the workspace defaults. Send `{}` to clear. - [List saved log views](https://gridrouter.io/docs/api/logs/log_views_list.md): Your saved log views plus views shared with the workspace, newest first. A view is a query in the log query language and the visible columns. - [Save a log view](https://gridrouter.io/docs/api/logs/log_views_create.md): Save the query and visible columns under a name. `shared: true` (owners and admins only) makes it visible to the whole workspace; `replace: true` overwrites your view with the same name. - [Delete a log view](https://gridrouter.io/docs/api/logs/log_views_delete.md): Delete one of your views (owners and admins can also delete shared views). - [Rename or update a log view](https://gridrouter.io/docs/api/logs/log_views_update.md): Rename a view or change its query, columns or sharing. You can change your own views; owners and admins can also change shared ones. - [Import browser-saved views and pins](https://gridrouter.io/docs/api/logs/log_views_import.md): One-time move of views and pins the dashboard kept in the browser. Views whose names you already use and calls already pinned are skipped. - [List pinned calls](https://gridrouter.io/docs/api/logs/log_pins_list.md): Calls you pinned to the top of the log viewer, newest pin first, each with its current log row (null once the call is past log retention). - [Pin a call](https://gridrouter.io/docs/api/logs/log_pins_create.md): Pin a call to the top of the log viewer. You keep up to 20 pins; the oldest drops off. - [Unpin a call](https://gridrouter.io/docs/api/logs/log_pins_delete.md): Remove a pinned call. - [Search call logs](https://gridrouter.io/docs/api/logs/logs_list.md): Every call and routed attempt for this org, newest first (360-day retention). Filter by time, outcome, status, provider, capability, endpoint, key, agent, client, mode, credential, error code, latency and cost; cursor-paginated. - [Call log facets](https://gridrouter.io/docs/api/logs/logs_facets.md): Counts per value (outcome, status, provider, capability, endpoint, key, client…) and latency/cost ranges for the same filters as logs_list. - [Call log stats](https://gridrouter.io/docs/api/logs/logs_stats.md): Calls, error rate, p50/p95/p99 latency, spend, a hit/miss/failed timeline and spend by provider over time, for the same filters as logs_list. - [Vendor billing accuracy](https://gridrouter.io/docs/api/logs/logs_billing.md): Per vendor, how many of your own-key (BYOK) calls were billed as the vendor's published rule says, how many were charged for a miss, double-charged on a retry or at the wrong price, and the credits and dollars at stake. Same filters as logs_list. - [Get a call log](https://gridrouter.io/docs/api/logs/logs_get.md): One call with timings, its redacted request/response body (audit-logged), the other attempts in its routed run or list, and its ledger entries. - [Tail the live log](https://gridrouter.io/docs/api/logs/logs_tail.md): The newest events from the live tail (calls, waterfall run steps, jobs, lists and alerts), newest last, with the same filters as the stream: provider, capability, status, key, app, run or waterfall, minimum latency and cost, sample and fields. Stream them with GET /v1/logs/live or the logs://live MCP resource. - [Get a live tail ticket](https://gridrouter.io/docs/api/logs/logs_live_ticket.md): A single-use ticket valid for 60 seconds that opens GET /v1/logs/live without an Authorization header (browsers). Carries logs:read for this org only. - [List log drains](https://gridrouter.io/docs/api/logs/drains_list.md): Log drains with their target, filter, batching and delivery health. Credentials are never returned. - [Create a log drain](https://gridrouter.io/docs/api/logs/drains_create.md): Send the live log to an HTTPS webhook (HMAC-signed), Axiom, Datadog, or S3, GCS or R2 as NDJSON. Credentials are stored encrypted in the vault and are write-only. Webhook drains return their signing secret once. - [Get a log drain](https://gridrouter.io/docs/api/logs/drains_get.md): One drain with its delivery health. - [Delete a log drain](https://gridrouter.io/docs/api/logs/drains_delete.md): Stop sending and remove the drain and its stored credentials. - [Update a log drain](https://gridrouter.io/docs/api/logs/drains_update.md): Rename, pause or resume, change the target, filter or batching, or replace credentials. - [Test a log drain](https://gridrouter.io/docs/api/logs/drains_test.md): Send one sample event to the drain now and report the result; updates drain health. - [Alerts summary](https://gridrouter.io/docs/api/logs/alerts_summary.md): Open alerts by severity, when the last one fired, and how many rules, destinations and webhook endpoints the workspace has. - [List alert rules](https://gridrouter.io/docs/api/logs/alerts_rules_list.md): Every alert rule with its metric, threshold, window, scope, severity, destinations, mute and live state (ok, firing, muted, no_data). New workspaces start with defaults (a vendor key failing, budgets at 80% and 100%, billing mismatches, error-rate and spend spikes, a key on a new IP, failing deliveries, security events). - [Create an alert rule](https://gridrouter.io/docs/api/logs/alerts_rules_create.md): Alert when a metric crosses a threshold over a window: error_rate, p95_latency, spend, budget_used, vendor_failure_spike, vendor_key_failing, billing_mismatch, cache_hit_rate, delivery_backlog, security_event or new_ip. Scope it to the workspace, a key, a vendor or a capability; route it to every destination or to chosen ones. - [Get an alert rule](https://gridrouter.io/docs/api/logs/alerts_rules_get.md): One alert rule with its state. - [Delete an alert rule](https://gridrouter.io/docs/api/logs/alerts_rules_delete.md): Delete the rule and resolve its open alerts. - [Update an alert rule](https://gridrouter.io/docs/api/logs/alerts_rules_update.md): Change any field; fields you leave out keep their value. Changing what the rule measures resolves its open alerts. - [Mute or unmute an alert rule](https://gridrouter.io/docs/api/logs/alerts_rules_mute.md): Snooze a rule for `minutes` (or until `until`); it keeps evaluating and recording alerts but sends nothing. `minutes: 0` unmutes. - [Send a test alert for a rule](https://gridrouter.io/docs/api/logs/alerts_rules_test.md): Send a test alert to every destination the rule notifies, now, and report each result. Nothing is recorded as a real alert. - [List alert destinations](https://gridrouter.io/docs/api/logs/alerts_destinations_list.md): Where alerts go (email, webhook endpoints, Slack, Discord, Microsoft Teams, PagerDuty, Opsgenie) with delivery health. Secrets are masked. - [Connect an alert destination](https://gridrouter.io/docs/api/logs/alerts_destinations_create.md): Connect email recipients (with optional hourly or daily digests), a webhook endpoint, a Slack or Discord incoming webhook, a Microsoft Teams Workflows URL, a PagerDuty Events API v2 integration key or an Opsgenie API key. The secret is stored encrypted in the vault and never returned. - [Get an alert destination](https://gridrouter.io/docs/api/logs/alerts_destinations_get.md): One destination with its delivery health. - [Remove an alert destination](https://gridrouter.io/docs/api/logs/alerts_destinations_delete.md): Stop sending there and delete its stored secret. Rules that listed it stop routing to it. - [Update an alert destination](https://gridrouter.io/docs/api/logs/alerts_destinations_update.md): Rename, pause or resume, change the minimum severity or settings, or replace the secret. - [Send a test to an alert destination](https://gridrouter.io/docs/api/logs/alerts_destinations_test.md): Deliver a test alert now and report the result (PagerDuty and Opsgenie tests open and immediately resolve their own incident). Test emails are queued. - [List alerts](https://gridrouter.io/docs/api/logs/alerts_list.md): Alerts newest first: open (triggered or acknowledged) or resolved, with how often each repeated and its timeline of notifications. - [Get an alert](https://gridrouter.io/docs/api/logs/alerts_get.md): One alert with its full timeline. - [Acknowledge an alert](https://gridrouter.io/docs/api/logs/alerts_acknowledge.md): Mark an open alert as being handled. PagerDuty and Opsgenie destinations are acknowledged too. - [Resolve an alert](https://gridrouter.io/docs/api/logs/alerts_resolve.md): Close an open alert now; destinations that get resolve notifications are told. The rule's cooldown starts from here. - [Usage rankings](https://gridrouter.io/docs/api/insights/rankings_get.md): Top capabilities, providers, categories and opted-in apps by calls and hits over the last day, week or month across all GridRouter traffic, with change vs the previous window and trending movers. - [Provider status](https://gridrouter.io/docs/api/insights/status_get.md): Live health per provider: vendor failures in the last 30 seconds (the router's outage signal), last-hour error rate and latency, and 24-hour and 30-day uptime with daily bars. - [Platform announcements](https://gridrouter.io/docs/api/other/announcements_list.md): Current platform announcements (maintenance windows, incidents, launches). - [List webhook event types](https://gridrouter.io/docs/api/other/webhooks_event_types.md): Every event a webhook endpoint can subscribe to, with when it is sent and the current api_version. - [List webhook endpoints](https://gridrouter.io/docs/api/other/webhooks_endpoints_list.md): Webhook endpoints with their subscriptions, status and delivery health. Secrets are never returned. - [Create a webhook endpoint](https://gridrouter.io/docs/api/other/webhooks_endpoints_create.md): Receive events at an HTTPS URL, signed per Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature). Returns the whsec_ signing secret once. - [Get a webhook endpoint](https://gridrouter.io/docs/api/other/webhooks_endpoints_get.md): One endpoint with its delivery health. - [Delete a webhook endpoint](https://gridrouter.io/docs/api/other/webhooks_endpoints_delete.md): Stop delivering, delete its secrets and delivery log. - [Update a webhook endpoint](https://gridrouter.io/docs/api/other/webhooks_endpoints_update.md): Change the URL, description or subscribed events, or enable and disable it (re-enabling an automatically disabled endpoint clears its failure count). - [Rotate a webhook signing secret](https://gridrouter.io/docs/api/other/webhooks_endpoints_rotate_secret.md): Issue a new signing secret. The old one keeps signing alongside it for `overlap_s` (default 24 hours), so both verify while you deploy the new one. Returns the new secret once. - [Send a test webhook event](https://gridrouter.io/docs/api/other/webhooks_endpoints_test.md): Deliver an example event of the given type (marked test: true) to the endpoint now and return the delivery with its attempt. - [List webhook deliveries](https://gridrouter.io/docs/api/other/webhooks_deliveries_list.md): Recent deliveries newest first with every attempt's status code, latency and a redacted response snippet. Kept 30 days. - [Get a webhook delivery](https://gridrouter.io/docs/api/other/webhooks_deliveries_get.md): One delivery with its attempts and the start of the signed body. - [Replay a webhook delivery](https://gridrouter.io/docs/api/other/webhooks_deliveries_replay.md): Send a delivery again with the same webhook-id (receivers that dedupe on it ignore a duplicate) and a fresh retry schedule. - [Waterfall builder catalog](https://gridrouter.io/docs/api/waterfalls/waterfall_catalog.md): Every capability with its inputs, normalized output fields, and the endpoints a waterfall can use: price, quality, fill, p50 and rate limits. - [List waterfall templates](https://gridrouter.io/docs/api/waterfalls/waterfall_templates.md): Prebuilt GTM waterfalls (work email, mobile, verification, catch-all, person and company enrichment, job change, full lead enrichment, CRM hygiene and more). Each item has its inputs, outputs, sample_input, recommended speed and run_mode, the explained steps, and availability computed from the catalog: status (ready = runnable now, sandbox = runs on a test key, needs_integration = preview only), vendor_keys (add any one per stage in Settings > Vendor keys) and a list-price cost range in micro-USD. future lists recipes that aren't buildable yet and why. Public: no key needed. - [Get a waterfall template](https://gridrouter.io/docs/api/waterfalls/waterfall_template_get.md): One template by id (or an earlier id): its definition, inputs and outputs, sample_input, explained steps and catalog availability (status, vendor_keys, cost range). Public: no key needed. - [Create a waterfall from a template](https://gridrouter.io/docs/api/waterfalls/waterfall_create_from_template.md): Copy a template into your workspace in one call, optionally pinning vendors per stage, overriding speed or capping cost, and publish it (default) so waterfall_run works right away. Returns the waterfall (id, name, endpoint). Templates with status needs_integration are rejected with validation_failed. Next: waterfall_run with {id, input}. - [List waterfalls](https://gridrouter.io/docs/api/waterfalls/waterfall_list.md): Waterfalls and pipelines in this org, newest first, with their published version. - [Create a waterfall](https://gridrouter.io/docs/api/waterfalls/waterfall_create.md): Create a draft waterfall (one capability, ordered vendor steps, speed profile, stop rules, per-field merge) or a multi-stage pipeline. Start from a definition, a template or a routing preset. - [Get a waterfall](https://gridrouter.io/docs/api/waterfalls/waterfall_get.md): One waterfall: its draft definition, versions and published endpoint. - [Delete a waterfall](https://gridrouter.io/docs/api/waterfalls/waterfall_delete.md): Delete a waterfall and its versions; its published endpoint stops answering. - [Update a waterfall draft](https://gridrouter.io/docs/api/waterfalls/waterfall_update.md): Replace the draft definition, title or description. Published versions never change. - [Estimate a waterfall](https://gridrouter.io/docs/api/waterfalls/waterfall_estimate.md): Price a waterfall before running it, without calling any vendor: per-step quote, p50 latency, fill and reach, plus worst-case and expected cost (micro-USD) and ETA. Pass a definition, or a template id with the same pins/speed/max_cost_micro choices as waterfall_create_from_template. - [Waterfall versions](https://gridrouter.io/docs/api/waterfalls/waterfall_versions.md): Every published version (immutable), newest first. - [Publish a waterfall](https://gridrouter.io/docs/api/waterfalls/waterfall_publish.md): Freeze the draft as a new semver version and serve it at /v1/x/{workspace}/{name} (REST, MCP x_run and OpenAPI). - [Roll back a waterfall](https://gridrouter.io/docs/api/waterfalls/waterfall_rollback.md): Serve an earlier published version again. Nothing is deleted. - [Export a waterfall as a preset](https://gridrouter.io/docs/api/waterfalls/waterfall_preset.md): The waterfall's vendor order as a routing preset body for presets_create, so /v1/run can use it as @slug. - [Published endpoint OpenAPI](https://gridrouter.io/docs/api/waterfalls/waterfall_openapi.md): OpenAPI 3.1 for the waterfall's published endpoint /v1/x/{workspace}/{name}. - [Run a waterfall](https://gridrouter.io/docs/api/waterfalls/waterfall_run.md): Run a waterfall on one input and get the golden record: data, _provenance per field (vendor, confidence, verified, conflicts), _attempts, outcome (hit, partial, miss, failed) and cost_micro. Sync by default (up to 50 s). wait: N seconds falls back to a queued run; async: true returns at once with status queued and the run id: poll waterfall_status with {id, run_id}. version defaults to published; use draft for an unpublished waterfall. Set max_cost_micro to cap spend. A vendor you have no key for is skipped; when none can run, the error is vendor_key_required naming them. For lists use waterfall_batch_run. - [Batch-run a waterfall](https://gridrouter.io/docs/api/waterfalls/waterfall_batch_run.md): Run a waterfall over up to 1,000 inputs (JSON rows or CSV) in the background through gr-rows, paced per vendor. Returns the batch (a list) to poll. - [List waterfall runs](https://gridrouter.io/docs/api/waterfalls/waterfall_runs.md): Recent runs of one waterfall: outcome, cost, time, attempts and fields filled. - [Get a waterfall run](https://gridrouter.io/docs/api/waterfalls/waterfall_status.md): Poll a run started with async or wait: status (queued, running, completed, failed, cancelled), then the golden record with _provenance per field, every attempt with its timing and error, and cost per filled field. - [Waterfall run events](https://gridrouter.io/docs/api/waterfalls/waterfall_run_events.md): Progress events of a run after a sequence number (the SSE stream's JSON form). - [Cancel a waterfall run](https://gridrouter.io/docs/api/waterfalls/waterfall_cancel.md): Stop a queued or running run. In-flight attempts are aborted and released; the partial result is kept. - [Run a published waterfall endpoint](https://gridrouter.io/docs/api/waterfalls/x_run.md): Call your own published waterfall by name: /v1/x/{workspace}/{name}, where workspace is your org id. Same modes as waterfall_run. - [Get private cache stats](https://gridrouter.io/docs/api/cache/cache_stats.md): Records (entities and exact responses), bytes, hits and the vendor spend cache hits saved this month and all time, plus daily hit/partial/miss counts. Cache hits are always free. - [List cached records](https://gridrouter.io/docs/api/cache/cache_list.md): The cache explorer: each cached entity or response with its masked label, fields, their ages and freshness, hits and savings. Values are never returned here. - [Purge the private cache](https://gridrouter.io/docs/api/cache/cache_purge.md): Delete cached records by `key`, `tag` or `capability`, or everything with `all=true` (crypto-shreds the workspace cache key: nothing sealed before can be read again). - [Forget a person or company](https://gridrouter.io/docs/api/cache/cache_forget.md): DSAR delete for the private cache: every cached record about this subject (entity records under all its identities and exact responses naming it) is removed. - [Report a bad cached value](https://gridrouter.io/docs/api/cache/cache_feedback.md): Negative feedback, such as a bounce: the named fields are dropped from the subject's cached record so the next request fetches them again. ## API - [API base](https://api.gridrouter.io/v1/): REST API; `Authorization: Bearer ` - [OpenAPI 3.1](https://api.gridrouter.io/openapi.json): service-desc, application/vnd.oai.openapi+json;version=3.1 - [OpenAPI 3.0](https://api.gridrouter.io/openapi-3.0.json): service-desc, application/json - [MCP tool schemas (also format=openai and format=anthropic)](https://api.gridrouter.io/v1/tools?format=mcp): service-desc, application/json - [GridRouter docs](https://gridrouter.io/docs): service-doc, text/html - [llms.txt](https://gridrouter.io/llms.txt): service-doc, text/plain - [Status](https://api.gridrouter.io/v1/status): status, application/json - [Catalog snapshot](https://api.gridrouter.io/v1/catalog/snapshot): service-meta, application/json - [Capabilities](https://api.gridrouter.io/v1/catalog/capabilities): service-meta, application/json ## MCP server - [MCP endpoint](https://mcp.gridrouter.io/mcp): Streamable HTTP; OAuth 2.1 or `Bearer ` - [MCP Server Card](https://mcp.gridrouter.io/mcp/server-card): service-desc, application/mcp-server-card+json - [OAuth protected resource metadata](https://mcp.gridrouter.io/.well-known/oauth-protected-resource/mcp): service-meta, application/json - [Discovery and MCP](https://gridrouter.io/docs/discovery): service-doc, text/html ## Discovery documents - [llms.txt](https://gridrouter.io/llms.txt): Index of the site, API, MCP server and catalog for language models. - [llms-full.txt](https://gridrouter.io/llms-full.txt): Every guide, capability and provider inline, plus the customer integration skill. - [API catalog (site)](https://gridrouter.io/.well-known/api-catalog): RFC 9727 linkset pointing at the OpenAPI descriptions, docs and MCP server. - [AI Catalog (site)](https://gridrouter.io/.well-known/ai-catalog.json): Points agents at the MCP Server Card. - [Agent Skills index](https://gridrouter.io/.well-known/agent-skills/index.json): Agent Skills discovery v0.2.0: downloadable SKILL.md files with sha256 digests. - [Agent Skills index (v0.1.0)](https://gridrouter.io/.well-known/skills/index.json): Legacy Agent Skills discovery path for older clients. - [security.txt (site)](https://gridrouter.io/.well-known/security.txt): RFC 9116 vulnerability disclosure contact and policy. - [OpenAPI 3.1](https://api.gridrouter.io/openapi.json): The full API description. - [OpenAPI 3.0](https://api.gridrouter.io/openapi-3.0.json): The same description down-converted for tools that only read 3.0. - [API llms.txt](https://api.gridrouter.io/llms.txt): The API's own endpoint index for language models. - [API catalog (api)](https://api.gridrouter.io/.well-known/api-catalog): RFC 9727 linkset served by the API host. - [security.txt (api)](https://api.gridrouter.io/.well-known/security.txt): RFC 9116 disclosure contact on the API host. - [MCP Server Card](https://mcp.gridrouter.io/mcp/server-card): Name, transport, auth header and protocol versions of the MCP server. - [OAuth protected resource metadata](https://mcp.gridrouter.io/.well-known/oauth-protected-resource/mcp): RFC 9728 metadata naming the authorization server for the MCP endpoint. - [OAuth authorization server metadata](https://mcp.gridrouter.io/.well-known/oauth-authorization-server): RFC 8414 endpoints for the MCP OAuth 2.1 flow. - [AI Catalog (mcp)](https://mcp.gridrouter.io/.well-known/ai-catalog.json): Points agents at the MCP Server Card from the MCP host. - [security.txt (mcp)](https://mcp.gridrouter.io/.well-known/security.txt): RFC 9116 disclosure contact on the MCP host. ## Categories - [People & Contacts](https://gridrouter.io/catalog/people): Turn a name, a work email or a B2B profile URL (…/in/…) into a current person record: title, seniority, employer, location and past roles. Search by title and company to build contact lists. (3 capabilities) - [Company & Firmographics](https://gridrouter.io/catalog/company): Resolve a domain to firmographics, find companies by industry, size or technology, and pull funding rounds and investors for account scoring. (2 capabilities) - [Email](https://gridrouter.io/catalog/email): Find a work email from a name and domain, verify it before you send, resolve catch-all domains, and learn a company's address pattern. Accuracy here is measured by bounce rate after verification. (3 capabilities) - [Phone](https://gridrouter.io/catalog/phone): Find a prospect's mobile from a B2B profile URL (…/in/…) or work email, and check line type and carrier before a dialer burns a call on a landline. (2 capabilities) - [Intent & Signals](https://gridrouter.io/catalog/signals): Detect when a champion changes jobs, when an account opens roles in your buying team, and other events that make an outbound message timely. (3 capabilities) - [Ads Intelligence](https://gridrouter.io/catalog/ads): Search public ad libraries by advertiser or keyword to see live creative, first-seen dates and spend signals. Useful for account lists and messaging research. (4 capabilities) - [SEO & SERP](https://gridrouter.io/catalog/seo): Pull Google organic results for a keyword, keyword volume and difficulty, and the backlinks behind a domain, priced per call instead of per seat. (4 capabilities) - [Social](https://gridrouter.io/catalog/social): Read a prospect's recent B2B profile posts for a first line that isn't generic, and find the social profiles tied to an email address. (3 capabilities) - [Web Data](https://gridrouter.io/catalog/web): Neural web search, page fetches that survive anti-bot, and extraction of structured fields from articles, product pages and company sites. (3 capabilities) - [Local & Places](https://gridrouter.io/catalog/local): Search local businesses by category and area and pull phone, website, rating and hours. The base layer for SMB and field-sales prospecting. (2 capabilities) - [CRM & Sequencers](https://gridrouter.io/catalog/crm): Upsert contacts and companies into your CRM and enroll leads in Instantly or Smartlead. These run on your own OAuth grant or key, so they are never metered. (2 capabilities) - [AI Utilities](https://gridrouter.io/catalog/ai): Call any model through OpenRouter, or extract a typed JSON object from messy text, without a second key or a second invoice. (2 capabilities) - [Compliance](https://gridrouter.io/catalog/compliance): Check numbers against do-not-call lists and every address against your org's suppression list before a sequence or dialer touches it. (3 capabilities) - [Technographics](https://gridrouter.io/catalog/technographics): Detect the software a company uses from its website, DNS and job posts, and find every company running a product you integrate with or displace. (2 capabilities) - [Funding & Financials](https://gridrouter.io/catalog/funding): Pull funding rounds, investors and valuations for private companies, and revenue and filed statements for public ones, to size and time an account. (3 capabilities) - [Hiring & Job Postings](https://gridrouter.io/catalog/jobs): Search job postings across boards and career sites, or list every open role at one account, to find teams that are growing and the tools they hire for. (2 capabilities) - [News & Media](https://gridrouter.io/catalog/news): Search news articles and press releases by keyword, entity and date, and follow what is being written about an account before you reach out. (2 capabilities) - [Reviews & Reputation](https://gridrouter.io/catalog/reviews): Read ratings and reviews from public review sites for a local business or a software product, for research, reputation monitoring and competitive plays. (2 capabilities) - [IP & Visitor ID](https://gridrouter.io/catalog/ip): Geolocate an IP address, resolve it to the company behind it, and identify the accounts (and, where lawful, people) visiting your website. (3 capabilities) - [Registries & Public Records](https://gridrouter.io/catalog/registry): Look up legal entities in government and legal-entity registries, with registration numbers, filings, officers and trademark records, straight from the source of truth. (4 capabilities) - [E-commerce & Product Data](https://gridrouter.io/catalog/commerce): Profile an online store's platform, apps and size, and search products, prices and sellers across marketplaces and shopping results. (2 capabilities) - [Email Sending & Deliverability](https://gridrouter.io/catalog/sending): Send email through a delivery API and check inbox placement and blocklists, so the addresses you found and verified actually land. (3 capabilities) ## Agent skills - [gridrouter-customer-integration](https://gridrouter.io/.well-known/agent-skills/gridrouter-customer-integration/SKILL.md): Integrates an application or agent with GridRouter, one API key and MCP server for go-to-market data vendors — key setup, catalog search, quotes, routed runs and direct endpoint calls, your own vendor keys, waterfalls, logs and live tail, errors, rate limits and idempotency. Use when calling the GridRouter API or connecting an agent to the GridRouter MCP server. - [gridrouter-waterfalls](https://gridrouter.io/.well-known/agent-skills/gridrouter-waterfalls/SKILL.md): Builds and runs GridRouter waterfalls, multi-vendor recipes that return one golden record per input, from prebuilt templates (work email, mobile, verification, person, company, job change, full lead enrichment, CRM hygiene) — choosing a template and speed, pinning vendors, estimating and capping cost, sync, async and batch runs, reading provenance and conflicts, and fixing vendor_key_required. Use when enriching records through the GridRouter API or MCP server with more than one vendor. ## Capabilities - [Add lead to sequence](https://gridrouter.io/capabilities/sequencer.lead.add): Enroll a lead in a sequencer campaign. (`sequencer.lead.add`, 0 providers) - [B2B ad library](https://gridrouter.io/capabilities/ads.linkedin.search): Sponsored content a company has run, with first-seen dates. (`ads.linkedin.search`, 0 providers) - [B2B profile posts](https://gridrouter.io/capabilities/social.linkedin.posts): A person's or company's recent posts with engagement counts. (`social.linkedin.posts`, 0 providers) - [Backlinks](https://gridrouter.io/capabilities/seo.backlinks): Referring domains and anchors pointing at a site. (`seo.backlinks`, 0 providers) - [Blocklist check](https://gridrouter.io/capabilities/deliverability.blocklist_check): Whether a sending domain or IP is on public blocklists. (`deliverability.blocklist_check`, 0 providers) - [Business reviews](https://gridrouter.io/capabilities/reviews.business): Ratings and reviews for a business from public review sites. (`reviews.business`, 0 providers) - [Company financials](https://gridrouter.io/capabilities/company.financials): Revenue, headcount-based estimates or filed financials for a company. (`company.financials`, 0 providers) - [Company job postings](https://gridrouter.io/capabilities/jobs.company_postings): Every open role at one company, with posted dates and departments. (`jobs.company_postings`, 0 providers) - [Company news](https://gridrouter.io/capabilities/news.company_mentions): Recent coverage that mentions one company. (`news.company_mentions`, 0 providers) - [Do-not-call check](https://gridrouter.io/capabilities/compliance.dnc.check): Is this number on a national or internal do-not-call list. (`compliance.dnc.check`, 0 providers) - [E-commerce store lookup](https://gridrouter.io/capabilities/commerce.store_lookup): Platform, apps, product count and traffic estimates for an online store. (`commerce.store_lookup`, 0 providers) - [Email pattern](https://gridrouter.io/capabilities/email.pattern): The address format a domain uses, such as first.last. (`email.pattern`, 0 providers) - [Enrich a company](https://gridrouter.io/capabilities/company.enrich): Industry, headcount, location, founding year and links from a domain. (`company.enrich`, 0 providers) - [Enrich a person](https://gridrouter.io/capabilities/people.enrich): Current title, employer, seniority and history from an email or B2B profile URL (…/in/…). (`people.enrich`, 0 providers) - [Extract JSON](https://gridrouter.io/capabilities/ai.extract): A typed JSON object from messy text, validated against your schema. (`ai.extract`, 0 providers) - [Extract structured data](https://gridrouter.io/capabilities/web.extract): Typed fields from an article, product or company page. (`web.extract`, 0 providers) - [Fetch a page](https://gridrouter.io/capabilities/web.scrape): Rendered HTML or markdown for a URL, through anti-bot. (`web.scrape`, 0 providers) - [Find companies by technology](https://gridrouter.io/capabilities/technographics.search): Companies that run a given product, with first and last detection dates. (`technographics.search`, 0 providers) - [Find mobile number](https://gridrouter.io/capabilities/people.phone.find): A direct mobile from a B2B profile URL (…/in/…) or work email. (`people.phone.find`, 0 providers) - [Find work email](https://gridrouter.io/capabilities/people.email.find): A verified work email from a name and company domain. (`people.email.find`, 0 providers) - [Funding and investors](https://gridrouter.io/capabilities/company.funding): Rounds, amounts, dates and lead investors for a company. (`company.funding`, 0 providers) - [Geolocate an IP](https://gridrouter.io/capabilities/ip.geolocate): Country, region, city, ASN and connection type for an IP address. (`ip.geolocate`, 0 providers) - [Google ads transparency](https://gridrouter.io/capabilities/ads.google.search): Search, display and video ads a domain runs on Google. (`ads.google.search`, 0 providers) - [Google SERP](https://gridrouter.io/capabilities/serp.google.search): Organic results, features and positions for a keyword. (`serp.google.search`, 0 providers) - [Hiring activity](https://gridrouter.io/capabilities/signals.hiring): Open roles and hiring velocity by department. (`signals.hiring`, 0 providers) - [Identify a website visitor](https://gridrouter.io/capabilities/signals.visitor_id): The company, and where lawful the person, behind a website session. (`signals.visitor_id`, 0 providers) - [Inbox placement test](https://gridrouter.io/capabilities/deliverability.inbox_placement): Where a test message landed across mailbox providers: inbox, promotions or spam. (`deliverability.inbox_placement`, 0 providers) - [Intent topics](https://gridrouter.io/capabilities/signals.intent): Accounts researching a topic more than usual (surge), by topic and week. (`signals.intent`, 0 providers) - [IP to company](https://gridrouter.io/capabilities/ip.company_lookup): The company behind an IP address (reverse IP), with its domain. (`ip.company_lookup`, 0 providers) - [Job change](https://gridrouter.io/capabilities/signals.job_change): Has this person moved companies since you last checked. (`signals.job_change`, 0 providers) - [Keyword volume](https://gridrouter.io/capabilities/seo.keywords.volume): Monthly search volume, CPC and difficulty for keywords. (`seo.keywords.volume`, 0 providers) - [Meta ad library](https://gridrouter.io/capabilities/ads.meta.search): Active Facebook and Instagram ads by advertiser or keyword. (`ads.meta.search`, 0 providers) - [Model completion](https://gridrouter.io/capabilities/ai.complete): Any model through one endpoint, billed at the model's rate. (`ai.complete`, 0 providers) - [Officers and directors](https://gridrouter.io/capabilities/registry.officers): Directors, officers and significant controllers for a registered entity. (`registry.officers`, 0 providers) - [Phone line type](https://gridrouter.io/capabilities/phone.lookup): Line type, carrier and validity for any number. (`phone.lookup`, 0 providers) - [Place details](https://gridrouter.io/capabilities/places.details): Phone, website, hours and rating for one place. (`places.details`, 0 providers) - [Product and price search](https://gridrouter.io/capabilities/commerce.product_search): Products, prices and sellers from marketplaces and shopping results. (`commerce.product_search`, 0 providers) - [Registry company lookup](https://gridrouter.io/capabilities/registry.company_lookup): The official record for a company from a government or legal-entity registry. (`registry.company_lookup`, 0 providers) - [Registry filings](https://gridrouter.io/capabilities/registry.filings): Filings and statements lodged with a registry or regulator. (`registry.filings`, 0 providers) - [Resolve an identity](https://gridrouter.io/capabilities/people.identity.resolve): Link emails, phones, hashed identifiers and profiles that belong to one person. (`people.identity.resolve`, 0 providers) - [Sanctions and PEP screening](https://gridrouter.io/capabilities/compliance.sanctions.screen): Screen a person or company name against sanctions, PEP and watchlists. (`compliance.sanctions.screen`, 0 providers) - [Search companies](https://gridrouter.io/capabilities/company.search): Accounts by industry, size, location and technology. (`company.search`, 0 providers) - [Search funding rounds](https://gridrouter.io/capabilities/funding.rounds.search): Recent rounds by stage, amount, date and investor. (`funding.rounds.search`, 0 providers) - [Search job postings](https://gridrouter.io/capabilities/jobs.search): Open roles by title, location, company and date posted. (`jobs.search`, 0 providers) - [Search news](https://gridrouter.io/capabilities/news.search): Articles by keyword, entity, source and date. (`news.search`, 0 providers) - [Search people](https://gridrouter.io/capabilities/people.search): Contacts by title, seniority, company and location. (`people.search`, 0 providers) - [Search places](https://gridrouter.io/capabilities/places.search): Local businesses by category and area. (`places.search`, 0 providers) - [Send email](https://gridrouter.io/capabilities/sending.email.send): Send one message through a sending API, with delivery events. (`sending.email.send`, 0 providers) - [Social listening](https://gridrouter.io/capabilities/social.mentions.search): Posts that mention a brand, product or keyword across social platforms. (`social.mentions.search`, 0 providers) - [Social profiles from email](https://gridrouter.io/capabilities/social.profile.find): Public profile URLs tied to an email address. (`social.profile.find`, 0 providers) - [Software reviews](https://gridrouter.io/capabilities/reviews.software): Ratings and reviews for a software product. (`reviews.software`, 0 providers) - [Suppression check](https://gridrouter.io/capabilities/compliance.suppression.check): Has this address unsubscribed, bounced or opted out anywhere in your org. (`compliance.suppression.check`, 0 providers) - [Technology stack](https://gridrouter.io/capabilities/company.technographics): The tools a company runs, detected from its site and job posts. (`company.technographics`, 0 providers) - [TikTok ads](https://gridrouter.io/capabilities/ads.tiktok.search): Ads a brand runs on TikTok, from the commercial content library. (`ads.tiktok.search`, 0 providers) - [Trademarks and patents](https://gridrouter.io/capabilities/registry.trademarks): Trademark and patent records filed by a company. (`registry.trademarks`, 0 providers) - [Upsert CRM contact](https://gridrouter.io/capabilities/crm.contact.upsert): Create or update a contact, matched on email. (`crm.contact.upsert`, 0 providers) - [Verify email](https://gridrouter.io/capabilities/email.verify): Is this address deliverable, before you send to it. (`email.verify`, 0 providers) - [Web search](https://gridrouter.io/capabilities/web.search): Ranked pages for a natural-language query, with snippets. (`web.search`, 0 providers) - [Website traffic](https://gridrouter.io/capabilities/seo.traffic): Estimated visits, sources and engagement for a domain. (`seo.traffic`, 0 providers) ## Providers - [6sense](https://gridrouter.io/providers/6sense): Account identification, intent and enrichment APIs for customers. (6sense.com) - [ABN Lookup web services](https://gridrouter.io/providers/abn-lookup): Australian Business Register ABN Lookup web services: search by ABN, ACN or name (SOAP / HTTP GET/POST). (abr.business.gov.au) - [Abstract API](https://gridrouter.io/providers/abstract-api): Improve your contact rate and clean your lists with Abstract's industry-leading phone number validation API. (abstractapi.com) - [AccuRanker](https://gridrouter.io/providers/accuranker): Daily rank tracker with read API and MCP server. (accuranker.com) - [ActiveCampaign](https://gridrouter.io/providers/activecampaign): Marketing automation and CRM with a v3 REST API. (activecampaign.com) - [Adapt.io](https://gridrouter.io/providers/adapt-io): B2B contact and company data with email and phone credits and an API product. (adapt.io) - [Adbeat](https://gridrouter.io/providers/adbeat): Display, programmatic and native ad intelligence (web app, no public API found). (adbeat.com) - [AdSpy](https://gridrouter.io/providers/adspy): Searchable database of Facebook and Instagram ads (no public API). (adspy.com) - [Adthena](https://gridrouter.io/providers/adthena): Paid search competitive intelligence and brand protection; API for customers. (adthena.com) - [Advan Research](https://gridrouter.io/providers/advan): Foot-traffic and POI datasets (Patterns+, FIT platform); dataset delivery. (advanresearch.com) - [Adyntel](https://gridrouter.io/providers/adyntel): Ad intelligence API for professional network, Meta and Google ads. (adyntel.com) - [Adzuna](https://gridrouter.io/providers/adzuna): Job search engine with a developer API for job listings and salary data. (adzuna.com) - [AeroLeads](https://gridrouter.io/providers/aeroleads): Pay-once B2B email and phone data credits. (aeroleads.com) - [Affinity](https://gridrouter.io/providers/affinity): Relationship intelligence CRM for dealmaking teams with a REST API. (affinity.co) - [Ahrefs API](https://gridrouter.io/providers/ahrefs): Backlink and keyword data on the Enterprise plan. (ahrefs.com) - [AI Ark](https://gridrouter.io/providers/ai-ark): People and company search API with async email finding and reverse lookup. (ai-ark.com) - [Albacross](https://gridrouter.io/providers/albacross): B2B website visitor identification and intent platform. (albacross.com) - [Alpha Vantage](https://gridrouter.io/providers/alpha-vantage): Stock market and fundamentals API (company overview, statements, earnings) with free and premium keys. (alphavantage.co) - [Amazon SES](https://gridrouter.io/providers/amazon-ses): AWS Simple Email Service for high-volume sending. (aws.amazon.com) - [Amplemarket](https://gridrouter.io/providers/amplemarket): AI sales platform with prospect data, sequences and a documented API. (amplemarket.com) - [Anthropic API](https://gridrouter.io/providers/anthropic): Claude models via API (also routable through OpenRouter). (anthropic.com) - [Anymail Finder](https://gridrouter.io/providers/anymail-finder): Verified email finder with an OpenAPI spec and MCP. (anymailfinder.com) - [Apify](https://gridrouter.io/providers/apify): Marketplace of scrapers (Actors) with a run-and-fetch API. (apify.com) - [Apollo](https://gridrouter.io/providers/apollo): A large contact database with people and company search. (apollo.io) - [Apple Maps Server API](https://gridrouter.io/providers/apple-maps-server): Apple's server-side place search, geocoding and place lookup API. (developer.apple.com) - [AroundDeal](https://gridrouter.io/providers/arounddeal): Publishes 4 APIs on RapidAPI: Company Enrichment API, People Enrichment API, Contact Verification API, Resume Enrichment API. (arounddeal.com) - [Ashby Job Postings API](https://gridrouter.io/providers/ashby): Public Job Postings API exposing each Ashby customer's published postings. (ashbyhq.com) - [Attio](https://gridrouter.io/providers/attio): CRM writes over your own OAuth connection. (attio.com) - [Audience Acuity](https://gridrouter.io/providers/audience-acuity): Identity infrastructure provider (sales-led). (audienceacuity.com) - [Aviato](https://gridrouter.io/providers/aviato): People and company data API for investors and GTM. (aviato.co) - [Awario](https://gridrouter.io/providers/awario): Social listening and brand monitoring tool with API access on higher plans. (awario.com) - [B2B Ad Library](https://gridrouter.io/providers/linkedin-ad-library): Public ad search on professional network; no public API found. (linkedin.com) - [B2B Marketing API](https://gridrouter.io/providers/linkedin-marketing-api): professional network Advertising, Community Management and Audience Insights APIs (approval required). (learn.microsoft.com) - [Bazaarvoice](https://gridrouter.io/providers/bazaarvoice): Product ratings, reviews and UGC network with the Conversations API. (bazaarvoice.com) - [BetterContact](https://gridrouter.io/providers/bettercontact): Waterfall over 20+ phone and email providers, async API. (bettercontact.rocks) - [BigPicture](https://gridrouter.io/providers/bigpicture): Company enrichment API: lookup by domain, company search, name-to-domain and IP-to-company. (bigpicture.io) - [BigSpy](https://gridrouter.io/providers/bigspy): Ad spy tool for Facebook, Instagram, TikTok, YouTube and AdMob ads. (bigspy.com) - [Birdeye](https://gridrouter.io/providers/birdeye): Reputation, reviews and listings platform for multi-location businesses; partner API. (birdeye.com) - [Blacklist Alliance](https://gridrouter.io/providers/blacklist-alliance): TCPA litigator and DNC scrubbing. (blacklistalliance.com) - [Bombora](https://gridrouter.io/providers/bombora): Company Surge intent data from a publisher co-op. (bombora.com) - [BounceBan](https://gridrouter.io/providers/bounceban): Verification that resolves catch-all domains. (bounceban.com) - [Bouncer](https://gridrouter.io/providers/bouncer): Email verification from $8 per 1,000. (usebouncer.com) - [Brand.dev](https://gridrouter.io/providers/brand-dev): Brand, logo and company data by domain, plus page scraping. (brand.dev) - [Brand24](https://gridrouter.io/providers/brand24): Social listening tool; API and MCP available as a paid add-on. (brand24.com) - [Brandwatch](https://gridrouter.io/providers/brandwatch): Consumer intelligence and social listening with the Consumer Research API. (brandwatch.com) - [Brave Search API](https://gridrouter.io/providers/brave-search-api): Independent web index search API (web, news, images, local, LLM context). (brave.com) - [Brevo](https://gridrouter.io/providers/brevo): Email, SMS and CRM platform (formerly Sendinblue) with a v3 API. (brevo.com) - [Bright Data](https://gridrouter.io/providers/bright-data): Scraper, SERP, unlocker and dataset APIs plus proxies. (brightdata.com) - [BrightLocal](https://gridrouter.io/providers/brightlocal): Local SEO platform (rank tracking, citations, reviews) with API solutions. (brightlocal.com) - [Brønnøysund Register Centre (Enhetsregisteret)](https://gridrouter.io/providers/brreg): Norwegian Central Coordinating Register open-data API: entities, sub-entities and roles. (brreg.no) - [Browserbase](https://gridrouter.io/providers/browserbase): Cloud browser infrastructure for agents with Sessions, Search and Fetch APIs. (browserbase.com) - [Browserless](https://gridrouter.io/providers/browserless): Hosted headless Chrome/Firefox with REST endpoints and BrowserQL. (browserless.io) - [BuiltWith](https://gridrouter.io/providers/builtwith): Technology lookup for any website, with historical usage. (builtwith.com) - [Captain Verify](https://gridrouter.io/providers/captain-verify): French email verification and HLR mobile lookup service with APIs. (captainverify.com) - [CB Insights](https://gridrouter.io/providers/cb-insights): Market intelligence API v2: firmographics, funding and investment rounds, Mosaic scores, revenue. (cbinsights.com) - [Champify](https://gridrouter.io/providers/champify): Champion job-change tracking and first-party relationship intelligence in Salesforce. (champify.io) - [Clay](https://gridrouter.io/providers/clay): Enrichment orchestration; no public data API as a source. (clay.com) - [Clearout](https://gridrouter.io/providers/clearout): Email verifier and email finder with instant and bulk APIs. (clearout.io) - [Clodura.AI](https://gridrouter.io/providers/clodura): India-based B2B contact and company data platform with credits. (clodura.ai) - [Close](https://gridrouter.io/providers/close): Sales CRM with calling and email, REST API. (close.com) - [Cognism](https://gridrouter.io/providers/cognism): Compliance-first B2B contact data with verified mobiles. (cognism.com) - [Cohere](https://gridrouter.io/providers/cohere): Command, Embed, Rerank and Parse model APIs for enterprise. (cohere.com) - [Common Room](https://gridrouter.io/providers/common-room): Buyer signals from community, product and web activity. (commonroom.io) - [Companies House](https://gridrouter.io/providers/companies-house): UK register of companies: company profiles, officers, filing history, charges and PSC via REST. (company-information.service.gov.uk) - [CompanyEnrich](https://gridrouter.io/providers/companyenrich): Real-time company enrichment and search with an MCP server. (companyenrich.com) - [ComplyAdvantage](https://gridrouter.io/providers/complyadvantage): Sanctions, PEP and adverse-media screening API with self-service Starter plan. (complyadvantage.com) - [ContactOut](https://gridrouter.io/providers/contactout): Personal and work contact details from profile URLs. (contactout.com) - [Contify](https://gridrouter.io/providers/contify): Market and competitive intelligence platform with a Business News API. (contify.com) - [Copper](https://gridrouter.io/providers/copper): Google Workspace CRM with a developer API for people, leads and deals. (copper.com) - [Coresignal](https://gridrouter.io/providers/coresignal): Employee, company and job-posting records refreshed weekly. (coresignal.com) - [Crawlbase](https://gridrouter.io/providers/crawlbase): Crawling API (formerly ProxyCrawl) with pay-as-you-go per-request pricing. (crawlbase.com) - [CreatorIQ](https://gridrouter.io/providers/creatoriq): Enterprise creator marketing platform (API not publicly documented). (creatoriq.com) - [Creditsafe](https://gridrouter.io/providers/creditsafe): Global business credit data: Connect API for company search, credit reports, KYC and monitoring. (creditsafe.com) - [Crossbeam](https://gridrouter.io/providers/crossbeam): Partner ecosystem data: account and lead overlaps with partners via OAuth API. (crossbeam.com) - [Crunchbase](https://gridrouter.io/providers/crunchbase): Funding rounds, investors and company profiles. (crunchbase.com) - [Crustdata](https://gridrouter.io/providers/crustdata): Real-time people, company, hiring and post data. (crustdata.com) - [Currents API](https://gridrouter.io/providers/currents-api): Latest news and search API with free daily quota. (currentsapi.services) - [Customers.ai](https://gridrouter.io/providers/customers-ai): Website visitor identification (X-Ray pixel) and ecommerce email marketing. (customers.ai) - [Data Axle](https://gridrouter.io/providers/data-axle): US/Canada business (Places) and consumer (People) data via Search and Match APIs. (data-axle.com) - [Data Monster Collection](https://gridrouter.io/providers/data-monster-collection): Social Media Ad Library. (rapidapi.com) - [Data365](https://gridrouter.io/providers/data365): Social media data API (profiles, posts, comments) on credit subscriptions. (data365.co) - [DataForSEO](https://gridrouter.io/providers/dataforseo): SERP, keyword, backlink and local data at wholesale rates. (dataforseo.com) - [Datagma](https://gridrouter.io/providers/datagma): Phones and emails with API access on every paid plan. (datagma.com) - [Datanyze](https://gridrouter.io/providers/datanyze): Contact data Chrome extension on a credit plan; no public API found. (datanyze.com) - [dataplor](https://gridrouter.io/providers/dataplor): Global POI and foot-traffic data with emphasis on hard-to-cover markets. (dataplor.com) - [Datashake](https://gridrouter.io/providers/datashake): Unified review and social data API across 150+ sources. (datashake.com) - [DataWeave](https://gridrouter.io/providers/dataweave): AI-driven digital shelf, pricing and assortment intelligence for retailers and brands. (dataweave.com) - [Dealfront (Leadfeeder)](https://gridrouter.io/providers/dealfront): European website visitor identification and B2B data platform (Leadfeeder + Echobot). (dealfront.com) - [Dealroom](https://gridrouter.io/providers/dealroom): Startup, investor and funding-round data API (5M+ companies) with an MCP server. (dealroom.co) - [DeBounce](https://gridrouter.io/providers/debounce): Email validation API with bulk list cleaning and email-to-profile append. (debounce.com) - [Decodo (formerly Smartproxy)](https://gridrouter.io/providers/decodo): Proxies plus Web Scraping API, Site Unblocker and Fast Search API. (decodo.com) - [DeepSeek API](https://gridrouter.io/providers/deepseek): OpenAI- and Anthropic-compatible API for DeepSeek models with peak/off-peak pricing. (deepseek.com) - [Demandbase](https://gridrouter.io/providers/demandbase): ABM platform with B2B data, intent and export APIs plus an MCP server. (demandbase.com) - [DetectZeStack](https://gridrouter.io/providers/detectzestack): Website tech detection + change monitoring API. (detectzestack.com) - [Didomi](https://gridrouter.io/providers/didomi): Consent and preference management with a platform API. (didomi.io) - [Diffbot](https://gridrouter.io/providers/diffbot): Knowledge graph and structured extraction from any page. (diffbot.com) - [dilisense](https://gridrouter.io/providers/dilisense): Sanctions, PEP and criminal-list screening API with self-serve per-call pricing. (dilisense.com) - [dmarcian](https://gridrouter.io/providers/dmarcian): DMARC deployment and reporting; API access on paid plans. (dmarcian.com) - [DNC.com](https://gridrouter.io/providers/dnc-com): DNC, litigator and reassigned-number scrubbing APIs (DNCScrub). (dnc.com) - [dodocr7](https://gridrouter.io/providers/dodocr7): Api that scrape all reviews and ratings of any company or any business you searched from google. (rapidapi.com) - [Dropcontact](https://gridrouter.io/providers/dropcontact): GDPR-focused B2B email enrichment with an async batch API. (dropcontact.com) - [Dun & Bradstreet Direct+](https://gridrouter.io/providers/dun-bradstreet): D&B Direct+ APIs: identity resolution, search, enrichment data blocks, batch and monitoring. (dnb.com) - [EasyDMARC](https://gridrouter.io/providers/easydmarc): DMARC monitoring and DNS record checks with a REST API. (easydmarc.com) - [Ekata (Mastercard Identity)](https://gridrouter.io/providers/ekata): Mastercard identity verification data for fraud decisions. (ekata.com) - [Elastic Email](https://gridrouter.io/providers/elastic-email): Email marketing and sending API (v4). (elasticemail.com) - [Email Checker](https://gridrouter.io/providers/email-checker): Use our email verification API to check email addresses in real-time. (emailchecker.com) - [Email Hippo](https://gridrouter.io/providers/email-hippo): Email validation, intelligence and fraud-risk APIs plus bulk list cleaning. (emailhippo.com) - [Emailable](https://gridrouter.io/providers/emailable): Email verification API with SOC 2 Type II. (emailable.com) - [EmailListVerify](https://gridrouter.io/providers/emaillistverify): Email verification API and bulk list cleaning with finder tools. (emaillistverify.com) - [Enlyft](https://gridrouter.io/providers/enlyft): Technographic and account intelligence for B2B sales; no public API documentation found. (enlyft.com) - [Enrich Layer](https://gridrouter.io/providers/enrich-layer): Pay-as-you-go profile and company enrichment API. (enrichlayer.com) - [Enrow](https://gridrouter.io/providers/enrow): Asynchronous email finder, email verifier and phone finder API with webhooks. (enrow.io) - [EnsembleData](https://gridrouter.io/providers/ensembledata): Real-time social media scraping API (TikTok, Instagram, YouTube, Reddit, X, more). (ensembledata.com) - [EODHD](https://gridrouter.io/providers/eodhd): EOD Historical Data: global prices and fundamentals API with per-minute and daily call limits and MCP. (eodhd.com) - [EPO Open Patent Services](https://gridrouter.io/providers/epo-ops): European Patent Office OPS: RESTful access to bibliographic, legal status, full-text and image patent data. (epo.org) - [Everonu](https://gridrouter.io/providers/everonu): Company & contact enrichment API with per-field confidence scores and evidence trails. (enrichforge.com) - [Exa](https://gridrouter.io/providers/exa): Neural web search and page contents for agents. (exa.ai) - [Expandi](https://gridrouter.io/providers/expandi): professional network and email outreach automation. (expandi.io) - [Explorium](https://gridrouter.io/providers/explorium): AgentSource API: business match, firmographics, technographics, funding and prospect enrichment. (explorium.ai) - [Fantastic Jobs](https://gridrouter.io/providers/fantastic-jobs): ATS and job board postings API (55 ATS platforms, professional network, Wellfound, Y Combinator), refreshed hourly. (fantastic.jobs) - [Fast APIs](https://gridrouter.io/providers/fast-apis): 100% Genuine Results. (rapidapi.com) - [FCC Reassigned Numbers Database](https://gridrouter.io/providers/reassigned-numbers-database): FCC database to check whether a US number was permanently disconnected since a date. (reassigned.us) - [Feefo](https://gridrouter.io/providers/feefo): Verified customer reviews platform (6,500+ brands); API details unverified. (feefo.com) - [Fiber AI](https://gridrouter.io/providers/fiber-ai): People, company and search API with an OpenAPI spec. (fiber.ai) - [Financial Modeling Prep](https://gridrouter.io/providers/financial-modeling-prep): Financial statements, company profiles, screener and market data API with an apikey parameter. (financialmodelingprep.com) - [FindThatLead](https://gridrouter.io/providers/findthatlead): Email and social profile finder with prospecting tools. (findthatlead.com) - [Findymail](https://gridrouter.io/providers/findymail): Email finder tuned for low bounce rates on B2B lists. (findymail.com) - [Finnhub](https://gridrouter.io/providers/finnhub): Stock, fundamentals and alternative data API: company profiles, financials as reported, SEC and global filings. (finnhub.io) - [Firecrawl](https://gridrouter.io/providers/firecrawl): Scrape, crawl, map and search the web into LLM-ready data. (firecrawl.dev) - [Fireworks AI](https://gridrouter.io/providers/fireworks-ai): Serverless and on-demand inference and fine-tuning for open models. (fireworks.ai) - [FlyBy APIs](https://gridrouter.io/providers/flyby-apis): AI scrape and data extract any website with JavaScript rendering (headless browser) or fast HTTP, rotating datacenter/ISP proxies, Cloudflare & anti-b. (rapidapi.com) - [Folderly](https://gridrouter.io/providers/folderly): Email deliverability management and placement tests. (folderly.com) - [folk](https://gridrouter.io/providers/folk): Relationship CRM with a REST API for people, companies and deals. (folk.app) - [Foreplay](https://gridrouter.io/providers/foreplay): Ad creative library (200M+ ads) with a credit-based public API and MCP. (foreplay.co) - [Foursquare Places](https://gridrouter.io/providers/foursquare): Global POI search and place details API. (foursquare.com) - [Freshsales](https://gridrouter.io/providers/freshsales): Freshworks sales CRM with contact upsert and bulk upsert APIs. (freshworks.com) - [FullContact](https://gridrouter.io/providers/fullcontact): Identity resolution and person enrichment platform with an MCP server. (fullcontact.com) - [FullEnrich](https://gridrouter.io/providers/fullenrich): Waterfall email and phone enrichment across many sources. (fullenrich.com) - [G2 Buyer Intent](https://gridrouter.io/providers/g2): Buyer intent from G2 category and profile research. (g2.com) - [GDELT Project](https://gridrouter.io/providers/gdelt): Open global news monitoring database with a free DOC 2.0 search API. (gdeltproject.org) - [Geoapify](https://gridrouter.io/providers/geoapify): Places, geocoding and routing APIs built on OpenStreetMap data. (geoapify.com) - [GLEIF](https://gridrouter.io/providers/gleif): Global LEI index API: legal entity reference data, parent/child relationships and BIC/ISIN mappings. (gleif.org) - [Global Database](https://gridrouter.io/providers/global-database): Company, financial and KYB data API across UK/EU and global companies. (globaldatabase.com) - [GlockApps](https://gridrouter.io/providers/glockapps): Inbox placement testing, DMARC analytics and an API. (glockapps.com) - [GNews](https://gridrouter.io/providers/gnews): Search and top-headlines news API. (gnews.io) - [Google Ads API](https://gridrouter.io/providers/google-ads-api): Google Ads account API, including Keyword Planner historical search volume. (developers.google.com) - [Google Ads Transparency Center](https://gridrouter.io/providers/google-ads-transparency): Public ad search by advertiser; no official API. (adstransparency.google.com) - [Google Business Profile APIs](https://gridrouter.io/providers/google-business-profile-api): Manage reviews and listings for Business Profiles you own (OAuth 2.0). (developers.google.com) - [Google Custom Search JSON API](https://gridrouter.io/providers/google-custom-search): Google's Programmable Search JSON API; closed to new customers, ends 2027-01-01. (developers.google.com) - [Google Places](https://gridrouter.io/providers/google-places): Place search and details from Google Maps. (developers.google.com) - [Grata](https://gridrouter.io/providers/grata): Private company search for dealmakers: Search, Similar, Enrichment and List APIs. (grata.com) - [Greenhouse Job Board API](https://gridrouter.io/providers/greenhouse): Public Job Board API exposing each Greenhouse customer's open postings. (greenhouse.io) - [GroqCloud](https://gridrouter.io/providers/groq): Low-latency inference API for open models (OpenAI-compatible). (groq.com) - [Gryphon.ai](https://gridrouter.io/providers/gryphon-ai): Real-time call compliance (DNC/TCPA) and conversation intelligence. (gryphon.ai) - [Handelsregister (Registerportal der Länder)](https://gridrouter.io/providers/handelsregister): German joint register portal of the federal states (commercial register search); no public API found. (handelsregister.de) - [Harmonic](https://gridrouter.io/providers/harmonic): Startup and company discovery data with a customer API. (harmonic.ai) - [HarvestAPI](https://gridrouter.io/providers/harvestapi): Professional-network profile, company and post scraping API. (harvest-api.com) - [HERE Geocoding & Search](https://gridrouter.io/providers/here): HERE Geocoding and Search API v7: discover, geocode, autosuggest and POI lookup. (here.com) - [Hermann Samimi](https://gridrouter.io/providers/hermann-samimi): Real-time job search across professional network, Indeed, Glassdoor and more. (rapidapi.com) - [HeyReach](https://gridrouter.io/providers/heyreach): professional network outreach automation across many sender accounts, with an API. (heyreach.io) - [HG Insights](https://gridrouter.io/providers/hg-insights): Enterprise technographic and IT spend data. (hginsights.com) - [hireEZ](https://gridrouter.io/providers/hireez): Agentic AI recruiting platform with sourcing on top of an ATS. (hireez.com) - [HLR Lookups](https://gridrouter.io/providers/hlr-lookups): HLR, MNP and number-type lookup API for mobile connectivity and portability. (hlr-lookups.com) - [HubSpot](https://gridrouter.io/providers/hubspot): CRM writes over your own OAuth connection. (hubspot.com) - [Hunter](https://gridrouter.io/providers/hunter): Email finder, verifier and domain pattern search. (hunter.io) - [HypeAuditor](https://gridrouter.io/providers/hypeauditor): Influencer analytics with Discovery, Report, Suggester and Lists APIs. (hypeauditor.com) - [Hyperbrowser](https://gridrouter.io/providers/hyperbrowser): Cloud browsers, sandboxes and scrape/crawl/extract APIs for AI agents. (hyperbrowser.ai) - [Icypeas](https://gridrouter.io/providers/icypeas): Low-cost email finder and verifier for large lists. (icypeas.com) - [Import.io](https://gridrouter.io/providers/import-io): Managed web data extraction platform with extractors, API and webhooks. (import.io) - [Influencers Club](https://gridrouter.io/providers/influencers-club): Creator discovery and enrichment across 340M+ profiles. (influencers.club) - [Infobel Pro](https://gridrouter.io/providers/infobel): Global business listings database with BizSearch API (search, counts, records). (infobelpro.com) - [INSEE API Sirene](https://gridrouter.io/providers/insee-sirene): French Sirene business register API (SIREN/SIRET units) from INSEE's API catalogue. (insee.fr) - [Insightly](https://gridrouter.io/providers/insightly): CRM with a v3.1 REST API and published daily request quotas. (insightly.com) - [Instantly](https://gridrouter.io/providers/instantly): Add leads to campaigns with your own API key. (instantly.ai) - [Intentsify](https://gridrouter.io/providers/intentsify): B2B buyer intent data, visitor resolution and activation platform with MCP. (intentsify.io) - [Intrinio](https://gridrouter.io/providers/intrinio): Financial data API: fundamentals, prices and company data with per-second limits and bulk downloads. (intrinio.com) - [inUtil Labs](https://gridrouter.io/providers/inutil-labs): Verify phone numbers are valid on your apps. (inutil-labs.com) - [ip-api](https://gridrouter.io/providers/ip-api): IP geolocation API with a free non-commercial endpoint and paid pro service. (ip-api.com) - [IP2Location.io](https://gridrouter.io/providers/ip2location): IP geolocation and proxy detection API from IP2Location. (ip2location.io) - [ipapi.co](https://gridrouter.io/providers/ipapi-co): IP address location API with monthly request plans. (ipapi.co) - [ipdata](https://gridrouter.io/providers/ipdata): IP geolocation, threat and company data API with EU endpoint. (ipdata.co) - [IPGeolocation.io](https://gridrouter.io/providers/ipgeolocation-io): IP geolocation, bulk lookup and IP security API. (ipgeolocation.io) - [IPinfo](https://gridrouter.io/providers/ipinfo): IP geolocation, ASN, privacy detection and IP-to-company data via API and downloads. (ipinfo.io) - [Ipregistry](https://gridrouter.io/providers/ipregistry): IP geolocation, threat and user-agent API with batch lookups. (ipregistry.co) - [ipstack](https://gridrouter.io/providers/ipstack): APILayer's IP geolocation API. (ipstack.com) - [jaypat87 (JobScanner)](https://gridrouter.io/providers/jaypat87): Publishes 2 APIs on RapidAPI: Job Search, professional network Jobs Search. (jobscanner.org) - [Jina AI](https://gridrouter.io/providers/jina-ai): Reader (r.jina.ai), Search (s.jina.ai), embeddings and reranker APIs. (jina.ai) - [JobsPikr](https://gridrouter.io/providers/jobspikr): Job postings data feeds, datasets and Job Search API. (jobspikr.com) - [Jornaya (Verisk)](https://gridrouter.io/providers/jornaya): Consumer journey and consent (LeadiD) data for TCPA compliance. (jornaya.com) - [Judge.me](https://gridrouter.io/providers/judge-me): Shopify product reviews app with a developer API; $15/month max. (judge.me) - [Jungle Scout API](https://gridrouter.io/providers/jungle-scout): Amazon product database, keyword and sales-estimate API for sellers. (junglescout.com) - [JustSERP](https://gridrouter.io/providers/justserp): Test our API with 500 free API calls! Running reliably for 4+ years. (justserp.com) - [Kagi Search API](https://gridrouter.io/providers/kagi): Premium ad-free search, Enrichment (web/news), Summarizer and FastGPT APIs. (kagi.com) - [Kaspr](https://gridrouter.io/providers/kaspr): European contact data from profile URLs; API on request. (kaspr.io) - [Keap](https://gridrouter.io/providers/keap): Small-business CRM and marketing automation (formerly Infusionsoft). (keap.com) - [Keepa](https://gridrouter.io/providers/keepa): Amazon product data and price history API metered by tokens per minute. (keepa.com) - [Kendo](https://gridrouter.io/providers/kendo): Email and phone finder, domain search and verification with Kendo-API. (kendoemailapp.com) - [Ketch](https://gridrouter.io/providers/ketch): Consent and permissioning platform with an API reference. (ketch.com) - [Keyword.com](https://gridrouter.io/providers/keyword-com): Rank tracker and AI visibility tool with rank tracker API, SERP API and MCP. (keyword.com) - [Keywords Everywhere](https://gridrouter.io/providers/keywords-everywhere): Keyword volume, CPC, competition and trend API on prepaid credits. (keywordseverywhere.com) - [Kickbox](https://gridrouter.io/providers/kickbox): Email verification priced per verification, 100 free. (kickbox.com) - [KickFire](https://gridrouter.io/providers/kickfire): IP-to-company and website visitor intelligence APIs (FoundryCo). (kickfire.com) - [Kitt](https://gridrouter.io/providers/kitt): Email finder and catch-all email verifier with pay-as-you-go API access. (trykitt.ai) - [Klenty](https://gridrouter.io/providers/klenty): Sales engagement cadences with a REST API to add prospects and start cadences. (klenty.com) - [Koala](https://gridrouter.io/providers/koala): Product and website intent for sales teams. (getkoala.com) - [KVK API](https://gridrouter.io/providers/kvk): Dutch Chamber of Commerce Business Register APIs: search, basic profile, branch profile, trade names. (kvk.nl) - [Kyckr](https://gridrouter.io/providers/kyckr): Company data from official registries worldwide via API: search, KYB checks and register documents. (kyckr.com) - [La Growth Machine](https://gridrouter.io/providers/la-growth-machine): Multichannel professional network and email prospecting sequences. (lagrowthmachine.com) - [Lead Forensics](https://gridrouter.io/providers/lead-forensics): UK B2B website visitor identification software. (leadforensics.com) - [Lead411](https://gridrouter.io/providers/lead411): B2B contact data with verified emails, direct dials and intent. (lead411.com) - [Leadinfo](https://gridrouter.io/providers/leadinfo): Dutch B2B website visitor identification platform. (leadinfo.com) - [LeadIQ](https://gridrouter.io/providers/leadiq): Prospecting data with a GraphQL API and MCP connector for people and company search. (leadiq.com) - [LeadMagic](https://gridrouter.io/providers/leadmagic): Email, mobile, job-change and ads data on one credit balance. (leadmagic.io) - [Leadsforge](https://gridrouter.io/providers/leadsforge): AI lead search and enrichment with credits, from the Salesforge team. (leadsforge.ai) - [lemlist](https://gridrouter.io/providers/lemlist): Multichannel sequences with a lead and enrichment API. (lemlist.com) - [Lever Postings API](https://gridrouter.io/providers/lever): Public Postings API listing each Lever customer's published job postings. (lever.co) - [Linkup](https://gridrouter.io/providers/linkup): Web search and deep research API priced per request. (linkup.so) - [LiveRamp](https://gridrouter.io/providers/liveramp): Identity resolution (AbiliTec, RampID), clean rooms and activation APIs. (liveramp.com) - [Loops](https://gridrouter.io/providers/loops): Email platform for SaaS with a transactional and contacts API. (loops.so) - [Loqate](https://gridrouter.io/providers/loqate): GBG's address, email and phone validation APIs. (loqate.com) - [Lusha](https://gridrouter.io/providers/lusha): Contact and company data with direct dials. (lusha.com) - [Mahmudul Hasan](https://gridrouter.io/providers/mahmudul-hasan): Access detailed insights into Google ads, including advertiser metadata, creative content (text, images, videos), and campaign timelines. (rapidapi.com) - [Mail-tester](https://gridrouter.io/providers/mail-tester): Spam score testing with a JSON API. (mail-tester.com) - [mailboxlayer](https://gridrouter.io/providers/mailboxlayer): Simple and powerful email verification JSON API using SMTP, typo checks, syntax validation, and free and disposable provider filtering. (mailboxlayer.com) - [Mailchimp Transactional (Mandrill)](https://gridrouter.io/providers/mandrill): Mailchimp's transactional email API, sold in blocks. (mandrillapp.com) - [MailerCheck](https://gridrouter.io/providers/mailercheck): Email verification and list cleaning tool with a REST API. (mailercheck.com) - [MailerSend](https://gridrouter.io/providers/mailersend): Transactional email and SMS API with published per-endpoint limits. (mailersend.com) - [mailfloss](https://gridrouter.io/providers/mailfloss): Automated email list cleaning connected to email platforms, with a real-time API. (mailfloss.com) - [Mailgun](https://gridrouter.io/providers/mailgun): Sinch's transactional email API with US and EU regions. (mailgun.com) - [Mailjet](https://gridrouter.io/providers/mailjet): Sinch's email sending and marketing API. (mailjet.com) - [MailReach](https://gridrouter.io/providers/mailreach): Email warmup and spam tester with an API and MCP. (mailreach.co) - [Mailshake](https://gridrouter.io/providers/mailshake): Cold email and sales engagement with a quota-unit REST API. (mailshake.com) - [Majestic](https://gridrouter.io/providers/majestic): Backlink index (Trust Flow / Citation Flow) API. (majestic.com) - [Mangools](https://gridrouter.io/providers/mangools): SEO suite (KWFinder, SERPWatcher, LinkMiner, SiteProfiler) with an API. (mangools.com) - [Mapbox Search](https://gridrouter.io/providers/mapbox): Mapbox Search Box API: POI/address suggest, retrieve, forward and category search. (mapbox.com) - [Massive (formerly Polygon.io)](https://gridrouter.io/providers/massive): Market data APIs for stocks, options and partner datasets; Stocks Basic free at 5 calls/minute. (massive.com) - [MaxMind GeoIP](https://gridrouter.io/providers/maxmind): GeoIP Country, City Plus and Insights web services and databases. (maxmind.com) - [MediaRadar](https://gridrouter.io/providers/mediaradar): Advertising spend and creative intelligence across 30+ media channels. (mediaradar.com) - [mediastack](https://gridrouter.io/providers/mediastack): APILayer's live and historical news API. (mediastack.com) - [Melissa](https://gridrouter.io/providers/melissa): Global phone, email and address verification web services. (melissa.com) - [Meltwater](https://gridrouter.io/providers/meltwater): Media, social and consumer intelligence suite with a customer API. (meltwater.com) - [Mention](https://gridrouter.io/providers/mention): Brand monitoring and social listening with a REST API (OAuth2). (mention.com) - [Meta Ad Library API](https://gridrouter.io/providers/meta-ad-library): Official ads archive API for political/issue ads and EU-delivered ads. (facebook.com) - [Microsoft Advertising API](https://gridrouter.io/providers/microsoft-advertising-api): Bing Ads API for managing your own Microsoft Advertising accounts. (learn.microsoft.com) - [Middesk](https://gridrouter.io/providers/middesk): US business verification (KYB) API with registrations, TIN and sanctions checks. (middesk.com) - [MillionVerifier](https://gridrouter.io/providers/millionverifier): High-throughput bulk email verification. (millionverifier.com) - [Minelead](https://gridrouter.io/providers/minelead): Email finder, domain search and validator with API. (minelead.io) - [Mistral AI API](https://gridrouter.io/providers/mistral-ai): La Plateforme API for Mistral models: chat, embeddings, OCR and agents. (mistral.ai) - [Modash](https://gridrouter.io/providers/modash): Influencer discovery platform with Discovery and Raw data APIs. (modash.io) - [monday CRM](https://gridrouter.io/providers/monday-crm): monday.com CRM on the monday GraphQL platform API. (monday.com) - [Moody's Orbis](https://gridrouter.io/providers/moodys-orbis): Orbis (formerly Bureau van Dijk) global private and listed company data; no self-serve API found. (moodys.com) - [Moz API](https://gridrouter.io/providers/moz): Domain Authority, links and keyword data from $20/mo. (moz.com) - [Muck Rack](https://gridrouter.io/providers/muck-rack): PR platform with journalist database and media monitoring; API is a Premier add-on. (muckrack.com) - [MxToolbox](https://gridrouter.io/providers/mxtoolbox): DNS, MX and blacklist lookups via REST API. (mxtoolbox.com) - [National Do Not Call Registry (FTC)](https://gridrouter.io/providers/national-dnc-registry): FTC telemarketer access to the National DNC Registry by area code (SAN). (telemarketing.donotcall.gov) - [NeverBounce](https://gridrouter.io/providers/neverbounce): Email verification, pay-as-you-go or monthly. (neverbounce.com) - [NewsAPI.ai (Event Registry)](https://gridrouter.io/providers/event-registry): News articles and events API with concept tagging and text analytics. (newsapi.ai) - [NewsAPI.org](https://gridrouter.io/providers/newsapi): News search and top-headlines API over worldwide sources. (newsapi.org) - [NewsData.io](https://gridrouter.io/providers/newsdata-io): Latest, archive, crypto and market news API with WebSocket streaming. (newsdata.io) - [Nightwatch](https://gridrouter.io/providers/nightwatch): Rank tracking and SEO reporting; API on Agency plan and above. (nightwatch.io) - [Nimble](https://gridrouter.io/providers/nimble): Web search, extract, crawl, map and templated structured-data APIs. (nimbleway.com) - [North Data](https://gridrouter.io/providers/northdata): European company register search engine with a Data API for companies, persons, publications and financials. (northdata.com) - [numlookupapi](https://gridrouter.io/providers/numlookupapi): Phone number validation and carrier lookup API with an MCP server. (numlookupapi.com) - [numverify](https://gridrouter.io/providers/numverify): Phone number validation API from apilayer. (numverify.com) - [Nutshell](https://gridrouter.io/providers/nutshell): SMB CRM with REST and JSON-RPC APIs on all plans. (nutshell.com) - [Nymblr](https://gridrouter.io/providers/nymblr): B2B contact data provider; site unreachable when checked. (nymblr.com) - [Nymeria](https://gridrouter.io/providers/nymeria): Person and company enrichment and search API with emails and phones. (nymeria.io) - [Ocean.io](https://gridrouter.io/providers/ocean-io): Lookalike company search with waterfall contact enrichment. (ocean.io) - [Octolens](https://gridrouter.io/providers/octolens): AI-filtered social listening for B2B brands with API, webhooks and MCP. (octolens.com) - [Olostep](https://gridrouter.io/providers/olostep): Web scraping, crawling, batch and answers API for AI agents. (olostep.com) - [OneTrust](https://gridrouter.io/providers/onetrust): Privacy, consent and preference management platform with APIs. (onetrust.com) - [OpenAI API](https://gridrouter.io/providers/openai): GPT models for completion, extraction and embeddings. (openai.com) - [OpenCorporates](https://gridrouter.io/providers/opencorporates): Open database of companies from official registers worldwide; REST API for companies, officers and filings. (opencorporates.com) - [Openmart](https://gridrouter.io/providers/openmart): Local business leads database with an API. (openmart.com) - [OpenRouter](https://gridrouter.io/providers/openrouter): One endpoint for hundreds of language models. (openrouter.ai) - [OpenSanctions](https://gridrouter.io/providers/opensanctions): Sanctions and PEP screening API with per-query pricing and an OpenAPI spec. (opensanctions.org) - [Opensend](https://gridrouter.io/providers/opensend): Ecommerce visitor identity resolution for email/SMS retargeting. (opensend.com) - [OpenWeb Ninja](https://gridrouter.io/providers/openwebninja): Publishes 12 APIs on RapidAPI: JSearch, Real-Time SERP Data, Email Finder, Trustpilot Company and Reviews Data, Local Business Data, and more. (openwebninja.com) - [Osano](https://gridrouter.io/providers/osano): Consent management platform with REST and Unified Consent APIs. (osano.com) - [Outreach](https://gridrouter.io/providers/outreach): Enterprise sales engagement with an OAuth API. (outreach.io) - [Outscraper](https://gridrouter.io/providers/outscraper): Google Maps places and reviews scraping API. (outscraper.com) - [Overture Maps Foundation](https://gridrouter.io/providers/overture-maps): Open places/POI dataset (CDLA Permissive 2.0) released monthly; no query API. (overturemaps.org) - [Owler](https://gridrouter.io/providers/owler): Crowdsourced company intelligence: Enterprise API for company premium data, competitors and news feed. (owler.com) - [Oxylabs](https://gridrouter.io/providers/oxylabs): Proxy network and Web Scraper API with Google SERP sources. (oxylabs.io) - [Pappers](https://gridrouter.io/providers/pappers): French company information API: accounts, filed acts, statutes and directors (API v2). (pappers.fr) - [Parallel Web Systems](https://gridrouter.io/providers/parallel-web): Search, Extract, Task (deep research), FindAll and Monitor APIs for AI agents. (parallel.ai) - [Particl](https://gridrouter.io/providers/particl): E-commerce competitor sales, product and pricing intelligence (SaaS). (particl.com) - [People Data Labs](https://gridrouter.io/providers/people-data-labs): Bulk person and company datasets behind a fast lookup API. (peopledatalabs.com) - [Perigon](https://gridrouter.io/providers/perigon): Enriched news, stories, companies and journalists API with OpenAPI and MCP. (perigon.io) - [Perplexity Sonar](https://gridrouter.io/providers/perplexity): Search-grounded answers and a raw web search API. (perplexity.ai) - [PhoneValidator](https://gridrouter.io/providers/phonevalidator): Phone Validator API -- Phone Number Linetype Lookup. (phonevalidator.com) - [Phyllo](https://gridrouter.io/providers/phyllo): Creator data APIs (discovery, consented account data, social listening) across 20+ platforms. (getphyllo.com) - [Pipedrive](https://gridrouter.io/providers/pipedrive): Sales CRM with a REST API over OAuth or API token. (pipedrive.com) - [Pipl](https://gridrouter.io/providers/pipl): Identity and fraud intelligence from a people search API. (pipl.com) - [PitchBook](https://gridrouter.io/providers/pitchbook): Private-market company, deal and investor data (enterprise). (pitchbook.com) - [Plivo Lookup API](https://gridrouter.io/providers/plivo-lookup): Carrier and number-type lookup for E.164 phone numbers. (plivo.com) - [Plunk](https://gridrouter.io/providers/plunk): Open-source email platform with a REST API and OpenAPI spec. (useplunk.com) - [Podium](https://gridrouter.io/providers/podium): Local business messaging and reviews platform with an OAuth 2 API. (podium.com) - [Postmark](https://gridrouter.io/providers/postmark): Transactional email API with server tokens and batch send. (postmarkapp.com) - [PowerAdSpy](https://gridrouter.io/providers/poweradspy): Ad intelligence across up to 11 networks (web app). (poweradspy.com) - [PowerReviews](https://gridrouter.io/providers/powerreviews): Ratings & reviews and UGC for brands and retailers (developer portal not reachable). (powerreviews.com) - [PR Labs](https://gridrouter.io/providers/pr-labs): Access job listings from professional network, Indeed, and ZipRecruiter with PR Labs' Job Search API. (prlabsapi.com) - [PredictLeads](https://gridrouter.io/providers/predictleads): Company signals: job openings, news events, tech and connections. (predictleads.com) - [Price API (Metoda)](https://gridrouter.io/providers/priceapi): Product and offer data from Google Shopping, Amazon and other sources. (priceapi.com) - [Proofy](https://gridrouter.io/providers/proofy): Email verifier with bulk and API validation; unknowns not charged. (proofy.io) - [Prospeo](https://gridrouter.io/providers/prospeo): Email and mobile finder with profile enrichment. (prospeo.io) - [QuickEnrich](https://gridrouter.io/providers/quickenrich): Email and mobile finder with metered or unlimited API. (quickenrich.io) - [Radar](https://gridrouter.io/providers/radar): Geofencing, geocoding, place search and address validation APIs. (radar.com) - [RB2B](https://gridrouter.io/providers/rb2b): Person-level website visitor identification (US). (rb2b.com) - [RealtimeAPI](https://gridrouter.io/providers/realtimeapi): Ad data from: Meta (Facebook & Instagram), Tiktok and Google. (brizzox.com) - [RealValidation](https://gridrouter.io/providers/realvalidation): Phone validation, DNC and litigator lookup APIs. (realvalidation.com) - [Reddit Data API](https://gridrouter.io/providers/reddit-data-api): Official Reddit API for posts, comments, subreddits and users (OAuth2). (reddit.com) - [Reoon Email Verifier](https://gridrouter.io/providers/reoon): Low-cost email verifier with quick and power modes and a bulk task API. (reoon.com) - [Reply.io](https://gridrouter.io/providers/reply-io): Multichannel sales engagement with a v3 REST API for sequences. (reply.io) - [Reputation](https://gridrouter.io/providers/reputation): Enterprise reputation management (reviews, listings, social); API not public. (reputation.com) - [Resend](https://gridrouter.io/providers/resend): Developer email API with SDKs, MCP server and an OpenAPI spec. (resend.com) - [Retention.com](https://gridrouter.io/providers/retention-com): Person-level identity resolution for anonymous website traffic (US). (retention.com) - [REVIEWS.io](https://gridrouter.io/providers/reviews-io): Company and product reviews platform; API on the Plus package. (reviews.io) - [RocketReach](https://gridrouter.io/providers/rocketreach): Emails and phones for 700M professionals, with an API and MCP. (rocketreach.co) - [SafeGraph](https://gridrouter.io/providers/safegraph): Global POI Places dataset (Placekey IDs, brands, NAICS) delivered in bulk. (safegraph.com) - [Salesforce](https://gridrouter.io/providers/salesforce): CRM writes over your own OAuth connection. (salesforce.com) - [Saleshandy](https://gridrouter.io/providers/saleshandy): Cold email sequences with an open API to import prospects. (saleshandy.com) - [Salesloft](https://gridrouter.io/providers/salesloft): Sales engagement cadences with a team-level rate-limited API. (salesloft.com) - [SalesQL](https://gridrouter.io/providers/salesql): professional network-profile-to-email and phone enrichment API. (salesql.com) - [Scale SERP](https://gridrouter.io/providers/scale-serp): Google SERP API with batches, sold in monthly search bundles. (scaleserp.com) - [ScrapeCreators](https://gridrouter.io/providers/scrapecreators): Social profiles, posts and ad libraries across 20+ platforms. (scrapecreators.com) - [ScrapeGraphAI](https://gridrouter.io/providers/scrapegraphai): LLM-powered extract, scrape, search, crawl and monitor API. (scrapegraphai.com) - [ScrapeNinja](https://gridrouter.io/providers/scrapeninja): Web scraping API. (scrapeninja.net) - [Scraper.tech](https://gridrouter.io/providers/scraper-tech): Unofficial cheap Twitter / X API. (scraper.tech) - [ScraperAPI](https://gridrouter.io/providers/scraperapi): Proxy-rotating scraping API with structured-data endpoints and async DataPipeline. (scraperapi.com) - [scrapestack](https://gridrouter.io/providers/scrapestack): Real-time, Scalable Proxy & Web Scraping REST API Powerful infrastructure trusted by 2,000+ companies. (scrapestack.com) - [Scrapfly](https://gridrouter.io/providers/scrapfly): Scrape, screenshot and extraction APIs with anti-bot bypass and proxy pools. (scrapfly.io) - [ScrapingBee](https://gridrouter.io/providers/scrapingbee): Web scraping API with headless browsers, rotating proxies and CSS/AI extraction rules. (scrapingbee.com) - [Scrapingdog](https://gridrouter.io/providers/scrapingdog): Web scraping and Google SERP APIs sold as request credits. (scrapingdog.com) - [Scrubby](https://gridrouter.io/providers/scrubby): Catch-all and risky email validation service with API access. (scrubby.io) - [SE Ranking API](https://gridrouter.io/providers/se-ranking): SEO data API with pay-as-you-go credits and MCP. (seranking.com) - [Seamless.AI](https://gridrouter.io/providers/seamless-ai): Real-time contact search with an enterprise research API. (seamless.ai) - [SearchApi](https://gridrouter.io/providers/searchapi): Real-time Google and other search engine results as JSON. (searchapi.io) - [Searchbug](https://gridrouter.io/providers/searchbug): People search and phone lookup APIs on a prepaid balance. (searchbug.com) - [SEC EDGAR APIs](https://gridrouter.io/providers/sec-edgar): US SEC data.sec.gov JSON APIs: filing history by CIK and XBRL financial statement facts. (sec.gov) - [SeekOut](https://gridrouter.io/providers/seekout): AI recruiting platform with 1B+ candidate profiles. (seekout.com) - [Semrush API](https://gridrouter.io/providers/semrush): Keyword, domain and backlink analytics via API units. (semrush.com) - [SendGrid](https://gridrouter.io/providers/sendgrid): Twilio's email API for transactional and marketing sending. (sendgrid.com) - [SEO Dataset](https://gridrouter.io/providers/seo-dataset): ✅ This API offers a powerful tool that enables you to query the traffic and key performance metrics for any website. (seodataset.com) - [SerpApi](https://gridrouter.io/providers/serpapi): Live search engine results, including Maps and Ads Transparency. (serpapi.com) - [Serper](https://gridrouter.io/providers/serper): Fast, low-cost Google SERP API. (serper.dev) - [serpstack](https://gridrouter.io/providers/serpstack): apilayer's real-time Google SERP API with JSON or CSV output. (serpstack.com) - [Serpstat API](https://gridrouter.io/providers/serpstat): Keyword and domain analytics API. (serpstat.com) - [SerpWow](https://gridrouter.io/providers/serpwow): Multi-engine SERP API from Traject Data with batches and webhooks. (serpwow.com) - [ShoppingScraper](https://gridrouter.io/providers/shoppingscraper): Google Shopping data API with matched catalog IDs (EU). (shoppingscraper.com) - [SignalHire](https://gridrouter.io/providers/signalhire): Email and phone credits with API access on paid plans. (signalhire.com) - [Similarweb API](https://gridrouter.io/providers/similarweb): Website traffic and engagement estimates (enterprise). (similarweb.com) - [SISTRIX](https://gridrouter.io/providers/sistrix): German SEO visibility index toolbox with a credit-based API. (sistrix.com) - [Skrapp](https://gridrouter.io/providers/skrapp): Email finder and verifier with bulk endpoints. (skrapp.io) - [Smartlead](https://gridrouter.io/providers/smartlead): Add leads to campaigns with your own API key. (smartlead.ai) - [SMTP2GO](https://gridrouter.io/providers/smtp2go): SMTP relay and email API with a free tier. (smtp2go.com) - [Snitcher](https://gridrouter.io/providers/snitcher): B2B website visitor identification with REST and real-time Spotter APIs. (snitcher.com) - [Snov.io](https://gridrouter.io/providers/snov-io): Email finder, verifier and outreach with a REST API. (snov.io) - [Spamhaus](https://gridrouter.io/providers/spamhaus): IP and domain blocklists via DNS query service (DQS). (spamhaus.com) - [SparkPost](https://gridrouter.io/providers/sparkpost): Bird's email delivery API with US and EU endpoints. (sparkpost.com) - [Specter](https://gridrouter.io/providers/specter): Private-market data API: startups, people, investors, transactions and signals (approval-based key). (tryspecter.com) - [Spider](https://gridrouter.io/providers/spider): High-throughput crawl, scrape, search and links API with LLM-ready output. (spider.cloud) - [Sprout Social](https://gridrouter.io/providers/sprout-social): Social media management suite with a plan-gated analytics/listening API. (sproutsocial.com) - [SpyFu](https://gridrouter.io/providers/spyfu): Competitor PPC and SEO keyword data with an API. (spyfu.com) - [StandingAPI](https://gridrouter.io/providers/standingapi): Publishes 2 APIs on RapidAPI: Phone Number Validation and Verification, Company Enrichment. (rapidapi.com) - [Steel](https://gridrouter.io/providers/steel): Open-source cloud browser API for AI agents (sessions, CAPTCHA solving, proxies). (steel.dev) - [Store Leads](https://gridrouter.io/providers/store-leads): E-commerce store and app intelligence (Shopify, etc.) via domain and app APIs. (storeleads.app) - [Streak](https://gridrouter.io/providers/streak): CRM inside Gmail with an API for pipelines, boxes and contacts. (streak.com) - [Sumble](https://gridrouter.io/providers/sumble): Tech-stack, team and job-post signals by organization. (sumble.com) - [Surfe](https://gridrouter.io/providers/surfe): People and company search and enrichment API with waterfall email and mobile. (surfe.com) - [Swordfish](https://gridrouter.io/providers/swordfish): Cell phone and email finder; site blocked automated reads. (swordfish.ai) - [Tavily](https://gridrouter.io/providers/tavily): Search, extract and crawl API for agents. (tavily.com) - [TCPA Litigator List](https://gridrouter.io/providers/tcpa-litigator-list): Litigator and DNC scrub, priced per scrub. (tcpalitigatorlist.com) - [Techmap (Job Datafeeds)](https://gridrouter.io/providers/techmap): International job postings via RapidAPI Jobs API, data feeds and historical datasets. (jobdatafeeds.com) - [Telesign Phone ID](https://gridrouter.io/providers/telesign): Phone ID API returning phone type, carrier and risk data for a number. (telesign.com) - [Telnyx Number Lookup](https://gridrouter.io/providers/telnyx): Carrier, LRN and CNAM lookup from $0.0015 per query. (telnyx.com) - [The Companies API](https://gridrouter.io/providers/the-companies-api): Company enrichment from a domain or email, with webhooks. (thecompaniesapi.com) - [The Lens](https://gridrouter.io/providers/lens): Lens Scholarly and Patent APIs: search global patents and scholarly works (approval-based access). (lens.org) - [theCele](https://gridrouter.io/providers/thecele): Find email address with this email hunter API. (rapidapi.com) - [TheirStack](https://gridrouter.io/providers/theirstack): Job postings and technographics API: company search, job search and technologies used by company. (theirstack.com) - [TheNewsAPI](https://gridrouter.io/providers/thenewsapi): Headlines, top stories and all-news search API. (thenewsapi.com) - [TikHub](https://gridrouter.io/providers/tikhub): Pay-per-request API for TikTok, Douyin, Instagram, YouTube, X, Reddit and more. (tikhub.io) - [TikTok Commercial Content API](https://gridrouter.io/providers/tiktok-creative-center): TikTok ad and commercial content data by application only. (tiktok.com) - [Together AI](https://gridrouter.io/providers/together-ai): Serverless and dedicated inference for open models, plus batch and fine-tuning. (together.ai) - [Tomba](https://gridrouter.io/providers/tomba): Email finder, verifier and domain search. (tomba.io) - [TomTom Search API](https://gridrouter.io/providers/tomtom): TomTom Search API: fuzzy search, POI search, nearby and place-by-id. (tomtom.com) - [Tracxn](https://gridrouter.io/providers/tracxn): Private-market intelligence: APIs for companies, funding rounds, acquisitions, investors and news. (tracxn.com) - [Traject Data (Rainforest API)](https://gridrouter.io/providers/traject-data): Rainforest (Amazon), BlueCart (Walmart), Countdown (eBay) and SERP APIs. (trajectdata.com) - [Transcend](https://gridrouter.io/providers/transcend): Privacy and consent infrastructure with DSR and preference APIs. (transcend.io) - [Trestle](https://gridrouter.io/providers/trestle): Phone validation, reverse phone and identity APIs. (trestleiq.com) - [Trigify](https://gridrouter.io/providers/trigify): Social-listening buying signals; team joining HubSpot, service ending Oct 2026. (trigify.io) - [Tripadvisor Content API](https://gridrouter.io/providers/tripadvisor-content-api): Location search, details, reviews and photos for hotels, restaurants, attractions. (tripadvisor.com) - [Truelist](https://gridrouter.io/providers/truelist): Email verification with pay-as-you-go credits or flat unlimited plans. (truelist.io) - [TrustedForm (ActiveProspect)](https://gridrouter.io/providers/trustedform): Consent certificates for TCPA proof of opt-in, with a certificate API. (activeprospect.com) - [Trustpilot](https://gridrouter.io/providers/trustpilot): Consumer review platform with public business-unit and review APIs. (trustpilot.com) - [TrustRadius Intent](https://gridrouter.io/providers/trustradius): Downstream buyer intent from software review research. (trustradius.com) - [Twenty](https://gridrouter.io/providers/twenty): Open-source CRM with REST and GraphQL APIs generated from the workspace schema. (twenty.com) - [Twilio Lookup](https://gridrouter.io/providers/twilio-lookup): Line type, carrier and number validation. (twilio.com) - [Upfluence](https://gridrouter.io/providers/upfluence): Influencer and affiliate marketing platform with an influencer API and MCP. (upfluence.com) - [UpLead](https://gridrouter.io/providers/uplead): Verified B2B contacts with a person, company and combined API. (uplead.com) - [USAJOBS API](https://gridrouter.io/providers/usajobs): US federal government job announcements via the USAJOBS Search API. (usajobs.gov) - [UserGems](https://gridrouter.io/providers/usergems): Job-change and buying-signal tracking with a write API for contacts to track. (usergems.com) - [USPTO Open Data Portal](https://gridrouter.io/providers/uspto-open-data): USPTO Open Data Portal REST APIs for patent application data, continuity and documents (absorbing PatentsView). (uspto.gov) - [Validity Everest](https://gridrouter.io/providers/validity-everest): Email deliverability, inbox placement and reputation monitoring. (validity.com) - [Valimail](https://gridrouter.io/providers/valimail): DMARC enforcement and sender authentication. (valimail.com) - [VALUE SERP](https://gridrouter.io/providers/valueserp): Budget Google SERP API with batches, by Traject Data. (valueserp.com) - [Vector](https://gridrouter.io/providers/vector): Contact-level website visitor identification and ABM signals platform. (vector.co) - [Veer Hanuman](https://gridrouter.io/providers/veer-hanuman): Jobs Search Real-Time Data API provides live job postings from platforms like Indeed, professional network, ZipRecruiter, and Glassdoor. (openmarketplace.in) - [Veridion](https://gridrouter.io/providers/veridion): Company match & enrich and search APIs over a global firmographic database (OAuth 2.0). (veridion.com) - [Verifalia](https://gridrouter.io/providers/verifalia): Email verification REST API with open-source SDKs, by Cobisi Research. (verifalia.com) - [Veriphone](https://gridrouter.io/providers/veriphone): Phone number validation API returning validity, carrier and line type. (veriphone.io) - [Versium](https://gridrouter.io/providers/versium): REACH consumer and B2B contact append and identity APIs with an MCP server. (versium.com) - [Voila Norbert](https://gridrouter.io/providers/voila-norbert): Email finder with bulk jobs and basic-auth API. (voilanorbert.com) - [Vonage Number Insight](https://gridrouter.io/providers/vonage-number-insight): Phone number insight API (format, network, fraud signals); sunsetting for Identity Insights. (vonage.com) - [Waalaxy](https://gridrouter.io/providers/waalaxy): professional network and email prospecting automation for SMBs. (waalaxy.com) - [Wappalyzer](https://gridrouter.io/providers/wappalyzer): Technology lookup API and lead lists by technology. (wappalyzer.com) - [Warmly](https://gridrouter.io/providers/warmly): Website de-anonymization and AI inbound agents. (warmly.ai) - [Warmup Inbox](https://gridrouter.io/providers/warmup-inbox): Email warmup and inbox placement testing. (warmupinbox.com) - [WebScrapingAPI](https://gridrouter.io/providers/webscrapingapi): WebScraping - The leading REST API for web scraping. (webscrapingapi.com) - [Webz.io](https://gridrouter.io/providers/webz-io): Open-web news, blogs, forums and reviews data APIs. (webz.io) - [WhoisXML API](https://gridrouter.io/providers/whoisxml-api): Publishes 2 APIs on RapidAPI: Email Verification, IP geolocation. (emailverification.whoisxmlapi.com) - [Wiza](https://gridrouter.io/providers/wiza): Emails and phones from profile lists, with a bearer-token API. (wiza.co) - [Woodpecker](https://gridrouter.io/providers/woodpecker): Cold email platform with an API to add prospects to campaigns. (woodpecker.co) - [World News API](https://gridrouter.io/providers/world-news-api): Semantic news search API with sentiment, entities and front pages. (worldnewsapi.com) - [X API](https://gridrouter.io/providers/x-api): Official X (Twitter) v2 API, pay-per-use per resource read. (x.com) - [xAI API](https://gridrouter.io/providers/xai): Grok model API with spend-based rate-limit tiers. (x.ai) - [Yelp Places API](https://gridrouter.io/providers/yelp-fusion): Business search, details and reviews from Yelp. (yelp.com) - [Yotpo](https://gridrouter.io/providers/yotpo): E-commerce reviews, UGC and loyalty with a UGC/reviews API. (yotpo.com) - [You.com APIs](https://gridrouter.io/providers/you-com): Web Search, Contents, Answer and Research APIs with citations for LLMs. (you.com) - [YouScan](https://gridrouter.io/providers/youscan): AI social listening with image recognition and a Social Intelligence API. (youscan.io) - [YouTube Data API v3](https://gridrouter.io/providers/youtube-data-api): Official YouTube API for channels, videos, comments and search (quota-based). (developers.google.com) - [Zefix PublicREST](https://gridrouter.io/providers/zefix): Swiss central business name index (Zefix) REST API: company search, UID/CHID lookup, SOGC notices. (zefix.admin.ch) - [ZenRows](https://gridrouter.io/providers/zenrows): Universal scraper API with anti-bot bypass, JS rendering and auto-extraction. (zenrows.com) - [Zenserp](https://gridrouter.io/providers/zenserp): Google, Bing, Yandex and DuckDuckGo SERP API with a free tier. (zenserp.com) - [ZeroBounce](https://gridrouter.io/providers/zerobounce): Email validation with a freemium tier and ONE subscription. (zerobounce.net) - [Zinc](https://gridrouter.io/providers/zinc): Cross-retailer product search, offers and ordering API (Amazon, Walmart, Target…). (zinc.com) - [Zoho CRM](https://gridrouter.io/providers/zoho-crm): CRM with a REST API for records, upserts and bulk operations. (zoho.com) - [ZoomInfo](https://gridrouter.io/providers/zoominfo): Enterprise B2B contact, company and intent data. (zoominfo.com) - [Zyte API](https://gridrouter.io/providers/zyte): Scraping API priced per successful response. (zyte.com) ## Guides # API reference (/docs/api) Every page in this section is generated from the gateway's own route definitions at build time, so it always matches what `https://api.gridrouter.io` serves. The same operations are [MCP tools](/docs/mcp) with the same names. ## Base URL and auth [#base-url-and-auth] ```text https://api.gridrouter.io ``` Send a GridRouter [API key](/docs/getting-started/api-keys) as a bearer token: ```http Authorization: Bearer grid_live_… ``` Catalog and status routes are public and need no key. Everything else checks the key's scopes; each operation lists the scope it needs. ## Conventions [#conventions] * **JSON in, JSON out.** Request bodies are validated at the edge; a bad field is `400 invalid_request` or `422 validation_failed` with the field's path. * **Money** is integer micro-USD everywhere: 1,000,000 = $1. The one exception is the `X-Grid-Max-Cost` header, which is in USD. * **Timestamps** are ISO 8601 in UTC. * **Paging.** Routes that page take `limit` and an opaque `cursor`. * **Idempotency.** Send `Idempotency-Key` on `POST`s that run something; see [idempotency](/docs/errors#idempotency). * **Errors** share one [envelope](/docs/errors). ## Machine-readable [#machine-readable] | Document | URL | | ------------------------------- | ------------------------------------------------------------------ | | OpenAPI 3.1 | `https://api.gridrouter.io/openapi.json` | | OpenAPI 3.0 (for older tooling) | `https://api.gridrouter.io/openapi-3.0.json` | | Tool schemas | `https://api.gridrouter.io/v1/tools?format=openai\|anthropic\|mcp` | | Execution options JSON Schema | `https://api.gridrouter.io/v1/options/schema` | The playground on each operation page sends real requests from your browser straight to the API, with the key you enter. Use a test or read-only key there. # CLI (/docs/cli) The `grid` CLI (`@relaygrid/cli`) is not published yet. Until it is, the same stream is one `curl -N` away: see [live tail](/docs/concepts/logs-and-drains#live-tail). `grid` needs Node 22.18 or newer and a key with `logs:read`. ```bash export GRID_API_KEY=grid_live_… grid logs tail --capability people.email.find --status error ``` ## Commands [#commands] ```text grid logs tail [filters] [--json] Stream the live log (calls, runs, jobs, lists, alerts) grid logs recent [filters] [-n 50] Print the newest buffered events and exit ``` `tail` prints one line per event (for calls: time, outcome, HTTP status, endpoint, latency, cost, error code and call id) until you press Ctrl-C, reconnecting on its own. `--json` prints each event as a JSON line instead, for `jq`. ## Filters [#filters] | Flag | Filter | | --------------------------------------- | -------------------------------- | | `--capability ` | `capability` | | `--provider ` | `provider` | | `--endpoint ` | `endpoint_id` | | `--status ` | `status` | | `--key ` | `key_id` | | `--app ` | `app_id` | | `--run ` | `run_id` (a run, list or job id) | | `--waterfall ` | `waterfall_id` | | `--kinds ` | `kinds` | | `--min-latency ` | `latency_min` | | `--min-cost ` | `cost_min` | | `--sample <0-1>` | `sample` | | `--fields ` | `fields` | | `--replay <0-1000>` | `replay` | The API validates every value; see the [live tail filters](/docs/concepts/logs-and-drains#live-tail). ## Environment [#environment] | Variable | | | -------------- | ---------------------------------------------------------------------------- | | `GRID_API_KEY` | API key with `logs:read` (required) | | `GRID_API_URL` | API base URL (default `https://api.gridrouter.io`; `--api-url` overrides it) | # Alerts (/docs/concepts/alerts) An **alert rule** watches one metric in your workspace: the error rate of your calls, what they cost, how much of a budget is used, a provider rejecting your own key, and more. When the metric crosses the rule's threshold, GridRouter opens an **alert**, shows it as a toast in the dashboard and notifies the rule's [destinations](/docs/concepts/integrations): email, your own [webhook endpoints](/docs/concepts/webhooks), Slack, Discord, Microsoft Teams, PagerDuty or Opsgenie. When the metric recovers, the alert resolves on its own and destinations that take resolve notifications are told. Manage rules, alerts and destinations in the dashboard under Settings → **Alerts & integrations**, through the API or with the MCP tools below. ## Metrics [#metrics] Every rule measures one of these. The table is generated from the same definitions the API validates against. | Metric | Measures | Threshold | Fires | Evaluated | Scopes | One alert per | Default | | --- | --- | --- | --- | --- | --- | --- | --- | | `error_rate` | Error rate: The share of calls that failed in the window. | Share, 0–1 (`0.5` is 50%) | At or above | Live, within seconds (windows up to an hour) | `workspace`, `key`, `vendor`, `capability` | Rule | 50% over 5 minutes, at least 20 events | | `p95_latency` | p95 latency: How long the slowest 5% of calls took, end to end. | Milliseconds | At or above | Every 5 minutes | `workspace`, `key`, `vendor`, `capability` | Rule | 5 s over 15 minutes, at least 20 events | | `spend` | Spend: What calls cost in the window, in USD. | Micro-USD (`1000000` is $1) | At or above | Live, within seconds (windows up to an hour) | `workspace`, `key`, `vendor`, `capability` | Rule | $5.00 over 5 minutes | | `budget_used` | Budget used: How much of a workspace or key budget this period has used. | Percent of the limit (`80`) | At or above | Every 5 minutes | `workspace`, `key` | Budget | 80% over 5 minutes | | `vendor_failure_spike` | Vendor failure spike: One vendor's failed share, alerted separately for each vendor. | Share, 0–1 (`0.5` is 50%) | At or above | Live, within seconds (windows up to an hour) | `workspace`, `vendor`, `capability` | Vendor | 50% over 5 minutes, at least 10 events | | `vendor_key_failing` | Vendor key failing: A vendor rejected one of your own vendor keys (HTTP 401 or 403): expired or revoked. | Count | At or above | Live, within seconds (windows up to an hour) | `workspace`, `vendor` | Vendor | 1 over 5 minutes | | `billing_mismatch` | Billing mismatches: Calls a vendor billed against its own published rule (charged for a miss, twice, …). | Count | At or above | Live, within seconds (windows up to an hour) | `workspace`, `vendor`, `key` | Rule | 3 over an hour | | `cache_hit_rate` | Cache hit rate: The share of cacheable lookups answered from your private cache. | Share, 0–1 (`0.5` is 50%) | At or below | Every 5 minutes | `workspace`, `key`, `vendor`, `capability` | Rule | 20% over an hour, at least 50 events | | `delivery_backlog` | Delivery backlog: Webhook deliveries and log-drain batches that failed or were dead-lettered. | Count | At or above | Every 5 minutes | `workspace` | Rule | 10 over an hour | | `security_event` | Security events: Invalid-key bursts, a key used from a new country, admin actions on the workspace. | Count | At or above | When the signal arrives | `workspace`, `key` | Signal kind | 1 over an hour | | `new_ip` | Key used from a new IP: A key was used from an IP address it has never used before. | Count | At or above | When the signal arrives | `workspace`, `key` | Key | 1 over an hour | `threshold` is in the metric's unit. Money is always integer micro-USD, so `5000000` is $5. Rates (`error_rate`, `vendor_failure_spike`, `p95_latency`, `cache_hit_rate`) wait for `min_events` calls or lookups in the window before they can fire, so a single failed call in a quiet minute doesn't page anyone. ## Default rules [#default-rules] Every new workspace starts with these rules. They're ordinary rules: edit, disable or delete any of them. | Rule | Severity | Fires when | Evaluated | Cooldown | Notifies | | --- | --- | --- | --- | --- | --- | | Vendor key failing | critical | Alerts when a vendor rejects your own vendor key (HTTP 401 or 403) within 5 minutes: usually an expired or revoked key. | Live, within seconds (windows up to an hour) | 15 minutes | Every destination, and a toast | | Budget at 80% | warning | Alerts when a workspace or key budget reaches 80% of its limit for the period. | Every 5 minutes | a day | Every destination, and a toast | | Budget reached | critical | Alerts when a workspace or key budget reaches 100% of its limit for the period. | Every 5 minutes | a day | Every destination, and a toast | | Billing mismatch spike | warning | Alerts when 3 or more calls are billed against the vendor's published rule within an hour. | Live, within seconds (windows up to an hour) | 15 minutes | Every destination, and a toast | | Error-rate spike | warning | Alerts when 50% or more of calls fail over 5 minutes (once there are at least 20 calls). | Live, within seconds (windows up to an hour) | 15 minutes | Every destination, and a toast | | Spend velocity | warning | Alerts when calls cost $5.00 or more within 5 minutes. | Live, within seconds (windows up to an hour) | 15 minutes | Every destination, and a toast | | Key used from a new IP | info | Alerts when a key is used from an IP address it hasn't used before. | When the signal arrives | 15 minutes | Dashboard toast only | | Deliveries failing | warning | Alerts when 10 or more webhook deliveries or log-drain batches fail within an hour. | Every 5 minutes | 15 minutes | Every destination, and a toast | | Security events | warning | Alerts on every security event. | When the signal arrives | 15 minutes | Every destination, and a toast | "Key used from a new IP" is informational: it shows as a toast but goes to no destination until you route it to one. A key's first IP is its baseline and never alerts. ## Rule settings [#rule-settings] | Field | Meaning | | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `metric`, `threshold` | What to measure, and the value that fires the rule (at or above, or at or below for `cache_hit_rate`) | | `window_s` | The window the metric is measured over, 60 seconds to 7 days | | `min_events` | Rates only: calls or lookups the window needs before the rule can fire (default 1) | | `severity` | `info`, `warning` (default) or `critical` | | `scope` | `{ "type": "workspace" }` (default), or `key`, `vendor` or `capability` with a `value` (a key id, provider slug or capability id). Each metric lists the scopes it takes | | `kinds` | `security_event` only: the signal kinds that count (`invalid_key_burst`, `new_geo`, `admin_action`, `key_ip_denied`, `scope_denied_burst`); empty means every kind | | `cooldown_s` | After an alert resolves, the same rule and subject can't open a new one for this long (default 900, at most 86,400) | | `all_destinations`, `destination_ids` | Notify every enabled destination (default), or only the listed ones (up to 20) | | `toast` | Also show the alert as a dashboard toast (default on) | | `muted_until` | Snooze until this time; see [Mute](#mute) | Each destination has its own `min_severity` (alerts below it are not sent there) and `notify_on_resolve` (default on). ## Lifecycle [#lifecycle] An alert is `triggered`, then optionally `acknowledged`, then `resolved`. Its timeline records every step: when it triggered, each notification sent or failed, acknowledgement and resolution (the newest 60 entries, always keeping the trigger). * **Dedupe.** While an alert is open, further breaches of the same rule and subject don't open another one. They raise the alert's `count` and update its value and `last_seen_at`. * **Grouping.** Some metrics open one alert per subject instead of one per rule: `vendor_failure_spike` and `vendor_key_failing` per provider, `budget_used` per budget (the workspace's or one key's), `new_ip` per key and `security_event` per signal kind. The subject is on the alert as `subject`. * **Cooldown.** After an alert resolves, the same rule and subject can't open a new alert for `cooldown_s`. The budget rules default to a day, so a budget that hovers around 80% alerts once a day at most. * **Auto-resolve.** A live rule reports that it has cleared once it has stayed on the right side of its threshold for a minute. A scheduled rule resolves on the next five-minute run that's no longer breached. An alert that nothing has confirmed for a while resolves too: 5 to 30 minutes for live rules (the window, within that range), 15 minutes for scheduled rules, and the rule's window for event rules. * **Acknowledge.** `POST /v1/alerts/{id}/acknowledge` marks a triggered alert as being handled. PagerDuty and Opsgenie are acknowledged too; chat and email destinations only hear about triggers and resolutions. * **Resolve.** `POST /v1/alerts/{id}/resolve` closes an alert now, and the rule's cooldown starts from there. Changing what a rule measures (metric, threshold, window, `min_events`, scope or kinds), disabling it or deleting it resolves its open alerts. ### Mute [#mute] `POST /v1/alerts/rules/{id}/mute` with `{ "minutes": 60 }` (or `{ "until": "" }`) snoozes a rule (`minutes` goes up to 30 days). It keeps evaluating: its alerts still open and resolve, show in history marked `muted` and still show as toasts, but nothing is sent to destinations or webhook endpoints. `{ "minutes": 0 }` unmutes it. ## Live and scheduled evaluation [#live-and-scheduled-evaluation] Where a rule runs depends on its metric and window: * **Live.** `error_rate`, `spend`, `vendor_failure_spike`, `vendor_key_failing` and `billing_mismatch` with windows up to an hour run in your workspace's [live tail](/docs/concepts/logs-and-drains#live-tail) hub on every call, so they fire within seconds. * **Scheduled.** `p95_latency`, `cache_hit_rate`, `budget_used`, `delivery_backlog` and any live metric with a window over an hour are evaluated every five minutes, against your call log (hourly rollups for whole-hour windows), your budgets and the webhook delivery log. * **Event.** `new_ip` and `security_event` fire when the signal arrives. Every rule shows its state: `ok`, `firing`, `muted`, `disabled` or `no_data`. `no_data` means the rule couldn't be evaluated, with the reason in `state.note`; for example, in a deployment without the call-log store, scheduled call metrics report `no_data` while every other rule keeps working. ## Toasts [#toasts] Alerts with `toast` on appear as toasts in the dashboard when they trigger and when they resolve. They arrive over the live tail as `alert` events, so any client that tails `kinds=alert` sees them too: ```bash curl -N "https://api.gridrouter.io/v1/logs/live?format=sse&kinds=alert&replay=0" \ -H "Authorization: Bearer $GRID_API_KEY" ``` ## Create a rule [#create-a-rule] Creating and changing rules needs a key with `keys:write`. This rule pages on-call when a third of email-finding calls fail over ten minutes, and only notifies one destination: ```bash curl https://api.gridrouter.io/v1/alerts/rules \ -H "Authorization: Bearer $GRID_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Email finding failing", "metric": "vendor_failure_spike", "threshold": 0.33, "window_s": 600, "min_events": 25, "severity": "critical", "scope": { "type": "capability", "value": "people.email.find" }, "all_destinations": false, "destination_ids": ["dst_4f8k2m9q4w8x1c5v"] }' ``` The response is the rule with its `id`, its `evaluator` and its `state`. `POST /v1/alerts/rules/{id}/test` sends a test alert to every destination the rule notifies and reports each result; nothing is recorded as a real alert. ## API and MCP [#api-and-mcp] Every operation is a REST route and an [MCP tool](/docs/mcp) of the same name. Reads need `logs:read`, rule and alert changes need `keys:write`, and destinations need `credentials:write` because they hold secrets. Reads, with `logs:read`: * `alerts_summary`: `GET /v1/alerts/summary` * `alerts_rules_list` and `alerts_rules_get`: `GET /v1/alerts/rules` and `GET /v1/alerts/rules/{id}` * `alerts_list` and `alerts_get`: `GET /v1/alerts?status=open` and `GET /v1/alerts/{id}` * `alerts_destinations_list` and `alerts_destinations_get`: `GET /v1/alerts/destinations` and `GET /v1/alerts/destinations/{id}` Rule and alert changes, with `keys:write`: * `alerts_rules_create`: `POST /v1/alerts/rules` * `alerts_rules_update` and `alerts_rules_delete`: `PUT` and `DELETE /v1/alerts/rules/{id}` * `alerts_rules_mute` and `alerts_rules_test`: `POST /v1/alerts/rules/{id}/mute` and `POST /v1/alerts/rules/{id}/test` * `alerts_acknowledge` and `alerts_resolve`: `POST /v1/alerts/{id}/acknowledge` and `POST /v1/alerts/{id}/resolve` Destination changes, with `credentials:write`: * `alerts_destinations_create`: `POST /v1/alerts/destinations` * `alerts_destinations_update` and `alerts_destinations_delete`: `PUT` and `DELETE /v1/alerts/destinations/{id}` * `alerts_destinations_test`: `POST /v1/alerts/destinations/{id}/test` `alerts_list` takes `status` (`open`, `triggered`, `acknowledged`, `resolved` or `all`), `rule_id` and `limit` (up to 200). A `PUT` changes only the fields you send. ## Limits [#limits] | Limit | Value | | -------------------------- | ---------------- | | Alert rules per workspace | 50 | | Destinations per workspace | 20 | | Resolved alerts kept | The newest 2,000 | | Timeline entries per alert | 60 | # Vendor billing verification (/docs/concepts/billing-verification) When you call with your own vendor key, the provider bills you directly. GridRouter reads what the provider reported for each call (from its response headers or body), works out what its published pricing rules say it should have charged, and records a verdict on the call's log row. ## Verdicts [#verdicts] | Verdict | When | | ---------------------- | ----------------------------------------------------------------------------- | | `ok` | The provider reported exactly the expected charge | | `charged_for_miss` | It charged more than expected, and the call was a miss or failed | | `double_charged_retry` | It charged again for a request it had already billed within its repeat window | | `price_mismatch` | It charged less than expected, or more on a hit or record count | | `unverifiable` | There is no rule for the endpoint, or the provider reported nothing | | `none` | The provider was not called (for example, a private-cache hit) | Search `billing:mismatch` in `/logs` for all three mismatch verdicts, or name one: `billing:charged_for_miss`, `-billing:ok`. ## Rules [#rules] Each rule comes from the provider's own pricing page and is linked from the call's detail sheet. A rule says when the provider charges (`always`, on any 2xx `success`, only on a `hit`, `per_record`, or whatever the body states `per_credit`), how many credits, when a charge is waived, and whether retries and repeats of an already-billed request are billed again. | Provider | Coverage | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | Providers that report usage per call | Rules for every endpoint; each call is checked against the credits the provider reports | | Hunter | Rules exist, but Hunter reports no per-call usage, so calls read `unverifiable` | | Prospeo | `email.find` (free on a record already bought, repeats within 90 days free); no public price, so dollar amounts are empty | | Everyone else | `unverifiable` until their rules are researched and cited | For example, Prospeo's `email.find` costs 1 credit only when it returns an email, and nothing when the same record is enriched again within 90 days. A miss that consumed a credit reads `charged_for_miss`. ## Where it shows [#where-it-shows] * The **Billing** column and facet in `/logs`, and a Billing section in each call's detail sheet: the rule in plain English with its source, the expected and reported credits and dollars, and the balance the provider reported. * **Billing accuracy** in the log toolbar: per provider, calls checked, billed right, each mismatch type, and credits and dollars overbilled for the current filters. The API is [`GET /v1/logs/billing`](/docs/api/logs/logs_billing). * **Export → Billing disputes (CSV)**: the mismatches only, with request id, UTC timestamp, provider, endpoint, verdict, outcome, HTTP status, expected and reported credits and USD, balance after, and the rule. Send it to the provider as-is. Calls on GridRouter's managed vendor accounts read `managed`; their vendor-side cost is never shown. # Build a waterfall (/docs/concepts/build-a-waterfall) ## 1. Start from a template or from scratch [#1-start-from-a-template-or-from-scratch] Templates cover the common jobs (work email, verification, mobile, person and company enrichment, full lead enrichment). Find one with `GET /v1/waterfalls/templates?runnable=true&q=email` or in the dashboard under **Waterfalls → Templates**, where each card shows whether your vendor keys cover it. **Use template** opens it in the builder. From scratch, **New waterfall** starts with one stage for a capability and its first three supported endpoints. ## 2. Steps [#2-steps] A stage runs one capability. Its steps are tried by the speed profile until the stop rule holds: * A **routed** step is a pool: the capability's endpoints filtered by [provider preferences](/docs/concepts/routing#provider-preferences) (`order`, `only`, `ignore`, `allow_fallbacks`), up to `max_endpoints`. Templates use routed steps only, so they stay provider-neutral. * An **endpoint** step pins one provider endpoint, such as `hunter/email.find`. To pin providers on a template, pass `pins` when creating it: `{"pins":{"email":["hunter"]}}` puts those providers first in that stage's pool, and `"pins_only": true` turns off the fallback. Each step can set `timeout_ms`, `retries`, `max_cost_micro`, required fields, a minimum confidence, verified-only, what a provider 4xx does, and a `when` guard (`{"field":"email","op":"exists"}`, combined with `all`, `any` and `not`). A stage can also have a `when`: a stage that's skipped doesn't count against the outcome. ## 3. Speed, stop rules and budget [#3-speed-stop-rules-and-budget] | Choice | Options | | ------ | ------------------------------------------------------------------------------------------------------------------------------------- | | Speed | `fastest` (race, hedge 750 ms), `balanced` (one at a time, hedge at 3 s), `cheapest` (sequential, cheapest first), `custom` | | Stop | `first_hit`, `first_verified`, `until_fields_filled`, `all_then_merge`, `condition`, combined with `stop_mode` `any` or `all` | | Budget | `max_cost_micro` on the definition and on each run; the run stops before an attempt that would pass it and returns the partial record | `POST /v1/waterfalls/estimate` prices a definition or a template without calling any provider: worst-case and expected cost, expected time and fill, plus every step's quote. ## 4. Inputs between stages [#4-inputs-between-stages] A stage's input is the run input plus anything earlier stages found. Capability inputs fill themselves from the golden record by name, so a `company` stage gets the `domain` that a `person` stage returned. Map one explicitly with `input_map`: `{"domain":"stages.employer.domain"}` or `{"email":"input.work_email"}`. Mapped values are normalized like run inputs; a website URL becomes a bare domain, for example. Set `fields` on a stage to keep only those outputs. See [merge rules](/docs/concepts/merge-rules). ## 5. Test [#5-test] The builder's test runner runs the draft (`"version":"draft"`). On a `grid_test_` key, the `sandbox-*` templates and providers are deterministic and need no vendor key (their calls still draw on your credit at list price). A `scenario` input scripts each sandbox provider (`swift`, `deep`, `sure`) with `hit`, `miss`, `unverified`, `lowconf`, `timeout`, `slow:`, `500`, `400` or `429:`. For example, `swift=miss,deep=slow:2000,sure=hit` lets you check fallbacks and stop rules without spending anything. ## 6. Publish and run [#6-publish-and-run] Publishing freezes a semver version (`POST /v1/waterfalls/{id}/versions` `{"bump":"minor"}`; `from-template` publishes `1.0.0`). Then run it: | Mode | Call | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Sync | `POST /v1/waterfalls/{id}/run` `{"input":{…}}`, up to 50 s | | Async | add `"async": true` or `Prefer: respond-async`, then poll `GET /v1/waterfalls/{id}/runs/{run_id}`, stream `/events`, or pass `webhook_url` | | Batch | `POST /v1/waterfalls/batch-run` with up to 1,000 rows or a CSV, then `GET /v1/lists/{id}` | | Your endpoint | `POST /v1/x/{workspace}/{name}`, or the MCP tool `x_run` | ```ts import { createGrid } from "@relaygrid/sdk"; const grid = createGrid({ apiKey: process.env.GRID_API_KEY! }); const wf = await grid.waterfalls.fromTemplate("full-lead-enrichment", { pins: { email: ["hunter"] }, max_cost_micro: 200_000, }); const run = await grid.waterfalls.run(wf.id, { email: "ada@example.com" }, { async: true }); const done = await grid.waterfalls.waitFor(wf.id, run.id); console.log(done.outcome, done.data, done._provenance); ``` # Capabilities and endpoints (/docs/concepts/capabilities-and-endpoints) The catalog describes every provider API in the same shape. Browse it at [/providers](/providers) and [/capabilities](/capabilities), or read it from the public [catalog API](/docs/api/catalog/catalog_search). ## Capability [#capability] A capability is a task with a fixed contract, whichever provider performs it. `people.email.find`, for example: | Part | Value | | ------------- | ----------------------------------------------------------------- | | Inputs | `first_name`, `last_name`, `domain` (all required) | | Output fields | `email`, `confidence` (0–100) | | Hit | A deliverable or accept-all email address is returned | | Accuracy | Share of returned addresses that do not hard-bounce within 7 days | The **hit** definition is what makes providers comparable: routing stops on it, per-success pricing charges on it, and quality scores count it. Capabilities today include `people.email.find`, `email.verify`, `people.enrich`, `people.profile.find`, `people.role.find`, `people.search`, `phone.mobile.find`, `company.enrich` and `signals.job_change`. ## Endpoint [#endpoint] An endpoint is one provider's implementation, named `/`: `hunter/email.find`. It declares: * its **input** schema (Hunter's is `first_name`, `last_name` and `domain`), * how the provider's response maps to the capability's output fields, and what counts as a hit, * its **pricing model** and list price, * which **credentials** it accepts: `byok` (your key), `managed` (GridRouter's account) or both, * how the provider bills your own key, for [billing verification](/docs/concepts/billing-verification). `GET /v1/catalog/endpoints/{provider}/{endpoint}` returns all of it, including the input as JSON Schema, the current quote and quality. ## Pricing models [#pricing-models] | Model | Charged | | ------------- | ------------------------------------------------------------ | | `per_call` | Whenever the provider answers, hit or not | | `per_success` | Only on a hit (a miss can carry its own, usually zero, rate) | | `per_result` | Per returned record | | `per_unit` | Per unit of input or output (rows, domains, credits, pages) | | `per_token` | Per million tokens, read from the response | | `async_task` | A submit fee plus a completion fee charged only on success | Prices are integer micro-USD. `POST /v1/quote/{provider}/{endpoint}` returns the quote for a given input without calling the provider. On your own vendor keys GridRouter charges nothing, whatever the model. ## Quality [#quality] Every endpoint's quality comes from real traffic: reliability, coverage (fill), accuracy, freshness, speed (p50 and p95 latency) and value (cost per verified hit). Rates are Wilson lower bounds, so a small sample cannot rank high. The composite weighs accuracy 0.30, coverage 0.25, reliability 0.20, freshness 0.10, speed 0.10 and reviews 0.05, and needs at least 200 calls; below that, pages show "insufficient data". Use it with `sort: "quality"` when [routing](/docs/concepts/routing). # Execution options (/docs/concepts/execution-options) Every request that runs something (`call`, `run`, waterfall runs) accepts an `options` object. The same object is the default for a workspace (Settings → **Options**), for an API key, and on a preset. ```json { "input": { "domain": "example.com" }, "options": { "timing": { "timeout_ms": 8000, "deadline_ms": 30000 }, "cost": { "max_cost_micro": 50000 }, "data": { "cache": { "mode": "prefer", "max_age_s": 604800 } }, "observability": { "log_level": "metadata" } } } ``` ## Precedence [#precedence] Options merge leaf by leaf, later layers winning: ```text built-in defaults < workspace defaults < key defaults < preset < request (headers, then body) ``` Arrays and scalars replace; objects merge. The built-in defaults are cache `prefer` with writes on, stored records and bodies, `sync` delivery, and full logging with the live tail on. Then the result is clamped to your plan: | Plan | Max cache TTL | Max concurrency | Max retries | Max deadline | | ---- | ------------- | --------------- | ----------- | ------------ | | Free | 30 days | 5 | 2 | 60 s | | Pro | 180 days | 25 | 3 | 120 s | | Team | 365 days | 100 | 5 | 300 s | `log_level: none` becomes `metadata`, because every call is metered. A workspace that keeps no bodies turns `full` into `metadata`. `POST /v1/options/resolve` previews the result: the effective `options`, which layer set each leaf (`sources`) and every path that was lowered (`clamped`). Every call's log row stores the options it ran with. ## Headers [#headers] | Header | Option | | -------------------------------------------------- | -------------------------------------------------------------------- | | `X-Grid-Max-Cost: 0.05` | `cost.max_cost_micro` (the header is in USD; `0.05` is 50,000 micro) | | `X-Grid-Preset: @slug` | `routing.preset` | | `Idempotency-Key` (8–128 of `A-Z a-z 0-9 _ . : -`) | replays the first response for the same key and body | | `Cache-Control: no-store` | skip the cache and do not write to it | | `Cache-Control: no-cache` | refresh: call the provider and overwrite the cached result | | `Cache-Control: only-if-cached` | answer from the cache or fail | | `Cache-Control: max-age=N` | accept cached results up to N seconds old | | `Prefer: respond-async` / `Prefer: wait=N` | asynchronous waterfall runs | Body `options` win over headers. ## What takes effect today [#what-takes-effect-today] | Option | Effect | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `data.cache.*` | The [private cache](/docs/concepts/private-cache) policy | | `data.store.records`, `data.store.bodies` | `false` stops cache writes, or stops storing request and response bodies | | `data.fields` | Fields returned by `run` and waterfall runs when the body sets none | | `timing.timeout_ms` | Per-attempt provider timeout; caps every waterfall step | | `timing.deadline_ms` | Deadline for a whole `run` or waterfall run | | `timing.retry.max`, `timing.retry.base_ms`, `timing.hedge_after_ms` | Waterfall step retries, backoff and hedging | | `concurrency.max_concurrency` | Parallel steps in a waterfall stage | | `cost.max_cost_micro` | Spend cap for `call`, `run` and waterfall runs | | `routing.provider`, `routing.preset` | [Provider preferences](/docs/concepts/routing#provider-preferences) and preset for `run` | | `identity.meta` | Meta tags (≤ 16 keys, values ≤ 500 characters) when the body has none | | `observability.log_level`, `redact_fields`, `tail` | Body logging, masked keys, and whether the call shows on the live tail | The schema also accepts `rate`, `delivery.mode`, `cost.daily_cap_micro`, `cost.dry_run`, `timing.schedule` and a few more. They validate, merge and are logged, and the editor marks them, but nothing acts on them yet. The full JSON Schema is public at `GET /v1/options/schema`. Workspace defaults are [`GET`](/docs/api/calls/options_defaults_get) / [`PUT /v1/options/defaults`](/docs/api/calls/options_defaults_put) and a key's defaults are [`PUT /v1/keys/{id}/options`](/docs/api/access/keys_options_set). # Integrations (/docs/concepts/integrations) A **destination** is where [alerts](/docs/concepts/alerts) go. Connect destinations in the dashboard under Settings → **Alerts & integrations**, or with a key that has `credentials:write`. A rule notifies every enabled destination by default, or only the ones it lists. ```bash curl https://api.gridrouter.io/v1/alerts/destinations \ -H "Authorization: Bearer $GRID_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "On-call", "min_severity": "critical", "config": { "type": "pagerduty", "region": "us" }, "secret": "" }' ``` Every destination has a `name`, `enabled`, a `min_severity` (alerts below it aren't sent there, default `info`) and `notify_on_resolve` (default on). The `secret` (a webhook URL, routing key or API key) is stored encrypted in your workspace's vault and is never returned: reads show a masked hint such as `https://hooks.slack.com/…abcd` or `…abcd`. Send a new `secret` with `PUT /v1/alerts/destinations/{id}` to replace it. A workspace can have up to 20 destinations. ## Lifecycle [#lifecycle] What each destination receives as an alert moves through its [lifecycle](/docs/concepts/alerts#lifecycle): | Alert | Email | Webhook | Slack, Discord, Teams | PagerDuty | Opsgenie | | ------------ | -------------------------------------- | ----------------- | --------------------- | ----------------------------- | --------------- | | Triggered | An email, or a line in the next digest | `alert.triggered` | A message | `trigger` (opens an incident) | Create an alert | | Acknowledged | Nothing | Nothing | Nothing | `acknowledge` | Acknowledge | | Resolved | An email, or a digest line | `alert.resolved` | A "Resolved" message | `resolve` | Close | Resolutions are sent only when the destination's `notify_on_resolve` is on. Alerts from a [muted](/docs/concepts/alerts#mute) rule send nothing. ## Email [#email] Configure `{ "type": "email", "recipients": ["oncall@example.com"], "digest": "immediate" }` with 1 to 20 recipients. Email takes no secret. * **`immediate`** sends one email per trigger and resolution. The subject is `[GridRouter] : `, and the body has the alert's message, the rule, severity, status, value, threshold, subject, start time, how often it repeated and a link to the alert. * **`hourly`** or **`daily`** collects alerts into one digest per hour or day, sent at the first hour or day boundary (UTC) after the oldest alert in it, with up to 200 alerts. Email is sent once and not retried, so a partial failure never repeats to recipients who already got it. ## Webhooks [#webhooks] Connect one of your [webhook endpoints](/docs/concepts/webhooks) with `{ "type": "webhook", "endpoint_id": "whe_…" }`. The rules routed to this destination send their alerts to that endpoint as signed `alert.triggered` and `alert.resolved` events, even if the endpoint doesn't subscribe to those types. Deliveries follow the webhook [retry schedule](/docs/concepts/webhooks#retries) and show in its delivery log. The endpoint's signing secret is its own; this destination takes no secret. ## Slack [#slack] Alerts post to a channel through a Slack **incoming webhook**. Go to [api.slack.com/apps](https://api.slack.com/apps) and **Create New App** → **From scratch**. Name it (for example "GridRouter alerts") and pick your workspace. Open **Incoming Webhooks** and turn on **Activate Incoming Webhooks**. Click **Add New Webhook to Workspace**, choose the channel and click **Allow**. Copy the **Webhook URL**. It starts with `https://hooks.slack.com/services/`. Paste it as the destination's secret. The message uses Block Kit: a header such as "Warning: Error-rate spike", the alert's message, a field for each fact (rule, severity, status, value, threshold, subject, start time, occurrences), an **Open in GridRouter** button and the alert id. Text is sent as plain text, so nothing in an alert can mention a user or channel. The webhook URL decides the channel; the optional `channel` setting is a label for your reference. ## Discord [#discord] In your server, open **Server Settings** → **Integrations** → **Webhooks**. Click **New Webhook**, name it, and choose the channel. Click **Copy Webhook URL**. It starts with `https://discord.com/api/webhooks/`. Paste it as the destination's secret. The message is an embed from "GridRouter": the title links to the alert, the color follows the severity (green once resolved), and each fact is an inline field. Mentions are disabled, so an alert can never ping `@everyone` or a role. ## Microsoft Teams [#microsoft-teams] Teams alerts go through a **Workflows** webhook. The older Office 365 connectors (incoming webhook connectors) are retired; use Workflows. In Teams, open the channel, click **•••** next to its name and choose **Workflows**. Pick the template **Post to a channel when a webhook request is received**, name the workflow, and confirm the team and channel. Copy the URL the workflow shows, for example `https://prod-00.westus.logic.azure.com/workflows/…`. Paste it as the destination's secret. The message is an Adaptive Card (version 1.4): a bold title colored by severity, the alert's message, a fact set and an **Open in GridRouter** action. Workflows URLs on `*.logic.azure.com`, `*.environment.api.powerplatform.com` and `*.webhook.office.com` are accepted. ## PagerDuty [#pagerduty] GridRouter uses the PagerDuty **Events API v2**. In PagerDuty, open the **Service** that should be paged and go to its **Integrations** tab. Click **Add integration** (or **Add another integration**), choose **Events API V2** and add it. Copy the **Integration Key**: 32 letters and digits. Paste it as the destination's secret. If your PagerDuty account is in the EU service region, set `"region": "eu"` (events go to `events.eu.pagerduty.com`); otherwise leave the default `us`. Each GridRouter alert is one PagerDuty incident: the alert id is the `dedup_key`, so trigger, acknowledge and resolve all land on the same incident, and repeats are deduplicated. The event's summary is the alert's title and message, `source` is `gridrouter`, `component` is the alert's subject (or `workspace`), `group` is the metric, `class` is the rule name, and the facts are in `custom_details`, with a link back to the alert. ## Opsgenie [#opsgenie] GridRouter uses the Opsgenie **Alert API**. In Opsgenie, go to **Settings** → **Integrations** and add an **API** integration. Name it and assign the team that should be alerted. Copy the integration's **API key**, and save the integration with it turned on. Paste the key as the destination's secret. If your Opsgenie account is in the EU region, set `"region": "eu"` (requests go to `api.eu.opsgenie.com`); otherwise leave the default `us`. Each GridRouter alert is one Opsgenie alert with the GridRouter alert id as its `alias`, so acknowledging and resolving in GridRouter acknowledge and close it by alias. The Opsgenie alert's message is the title, the description has the message and a link, `source` is `GridRouter`, `entity` is the subject (or `workspace`), the tags are `gridrouter`, the metric and the severity, and the facts are in `details`. ## Severity mapping [#severity-mapping] GridRouter severities map to PagerDuty severities and Opsgenie priorities. These are the defaults; change them per destination with `severity_map` (PagerDuty: `critical`, `error`, `warning`, `info`) or `priority_map` (Opsgenie: `P1` to `P5`). | GridRouter severity | PagerDuty severity | Opsgenie priority | | --- | --- | --- | | `critical` | `critical` | `P1` | | `warning` | `warning` | `P3` | | `info` | `info` | `P5` | ```json { "type": "opsgenie", "region": "eu", "priority_map": { "critical": "P1", "warning": "P2", "info": "P5" } } ``` ## Test a destination [#test-a-destination] **Send test** in the dashboard, or `POST /v1/alerts/destinations/{id}/test`, delivers "Test alert from GridRouter" right away and returns `ok`, the HTTP `status`, `latency_ms` and any `error`. PagerDuty and Opsgenie tests open and immediately resolve their own incident, so nobody is left paged. Test emails are queued for the mailer, and the result says `queued: true`. To test every destination a rule notifies at once, use `POST /v1/alerts/rules/{id}/test`. ## Delivery [#delivery] * Slack, Discord, Teams, PagerDuty and Opsgenie notifications are retried up to 6 attempts, with backoff from 30 seconds, on `408`, `409`, `425`, `429`, `5xx` and network errors. Other errors are final. * Each result is recorded on the alert's timeline ("sent to" or "failed") and in the destination's health: status, deliveries, failures, consecutive failures and the last error. * Every URL passes the same checks as [webhook endpoints](/docs/concepts/webhooks#url-rules) when saved and before each send, and must be on that service's own hosts: `hooks.slack.com` for Slack, `discord.com` for Discord and the Workflows hosts above for Teams. Redirects are never followed. # Logs, live tail and drains (/docs/concepts/logs-and-drains) Every call, waterfall step, job and list update is written to your workspace's log and published to its **live tail**. The dashboard, the [CLI](/docs/cli), the [SDK](/docs/sdk) and [MCP clients](/docs/mcp) subscribe to the same stream, and **log drains** batch it out to your webhook, Axiom, Datadog or object storage. ## Search the log [#search-the-log] `/logs` and [`GET /v1/logs`](/docs/api/logs/logs_list) share one query language: ```text provider:hunter status:>=400 -capability:email.find latency:>2000 cost:<0.05 error:"rate limited" ``` * `field:a,b` includes values and `-field:a` excludes them. Fields: `outcome`, `status`, `provider`, `capability`, `endpoint`, `billing`, `client`, `client_mode`, `mode`, `credential`, `key`, `error`, `country` and `cache`. * `latency` (ms), `cost` (USD) and `status` take `>`, `>=`, `<`, `<=` and `a..b`. `status:4xx` is 400–499. * A bare word searches call, run and parent ids, the endpoint and the error code. Export streams CSV or NDJSON for the current filter, up to 10,000 rows. ## Live tail [#live-tail] `GET /v1/logs/live` streams over WebSocket, or SSE with `?format=sse`. It needs `logs:read`. ```bash curl -N "https://api.gridrouter.io/v1/logs/live?format=sse&kinds=call&status=error" \ -H "Authorization: Bearer $GRID_API_KEY" ``` | Filter | Meaning | | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | `kinds` | `call`, `run`, `job`, `list`, `alert` (default all) | | `provider`, `capability`, `endpoint_id`, `key_id`, `app_id`, `credential`, `http_status`, `error_code` | Call dimensions | | `status` | `hit`, `miss`, `failed` (`error` is an alias) | | `run_id`, `waterfall_id` | One run and its attempts, or one waterfall | | `latency_min`, `cost_min` | Minimum latency (ms) and cost (micro-USD) | | `query` | The log query language above (calls only) | | `sample` | 0–1, deterministic: every subscriber keeps the same events | | `fields` | Project call rows to these columns | | `replay` | Buffered events sent first, 0–1,000 (default 100) | | `max_rate` | Events per second for this subscriber (default 500, max 5,000) | Each frame is JSON with `seq`, `ts` and `shard`; `(shard, seq)` is unique, so de-duplicate on it after a reconnect. Control frames share the stream: `hello`, `dropped` (events this subscriber missed because it was too slow) and `heartbeat` (every 15 s). A stream is closed after 30 minutes; reconnect and replay. `GET /v1/logs/live/recent?limit=50` returns the newest events without streaming. A call made with `observability.tail: false` is logged but not published to the tail. ## Alerts [#alerts] Fast [alert rules](/docs/concepts/alerts) (error rate, spend, provider failures, vendor keys and billing mismatches over windows up to an hour) run on the tail as calls arrive, and alerts reach the dashboard as `alert` events (`kinds=alert`). Rules, destinations and [webhooks](/docs/concepts/webhooks) are documented on their own pages. ## Drains [#drains] Log drains are a Pro feature (2 drains; Team and above unlimited). On Free, creating one fails with `plan_limit_reached`. | Type | Delivery | | ----------------- | ------------------------------------------------------------------------- | | `webhook` | `POST {drain_id, batch_id, events}` as JSON, signed with `Grid-Signature` | | `axiom` | NDJSON to your dataset's ingest endpoint (`token`) | | `datadog` | JSON to the Logs intake, `ddsource: gridrouter` (`api_key`) | | `s3`, `gcs`, `r2` | SigV4-signed `PUT` of `prefix/YYYY/MM/DD/HH/.ndjson.gz` | Batches go out at 200 events or after 5 s (configurable up to 1,000 events and 60 s). `batch_id` is stable, so de-duplicate on it. 408, 429, 5xx and network errors retry 8 times with backoff from 10 s up to 30 minutes. Each drain reports its health: `idle`, `healthy`, `degraded`, `failing` or `disabled`. A webhook drain's `whsec_…` secret is shown once. Verify each batch against `Grid-Signature: t=,v1=` with a 5-minute tolerance. Drain credentials are write-only, and batches carry only public call columns, never bodies. # Merge rules (/docs/concepts/merge-rules) Every hit in a stage is a merge candidate: its fields, the provider, its confidence, whether it was verified, the endpoint's quality score and the order it ran in. Misses are not candidates. For each field that any candidate filled, the stage picks one value with that field's strategy, set in `merge.fields`, or `merge.default` when the field has none. ## Strategies [#strategies] | Strategy | Picks | Ties broken by | | ----------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `first_non_null` | The first filled value in step order | — | | `highest_quality` | The endpoint with the highest quality score | confidence, then verified, then order | | `prefer_verified` | A verified value | confidence, then order | | `most_recent` | The newest value by `merge.recency_field` (default `updated_at`), or when the attempt finished | order | | `consensus` | The value most providers agree on, compared case- and whitespace-insensitively | the best-quality candidate among the tied values | | `union` | Every distinct item across providers, flattened from arrays, in step order | — | ## Worked example [#worked-example] A stage runs three providers with `all_then_merge`, `merge.default: "highest_quality"` and `merge.fields: { "email": "consensus" }`: | Provider | Quality | `email` | `title` | | -------- | ------- | ------------------------ | -------------------------- | | A | 0.82 | `ada@example.com` | `CTO` | | B | 0.91 | `ADA@example.com ` | `Chief Technology Officer` | | C | 0.77 | `a.lovelace@example.com` | (empty) | * `email` uses `consensus`. A and B agree once case and spaces are ignored, so they win 2 to 1, and B is kept because it has the higher quality. C goes in the conflicts list. * `title` uses the default `highest_quality`, so B is picked. A's `CTO` is a conflict. C didn't fill the field, so it isn't a candidate. ```json { "data": { "email": "ADA@example.com ", "title": "Chief Technology Officer" }, "_provenance": { "email": { "provider": "b", "strategy": "consensus", "confidence": 0.9, "verified": true, "conflicts": [{ "provider": "c", "value": "a.lovelace@example.com" }] }, "title": { "provider": "b", "strategy": "highest_quality", "conflicts": [{ "provider": "a", "value": "CTO" }] } } } ``` Each provenance entry also carries `endpoint_id`, `call_id`, `stage_id`, `step_id` and `fetched_at`. The `conflicts` list holds up to 20 disagreeing values; `union` fields have none. Show conflicts to a reviewer rather than dropping them. ## Across stages: the golden record [#across-stages-the-golden-record] A pipeline merges inside each stage, then builds the run's `data` from its stages in order. The **first stage to fill a field keeps it**; later stages only add fields that are still empty. Put the stage you trust most for a field first, or use `fields` on a later stage so that stage returns only what it's there to add: ```json { "id": "company", "capability": "company.enrich", "fields": ["company_name", "industry", "employee_count"] } ``` Later stages read earlier ones in two ways. Capability inputs fill from the golden record by name. `input_map` reads a specific value with `stages..` or `input.`. A `when` on a stage or step can test golden-record fields, including `_verified` and `_confidence`. # Plans and pricing (/docs/concepts/plans) Every workspace is on **Free**, at no cost. Calls run on your own vendor keys and GridRouter never charges for them. Nothing can be bought yet: paid plans, credit top-ups and GridRouter's managed vendor accounts are coming soon. ## Free [#free] These limits come from the same plan definitions as the [pricing page](/pricing) and enforcement: | Limit | Value | | --- | --- | | Logged calls a month | 100k | | Log retention | 30 days | | Cached records (private) | 50k | | Bodies storage | 1 GB | | Workspaces | 2 | | Waterfalls and pipelines | 5 | | Queues | 1 | | API keys | 25 | | Live tail, MCP, API and SDK | Included | | Log drains and destinations | None | | Read-only SQL | Not included | | Anomaly alerts | Not included | | Subscription tracker | Not included | | Rebilling and white-label | Not included | | BYOK calls | Free | | Managed vendor calls | List +20% | ## Always free [#always-free] GridRouter never charges for: * Calls made with your own vendor keys (BYOK). Your provider bills you, and [billing verification](/docs/concepts/billing-verification) checks that it billed correctly. * Failed calls, and misses on providers that charge per hit. * Private cache hits. * Reads of your own data, logs and the catalog, and exports in any format. ## How paid plans will be metered [#how-paid-plans-will-be-metered] GridRouter prices the platform, not the data. When paid plans open, a plan's limits are soft: going past one never breaks a call, and the overage is billed per block (logged calls, cached records and stored bodies, each measured as a monthly average). Calls on GridRouter's managed vendor accounts will be charged at the provider's price plus a published markup, from a prepaid balance. Money in the API is always integer micro-USD: 1,000,000 is $1. `GET /v1/plans` and `GET /v1/entitlements` return the plan definitions and your workspace's current limits. # Private cache (/docs/concepts/private-cache) Every workspace has its own encrypted cache. Nothing is shared between workspaces: keys include the workspace id, and every value is sealed with AES-256-GCM under a key only that workspace can unwrap. ## Two kinds of record [#two-kinds-of-record] | Kind | Used by | Answers | | ------------ | ------------------------------------------------------ | ------------------------------------------------------------ | | **Entity** | `/v1/run`, `/v1/run/auto`, single-stage waterfall runs | Any provider, field by field, for the same person or company | | **Response** | `/v1/call` on GridRouter's managed vendor accounts | The same endpoint with the same normalized input | Calls on your own vendor keys never use the response cache, so at launch repeats are answered by the entity cache through `/v1/run` and waterfalls. An entity is found by any identity it carries, strongest first: B2B profile URL, email, name at domain, domain, company name. An enrichment by email is found again by B2B profile URL. Use the `/in/` path to recognize a person's profile. Inputs are normalized first: emails are lowercased with `+tags` removed, domains reduce to the registrable domain, company legal suffixes are dropped. When every wanted field is fresh, the answer is a free `hit`. When some are, it is a `partial`: the route runs and the cached fields fill what the providers leave empty. A single-stage waterfall skips the providers whose fields are already fresh. ## Freshness [#freshness] | Field class | Default TTL | Field class | Default TTL | | ---------------- | ----------- | ---------------- | ----------- | | `work_email` | 90 days | `technographics` | 14 days | | `personal_email` | 90 days | `signals` | 1 day | | `phone` | 180 days | `verification` | 30 days | | `title` | 30 days | `social` | 30 days | | `firmographics` | 30 days | `other` | 30 days | A value is kept for the shortest of: its class TTL (overridable per workspace), the provider's data terms (providers that forbid storage are never cached), your plan's maximum (30 days on Free) and the request's `ttl_s`. ## Per request [#per-request] Set `data.cache` in the [execution options](/docs/concepts/execution-options), or use `Cache-Control`: | `mode` | Header | Meaning | | ------------------ | ---------------- | ----------------------------------------------------------------------------- | | `prefer` (default) | | Serve fresh fields, fetch the rest | | `refresh` | `no-cache` | Always fetch, then write | | `only` | `only-if-cached` | Never call a provider; a miss is `404 not_found` with `details.cache: "miss"` | | `bypass` | `no-store` | No read, no write | `max_age_s` (`Cache-Control: max-age=N`) is the oldest value this request accepts, `stale_while_revalidate_s` serves a stale value while refreshing it in the background, and `write: false` reads without writing. ## Response headers [#response-headers] | Header | Value | | -------------------- | ------------------------------------------------------------------------------------------------ | | `X-Grid-Cache` | `hit`, `partial`, `stale` or `miss` when the cache was consulted; `bypass` on an explicit bypass | | `X-Grid-Cache-Age` | Seconds since the value was fetched | | `X-Grid-Fetched-At` | When it was fetched (ISO, UTC) | | `X-Grid-Saved-Micro` | Provider spend the answer avoided, in micro-USD (list price for your own keys) | The call body carries the same facts in `cache`, with `fields_cached` and `fields_fetched`. ## Manage it [#manage-it] `/cache` shows savings, a 30-day hit chart and an explorer with masked labels (never values). * [`DELETE /v1/cache`](/docs/api/cache/cache_purge) purges by key, tag or capability; `all=true` destroys the workspace's cache key, so every value becomes unreadable at once. * [`POST /v1/cache/forget`](/docs/api/cache/cache_forget) deletes every record about a person or company under any identity, for data subject requests. * [`POST /v1/cache/feedback`](/docs/api/cache/cache_feedback) drops fields (after a bounce, say) so the next request fetches them again. Free keeps up to 50,000 records. At the limit, new records are not written and existing ones still update. # Routing and fallbacks (/docs/concepts/routing) `POST /v1/call/{provider}/{endpoint}` runs one endpoint and never routes. `POST /v1/run/{capability}` plans a list of endpoints that serve the capability and tries them in turn. ## The plan [#the-plan] 1. **Candidates.** Every live endpoint for the capability. Endpoints whose circuit breaker is open, whose required inputs you did not send, or that your filters exclude drop out. 2. **Order.** Your `provider.order` or `sort` when given; otherwise the capability's declared route, if it has one. With nothing to decide the order, GridRouter load-balances: providers with recent errors go last and the rest are drawn with weight 1/price². 3. **Walk.** Each attempt is quoted, run and settled on its own. The run stops at the first **hit** (or the first successful response with `"stop_when": "success"`), and falls through on misses, provider errors and providers you have not added a key for. A run stops immediately on account errors, because a fallback would fail the same way: `insufficient_balance`, `budget_blocked`, `account_frozen`, `scope_denied` and `max_cost_exceeded`. When no provider could run because none has your key, the error is one `vendor_key_required` naming all of them. Every attempt is in the result's `attempts`, with its outcome (`hit`, `miss`, `failed`, `skipped`), cost, latency and error code. ## Provider preferences [#provider-preferences] Send them as `provider` in the run body, or save them in a [preset](/docs/api/calls/presets_create). | Field | Effect | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `order` | Try these first, in this order. Provider slugs (`hunter`) or endpoint ids (`hunter/email.find`); at most 20 | | `allow_fallbacks` | Default `true`. With `false`, only the providers in `order` are tried | | `only` / `ignore` | Keep only, or drop, these providers or endpoints | | `sort` | `price`, `reliability`, `latency`, `throughput` or `quality` | | `max_cost_micro` / `max_price_micro` | Skip endpoints whose quote (or worst-case price) is above this. The lower of the two wins | | `preferred_max_latency_ms` | Endpoints with a median latency above this go after the ones under it | | `data_policy.storage` | `any` (default), `reviewed` (drop providers whose data terms are not reviewed yet) or `storable` (only providers whose results may be kept) | | `data_policy.zdr` | `true` stops GridRouter from storing this call's request and response bodies | | `require_verified` | Only providers GridRouter has verified | ```json { "input": { "first_name": "Ada", "last_name": "Lovelace", "domain": "example.com" }, "provider": { "order": ["prospeo", "hunter"], "allow_fallbacks": false }, "fields": ["email", "confidence"], "stop_when": "hit" } ``` `fields` (at most 50) trims the result to the normalized output fields you name. `preset: "@slug"` applies a saved preset; anything in the request body overrides it. ## Cost caps [#cost-caps] The per-request cap is `max_cost_micro` in the body or `X-Grid-Max-Cost` in USD as a header. An attempt whose quote exceeds what is left is skipped, and a single `call` over the cap fails with `402 max_cost_exceeded` before anything runs. `POST /v1/quote/{provider}/{endpoint}` prices a call without making it. Failed attempts and misses on per-success endpoints are never charged. At launch every call runs on your own vendor keys and costs `0`. # Security (/docs/concepts/security) ## Roles and scopes [#roles-and-scopes] Each member has one role per workspace. A role maps to the scopes its dashboard session and MCP grants can use: | Scope | Owner | Admin | Developer | Billing | Viewer | | --- | --- | --- | --- | --- | --- | | `catalog:read` | Yes | Yes | Yes | Yes | Yes | | `balance:read` | Yes | Yes | Yes | Yes | Yes | | `logs:read` | Yes | Yes | Yes | Yes | Yes | | `billing:write` | Yes | Yes | | Yes | | | `keys:write` | Yes | Yes | Yes | | | | `agents:write` | Yes | Yes | | | | | `credentials:write` | Yes | Yes | Yes | | | | `presets:write` | Yes | Yes | Yes | | | | `pipelines:read` | Yes | Yes | Yes | Yes | Yes | | `pipelines:write` | Yes | Yes | Yes | | | | `cache:write` | Yes | Yes | Yes | | | API keys carry their own scopes and never more than their creator holds. Every operation checks its scope, and the workspace always comes from the authenticated key, never from the request. ## API keys [#api-keys] * Stored only as an HMAC-SHA256 with a versioned server-side pepper, and verified in constant time. GridRouter cannot show a key again after it is created. * Checked in order: checksum, lookup, HMAC, expiry, IP allowlist (against the connecting IP; `X-Forwarded-For` is never read). Expiry and IP errors are returned only after the HMAC proves the caller holds the key. * Revocation stops billable calls and key management immediately. * Owners can issue 10 one-time recovery codes (Settings → **Security**). `POST /v1/recovery` redeems one for a new owner key if every owner key is lost. ## Vendor credentials [#vendor-credentials] Each workspace has its own data-encryption key, wrapped by a versioned key-encryption key that only the vault service can use. Vendor keys are sealed with AES-256-GCM, bound to the workspace, provider, slot and credential id, so a ciphertext moved anywhere else fails to decrypt. The API is write-only; a key is decrypted in memory only for the provider call. ## Your data [#your-data] * Logs never contain `Authorization`, cookies, API keys or vault plaintext. Request and response bodies are stored only when your options allow it, and `redact_fields` masks named fields. * The [private cache](/docs/concepts/private-cache) is sealed per workspace, and destroying its key makes every cached value unreadable at once. * Every tenant table in Postgres has row-level security forced on, keyed to the workspace. * Membership, role, key and credential changes are written to a per-workspace hash-chained audit log. * Calls to providers go only to reviewed hosts over HTTPS, with no IP literals and every redirect re-validated. ## Dashboard sign-in [#dashboard-sign-in] Email and password with required verification. Five failed sign-ins for one email within 15 minutes lock it for 15 minutes. Sessions last 7 days, and a password reset signs out every other session. Session cookies are first-party, `HttpOnly` and `Secure`. Settings → **Security** lists your sessions and signs them out. ## Reporting a vulnerability [#reporting-a-vulnerability] Email **[security@gridrouter.io](mailto:security@gridrouter.io)**. We acknowledge within 2 business days and fix or mitigate critical issues within 7 days. Good-faith research against accounts you own is authorized. If you leak a key, revoke it at once and rotate with a backup key in place. # Waterfall templates (/docs/concepts/waterfall-templates) A template is a prebuilt [waterfall](/docs/concepts/waterfalls). Each step names a capability rather than a provider, so the router chooses the providers unless you pin them. Browse them with the explanations of each step at [/waterfalls/templates](/waterfalls/templates). This page is generated from the same library as the API (`GET /v1/waterfalls/templates`). ## Status [#status] | Status | Meaning | | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Ready | Routed providers can run every stage today on your own vendor keys. `availability.vendor_keys` lists the keys that unlock it; one key per stage is enough. | | Sandbox | Runs on the `sandbox-*` providers with a `grid_test_` key, no vendor key needed. Sandbox calls are priced like real ones and draw on your credit. Use the `scenario` input to script hits, misses and timeouts. | | Preview | Providers document the capability publicly, but none is routed yet. You can read the steps; creating one returns `422 validation_failed`. | Costs are list prices per run from the catalog: the minimum is the cheapest provider per stage and the maximum is every eligible provider trying, capped by the template's `max_cost_micro`. Conditional stages count 0 toward the minimum. With your own keys, GridRouter charges $0 and the provider bills its own rate. ## Contacts [#contacts] | Template | Status | Inputs | Outputs | Capabilities | Speed · mode | Per run | | --- | --- | --- | --- | --- | --- | --- | | `work-email` Work email finder: Name + company domain → a verified work email. | Ready | `first_name`, `last_name`, `domain` | `email`, `confidence`, `status`, `mx_provider` | `people.email.find` → `email.verify` | Balanced: one at a time, hedged · Sync (one request) | $0.012–$0.078 | | `email-from-profile` Email from a B2B profile URL: B2B profile URL → name and employer → verified work email. | Ready | `profile_url` | `full_name`, `title`, `company_name`, `company_website`, `email`, `confidence`, `status`, `mx_provider` | `people.enrich` → `people.email.find` → `email.verify` | Balanced: one at a time, hedged · Sync (one request) | $0.012–$0.090 | | `mobile-number` Mobile number finder: Profile URL or email → a mobile / direct dial. | Ready | `profile_url`?, `work_email`?, `personal_email`? (Send at least one of profile_url, work_email or personal_email.) | `mobile_number` | `phone.mobile.find` | Thorough: cheapest first · Sync (one request) | $0.060 | | `email-verification` Email verification (consensus): One address → a verdict that several verifiers agree on. | Ready | `email` | `status`, `mx_provider` | `email.verify` | Fast: providers race · Batch (lists) | $0.016 | | `catch-all-resolution` Catch-all resolution: Keep verifying until a verifier gives a definitive valid or invalid. | Ready | `email` | `status`, `mx_provider` | `email.verify` | Thorough: cheapest first · Batch (lists) | $0.0035–$0.016 | | `reverse-email-lookup` Reverse email lookup: Email → the person behind it: profile, title, employer. | Ready | `email` | `profile_url`, `full_name`, `first_name`, `last_name`, `title`, `company_name`, `company_website`, `location`, `country`, `work_experience` | `people.profile.find` → `people.enrich` | Balanced: one at a time, hedged · Sync (one request) | $0.120–$0.132 | | `phone-validation` Phone validation: Phone number → valid, line type and carrier. | Preview | `phone` | `valid`, `line_type`, `carrier_name`, `country_code`, `ported` | `phone.lookup` | Fast: providers race · Batch (lists) | — | | `dnc-check` Do-not-call check: Phone number → line type, then DNC and litigator lists before dialing. | Preview | `phone` | `line_type`, `listed`, `lists`, `litigator`, `reassigned` | `phone.lookup` → `compliance.dnc.check` | Balanced: one at a time, hedged · Batch (lists) | — | | `sandbox-work-email` Work email finder (sandbox): Swift, then Deep, then Sure on the sandbox vendors: runs on a test key, no vendor key needed. | Sandbox | `first_name`, `last_name`, `domain`, `scenario`? | `email`, `confidence` | `people.email.find` | Balanced: one at a time, hedged · Sync (one request) | $0.004–$0.028 | | `sandbox-mobile-number` Mobile number finder (sandbox): Cheapest-first mobile waterfall over the sandbox vendors. | Sandbox | `profile_url`?, `work_email`?, `scenario`? (Send profile_url or work_email.) | `mobile_number` | `phone.mobile.find` | Thorough: cheapest first · Sync (one request) | $0.015–$0.090 | ## People [#people] | Template | Status | Inputs | Outputs | Capabilities | Speed · mode | Per run | | --- | --- | --- | --- | --- | --- | --- | | `person-enrichment` Person enrichment: Profile URL or email → title, seniority, employer and history. | Ready | `profile_url`?, `email`? (Send profile_url, or email when you don't have it.) | `profile_url`, `full_name`, `first_name`, `last_name`, `title`, `company_name`, `company_website`, `location`, `country`, `work_experience` | `people.profile.find` → `people.enrich` | Balanced: one at a time, hedged · Sync (one request) | $0.012–$0.132 | | `job-change-detection` Job change detection: Profile URL + the company you know them at → did they move, and where. | Ready | `profile_url`, `domain`? | `job_change_detected`, `current_company`, `expected_company`, `summary`, `status` | `signals.job_change` | Balanced: one at a time, hedged · Batch (lists) | $0.036 | | `decision-makers` Decision maker by role: Company domain + job title → the person who holds it. | Ready | `domain`, `job_title` | `name`, `first_name`, `last_name`, `profile_url`, `company_name` | `people.role.find` | Balanced: one at a time, hedged · Sync (one request) | $0.024 | | `employee-list` Employee list: Company domain → people who work there, billed per row. | Ready | `domain`, `limit`? | `people`, `total_count` | `people.search` | Balanced: one at a time, hedged · Sync (one request) | $0.006–$0.036 | | `social-profiles` Social profiles: Email or name → the person's social profiles and handles. | Preview | `email` | `profile_url`, `platform`, `handle`, `followers` | `social.profile.find` | Balanced: one at a time, hedged · Sync (one request) | — | ## Company [#company] | Template | Status | Inputs | Outputs | Capabilities | Speed · mode | Per run | | --- | --- | --- | --- | --- | --- | --- | | `company-enrichment` Company enrichment: Domain → firmographics: headcount, industry, revenue, funding, stack. | Ready | `domain` | `name`, `employees`, `industry`, `website`, `description`, `founded_year`, `revenue`, `total_funding`, `technologies` | `company.enrich` | Balanced: one at a time, hedged · Sync (one request) | $0.012 | | `technographics` Technographics: Domain → the technologies a company runs. | Ready | `domain` | `technologies`, `technology_category` | `company.technographics` | Fast: providers race · Sync (one request) | $0 | | `funding-financials` Funding and financials: Domain → funding rounds, investors, revenue and filings. | Preview | `domain` | `total_funding_usd`, `last_round_type`, `last_round_date`, `investors`, `revenue_usd`, `fiscal_year` | `company.funding` → `company.financials` | Balanced: one at a time, hedged · Sync (one request) | — | | `hiring-signals` Hiring signals: Domain → open roles by department and hiring velocity. | Preview | `domain` | `open_roles`, `roles_by_department`, `growth_rate`, `job_title` | `signals.hiring` → `jobs.company_postings` | Balanced: one at a time, hedged · Sync (one request) | — | | `intent-signals` Intent surge by topic: Topic → accounts researching it more than usual this week. | Preview | `topic` | `company_domain`, `score`, `surging`, `week` | `signals.intent` | Balanced: one at a time, hedged · Async (poll or webhook) | — | | `news-monitoring` Company news: Domain or name → recent news mentions and events. | Preview | `domain` | `title`, `url`, `published_at`, `source_name`, `summary` | `news.company_mentions` | Balanced: one at a time, hedged · Sync (one request) | — | | `reviews-reputation` Reviews and reputation: Business domain or place → average rating, review count and recent reviews. | Preview | `domain`?, `place_id`? (Send domain or place_id.) | `average_rating`, `review_count`, `text`, `platform` | `reviews.business` | Balanced: one at a time, hedged · Sync (one request) | — | | `kyb-verification` KYB and sanctions screening: Company → registry record, officers and a sanctions/PEP screen. | Preview | `name`, `jurisdiction`? | `registration_number`, `status`, `incorporation_date`, `registered_address`, `role`, `match_count`, `lists` | `registry.company_lookup` → `registry.officers` → `compliance.sanctions.screen` | Thorough: cheapest first · Async (poll or webhook) | — | | `local-business-lookup` Local business lookup: Business name + area → address, phone, website, rating and hours. | Preview | `query`, `near` | `name`, `address`, `phone`, `website`, `rating`, `opening_hours` | `places.search` → `places.details` | Balanced: one at a time, hedged · Sync (one request) | — | | `ads-intelligence` Ads intelligence: Advertiser → what they run across Meta, Google and B2B networks. | Preview | `domain`, `query`? | `advertiser_name`, `headline`, `landing_url`, `first_seen`, `platform` | `ads.meta.search` → `ads.google.search` → `ads.linkedin.search` | Fast: providers race · Async (poll or webhook) | — | | `seo-presence` SEO and SERP presence: Domain → traffic, backlinks and where it ranks for a keyword. | Preview | `domain`, `query`? | `visits`, `referring_domains`, `authority`, `position` | `seo.traffic` → `seo.backlinks` → `serp.google.search` | Balanced: one at a time, hedged · Async (poll or webhook) | — | | `ip-to-company` IP to company: Visitor IP → the company behind it, with firmographics. | Preview | `ip` | `company_name`, `company_domain`, `is_isp`, `confidence`, `employees`, `industry` | `ip.company_lookup` → `company.enrich` | Fast: providers race · Sync (one request) | — | | `sandbox-company-enrichment` Company enrichment (sandbox): Race all three sandbox vendors and merge field by field. | Sandbox | `domain`, `scenario`? | `name`, `employees`, `industry`, `technologies` | `company.enrich` | Fast: providers race · Sync (one request) | $0.018 | ## Composite [#composite] | Template | Status | Inputs | Outputs | Capabilities | Speed · mode | Per run | | --- | --- | --- | --- | --- | --- | --- | | `full-lead-enrichment` Full lead enrichment: Name + domain → verified email, profile, title, mobile and company. | Ready | `first_name`, `last_name`, `domain`, `profile_url`? | `email`, `confidence`, `status`, `mx_provider`, `profile_url`, `full_name`, `title`, `company_name`, `company_website`, `location`, `country`, `work_experience`, `mobile_number`, `name`, `employees`, `industry`, `website`, `description`, `founded_year`, `revenue`, `total_funding`, `technologies` | `people.email.find` → `email.verify` → `people.profile.find` → `people.enrich` → `phone.mobile.find` → `company.enrich` | Balanced: one at a time, hedged · Async (poll or webhook) | $0.084–$0.282 | | `account-research-brief` Account research brief: Domain → firmographics, tech stack, hiring and news in one record. | Preview | `domain` | `name`, `employees`, `industry`, `website`, `technologies`, `open_roles`, `title` | `company.enrich` → `company.technographics` → `signals.hiring` → `news.company_mentions` | Balanced: one at a time, hedged · Async (poll or webhook) | — | | `inbound-lead-enrichment` Inbound lead enrichment: Form fill (email) → verified, with the person and company for routing. | Ready | `email`, `domain`? | `status`, `mx_provider`, `profile_url`, `full_name`, `first_name`, `last_name`, `title`, `company_name`, `company_website`, `location`, `country`, `work_experience`, `name`, `employees`, `industry`, `website`, `description`, `founded_year`, `revenue`, `total_funding`, `technologies` | `email.verify` → `people.profile.find` → `people.enrich` → `company.enrich` | Fast: providers race · Sync (one request) | $0.120–$0.172 | | `crm-hygiene` CRM hygiene: CRM record → re-verified email, job change check and refreshed company. | Ready | `email`?, `profile_url`?, `domain`? (Send whichever of email, profile_url and domain the record has.) | `status`, `mx_provider`, `job_change_detected`, `current_company`, `name`, `employees`, `industry`, `website` | `email.verify` → `signals.job_change` → `company.enrich` | Thorough: cheapest first · Batch (lists) | $0–$0.064 | | `decision-maker-emails` Decision maker + verified email: Domain + job title → the role holder and their verified work email. | Ready | `domain`, `job_title` | `name`, `profile_url`, `company_name`, `email`, `confidence`, `status`, `mx_provider` | `people.role.find` → `people.email.find` → `email.verify` | Balanced: one at a time, hedged · Batch (lists) | $0.024–$0.102 | | `sandbox-email-then-mobile` Email, then mobile (sandbox): Two sandbox stages: find the work email, then feed it to a mobile waterfall. | Sandbox | `first_name`, `last_name`, `domain`, `scenario`? | `email`, `mobile_number` | `people.email.find` → `phone.mobile.find` | Balanced: one at a time, hedged · Sync (one request) | $0.004–$0.088 | ## On the roadmap [#on-the-roadmap] These need a capability that no integrated provider exposes through a public API yet, or an engine feature. They ship when one does. | Template | Category | Waiting on | | --- | --- | --- | | `personal-email` Personal email finder: Profile URL → a personal address. | contacts | No catalog capability returns personal addresses, and no listed vendor documents a public API for it. | | `company-domain-lookup` Company name to domain: Company name → its website domain. | company | The catalog's company search filters by industry and size, not by name; no name-to-domain capability is defined yet. | | `lookalike-companies` Lookalike companies: Seed domain → companies like it. | company | No lookalike capability in the catalog; only one listed vendor documents lookalike search publicly, below the bar for a new capability. | | `competitors` Competitors: Domain → the company's direct competitors. | company | No competitor capability; listed vendors offer it behind sales-gated APIs or only as SEO keyword overlap. | | `company-profile-firmographics` Company profile URL → firmographics: B2B company page URL → firmographics. | company | Company enrichment takes a domain; no catalog capability takes a company profile URL as input yet. | | `ecommerce-store-data` E-commerce store data: Store domain → platform, apps, products and estimated sales. | company | commerce.store_lookup is in the catalog, but its one listed vendor has no public API docs. | | `ai-lead-scoring` AI lead scoring: Enriched lead → a fit score with reasons. | composite | A stage input maps one field, so a model step can't be given the whole enriched record as its prompt, and no model endpoint is routed yet. Score the Inbound lead enrichment output in your CRM for now. | | `ai-account-brief` AI-written account brief: Account research record → a five-line brief written by a model. | composite | Same gap as AI lead scoring: composing a prompt from several stages needs a prompt-template step the engine doesn't have yet. | | `icp-list-building` ICP list building: ICP filters → companies → people → verified emails. | composite | Company search is not routed yet and a run returns one record (no fan-out). Today: batch-run Decision maker + verified email over your target domains. | | `crm-dedupe` CRM dedupe and normalize: Merge duplicate records and normalize names, titles and domains. | composite | Dedupe works across rows and no capability does it; CRM hygiene covers the per-record re-verification. | ## Use one [#use-one] | Surface | Call | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | API | `POST /v1/waterfalls/from-template` `{"template":"work-email","pins":{"email":["hunter"]},"speed":"balanced","max_cost_micro":100000}` | | MCP | `waterfall_templates`, `waterfall_template_get`, `waterfall_create_from_template`, `waterfall_estimate`, `waterfall_run`, `waterfall_status` | | SDK | `grid.waterfalls.templates.list()`, `grid.waterfalls.fromTemplate("work-email")`, `grid.waterfalls.run(id, input)` | | Dashboard | Waterfalls → Templates → Use template opens it in the builder with its sample input in the test runner | `pins` maps a stage id to the provider slugs tried first. The router still falls back to other providers unless `pins_only` is `true`. `speed` is `fast` (race), `balanced` (one at a time, hedged) or `thorough` (cheapest first, 90 s deadline). The new waterfall is published as `1.0.0` unless you pass `"publish": false`. # Waterfalls (/docs/concepts/waterfalls) A **waterfall** is an ordered set of catalog endpoints for one capability, plus a speed profile, stop rules and a merge strategy per output field. A **pipeline** chains up to 10 waterfalls as stages, and a later stage can read an earlier one's output (`stages..`). Build them in the dashboard at `/waterfalls`, or with the [waterfall API](/docs/api/waterfalls/waterfall_create). Most start from one of the [waterfall templates](/docs/concepts/waterfall-templates) (browse them with each step explained at [/waterfalls/templates](/waterfalls/templates)); see [build a waterfall](/docs/concepts/build-a-waterfall) and [merge rules](/docs/concepts/merge-rules). Most start from one of the [waterfall templates](/docs/concepts/waterfall-templates) (browse them with each step explained at [/waterfalls/templates](/waterfalls/templates)); see [build a waterfall](/docs/concepts/build-a-waterfall) and [merge rules](/docs/concepts/merge-rules). ## Steps [#steps] A step is one endpoint (`hunter/email.find`) or a **routed** pool: the capability's endpoints, filtered with the same [provider preferences](/docs/concepts/routing#provider-preferences) as `/v1/run`. Each step can set a timeout, retries, a max cost, required fields, a minimum confidence, verified-only, what a provider 4xx does, and a `when` guard (field conditions such as `eq`, `gte`, `exists`, `in`, combined with `all`, `any` and `not`). ## Speed profiles [#speed-profiles] | Profile | Behavior | Default deadline | | ---------- | ----------------------------------------------------------------------- | ---------------- | | `fastest` | Starts 3 steps at once, hedges the next every 750 ms, aborts the losers | 15 s | | `balanced` | One at a time; hedges a slow step after 3 s | 30 s | | `cheapest` | Strictly sequential, lowest quote first | 60 s | | `custom` | Your concurrency, hedge delay, step timeout, deadline and sort | 30 s | ## Stop rules and merge [#stop-rules-and-merge] Stop rules combine with `stop_mode: any | all`: `first_hit`, `first_verified`, `until_fields_filled`, `all_then_merge` and `condition`. Each output field has its own merge strategy: `highest_quality`, `consensus`, `most_recent`, `prefer_verified`, `first_non_null` or `union`. Values that disagree are kept in `_provenance..conflicts`. ## Running [#running] | Mode | How | Response | | --------- | --------------------------------------------------------------- | --------------------------------------------------------------------------- | | Sync | `POST /v1/waterfalls/{id}/run` | `200` with the run (deadline capped at 50 s) | | Wait | `Prefer: wait=N` | `200` if done within N s, else `202` with a `Location` to poll | | Async | `Prefer: respond-async` | `202`; poll the run, stream `/events` (SSE) or `/ws`, or pass `webhook_url` | | Scheduled | `"delay_seconds": N` (≤ 12 h) | `202` | | Batch | `POST /v1/waterfalls/batch-run`, up to 1,000 JSON rows or a CSV | a list id; rows are paced per provider | Durable runs execute each attempt as its own step, so a crash resumes without paying for an attempt twice. `POST …/runs/{run_id}/cancel` stops a run between attempts. A run returns `outcome` (`hit`, `partial`, `miss`, `failed`), `stop_reason`, the merged record in `data`, `_provenance` per field (provider, call id, confidence, verified) and `_attempts`. Every attempt is its own row in the [call log](/docs/concepts/logs-and-drains) with the run id as its parent. ## Publish [#publish] Publishing freezes a semver version. A published waterfall is your own endpoint at `POST /v1/x/{workspace}/{name}`, an MCP tool call (`x_run`) and an OpenAPI document (`GET /v1/waterfalls/{id}/openapi`). Roll back with `POST /v1/waterfalls/{id}/rollback`. ## Errors [#errors] | Case | Behavior | | ------------------------------ | -------------------------------------------------------------------------------------- | | Invalid definition or input | `422 validation_failed` with `details.issues[].path` | | Provider 4xx | Not retried; next step | | Provider 429 | Next step now; back to this one after `Retry-After`, within the deadline | | Provider 5xx or timeout | Retried with backoff up to the step's `retries`, then the next step | | Run budget or deadline reached | Returns the partial record with `stop_reason` `budget_exceeded` or `deadline_exceeded` | | Every step misses | `200` with `outcome: miss` | | Account errors | Stop everything; the partial run is in `details.run` | # Webhooks (/docs/concepts/webhooks) A **webhook endpoint** is an HTTPS URL of yours that GridRouter posts events to. Each endpoint subscribes to the event types it wants, and every delivery is signed per the [Standard Webhooks](https://www.standardwebhooks.com) spec, retried with backoff for about a day, logged, and replayable. Webhooks are for events. To stream every call to your own storage in batches, use a [log drain](/docs/concepts/logs-and-drains#drains) instead. ## Endpoints [#endpoints] Create an endpoint in Settings → **Alerts & integrations**, or with a key that has `credentials:write`: ```bash curl https://api.gridrouter.io/v1/webhooks/endpoints \ -H "Authorization: Bearer $GRID_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/gridrouter", "description": "Production", "event_types": ["job.completed", "job.failed", "alert.triggered", "alert.resolved"] }' ``` The response includes the endpoint's signing `secret` (`whsec_…`). It is shown **once**; store it in your secret manager. Later reads show only its first characters. * **Subscriptions.** `event_types` lists the types delivered to the endpoint (up to 40). `["*"]` means every type, including types added later. * **Status.** `active`; `failing` after 3 failed attempts in a row; `disabled` when you turn it off or GridRouter [disables it](#auto-disable). * **Health.** Each endpoint reports deliveries, failures, consecutive failures, the last success and failure, and the last error (a status code or error class, never a response body). ### Alert events [#alert-events] An endpoint subscribed to `alert.triggered` and `alert.resolved` (or `*`) receives your alerts as they open and resolve. To send only some rules' alerts to an endpoint, connect it as a **webhook destination** (`{ "type": "webhook", "endpoint_id": "whe_…" }`) and route those rules to it; see [Integrations](/docs/concepts/integrations#webhooks). Alerts from muted rules send no webhook events. ## The envelope [#the-envelope] Every delivery is one JSON object: ```json { "id": "evt_job_completed_01j9x7k2m9q4", "type": "job.completed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "job": { "object": "job", "id": "job_01j9x7k2m9q4w8x1", "status": "succeeded" } } } ``` | Field | Meaning | | ------------- | ------------------------------------------------------------------------------- | | `id` | The event id (`evt_…`), the same for every endpoint that receives it | | `type` | One of the [event types](#event-reference) | | `api_version` | The payload version, currently `2026-10-01` | | `created_at` | When the event happened (ISO 8601, UTC) | | `test` | `true` on events sent with **Send test event**; absent otherwise | | `data` | The event's payload; its shape per type is in the [reference](#event-reference) | Payloads are versioned by `api_version`, and `GET /v1/webhooks/event-types` returns the current version with every type and an example. Write receivers to ignore fields and event types they don't recognize. ## Headers and signing [#headers-and-signing] | Header | Value | | ------------------- | ------------------------------------------------------------------------------ | | `webhook-id` | The delivery id (`msg_…`). The same on every retry and replay of this delivery | | `webhook-timestamp` | Unix seconds when this attempt was signed | | `webhook-signature` | One or more space-separated `v1,` | | `content-type` | `application/json` | | `user-agent` | `GridRouter-Webhooks/2.0` | Each signature is the base64 HMAC-SHA256 of `` `${webhook-id}.${webhook-timestamp}.${body}` ``, keyed by the base64-decoded bytes after `whsec_` in your secret. To verify: 1. Read the **raw** body exactly as received, before any JSON parsing. 2. Reject the request if `webhook-timestamp` is more than 5 minutes from your clock. 3. Compute the signature and compare it, in constant time, with each `v1,` entry in `webhook-signature`. Accept if any one matches. 4. Answer `2xx` within 15 seconds. Do slow work after you respond. ## Verify a delivery [#verify-a-delivery] `verifyWebhook` from `@relaygrid/sdk` checks the timestamp (5-minute tolerance by default, `toleranceSec` to change it) and every signature in the header. ```ts import { verifyWebhook } from "@relaygrid/sdk"; export async function POST(req: Request) { const body = await req.text(); const ok = await verifyWebhook(body, req.headers, process.env.GRID_WEBHOOK_SECRET ?? ""); if (!ok) return new Response("invalid signature", { status: 400 }); const event = JSON.parse(body); const deliveryId = req.headers.get("webhook-id"); // Skip deliveryId if you've already processed it, then handle event.type. return new Response(null, { status: 204 }); } ``` For Workers, Deno, Bun or any runtime with WebCrypto. `crypto.subtle.verify` compares in constant time. ```ts const b64 = (s: string) => Uint8Array.from(atob(s), (c) => c.charCodeAt(0)); export async function verifyGridWebhook( body: string, headers: Headers, secret: string, toleranceSec = 300, ): Promise { const id = headers.get("webhook-id"); const ts = headers.get("webhook-timestamp"); const sigs = headers.get("webhook-signature"); if (!id || !ts || !sigs || !/^\d+$/.test(ts)) return false; if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false; const key = await crypto.subtle.importKey( "raw", b64(secret.replace(/^whsec_/, "")), { name: "HMAC", hash: "SHA-256" }, false, ["verify"], ); const signed = new TextEncoder().encode(`${id}.${ts}.${body}`); for (const sig of sigs.split(" ")) { if (!sig.startsWith("v1,")) continue; try { if (await crypto.subtle.verify("HMAC", key, b64(sig.slice(3)), signed)) return true; } catch { // Not valid base64: not a match. } } return false; } ``` With Express, mount the route with `express.raw({ type: "application/json" })` so `req.body` is the raw bytes. ```ts import { createHmac, timingSafeEqual } from "node:crypto"; export function verifyGridWebhook( body: Buffer, headers: Record, secret: string, toleranceSec = 300, ): boolean { const id = String(headers["webhook-id"] ?? ""); const ts = String(headers["webhook-timestamp"] ?? ""); const sigs = String(headers["webhook-signature"] ?? ""); if (!id || !/^\d+$/.test(ts) || !sigs) return false; if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false; const expected = createHmac("sha256", Buffer.from(secret.replace(/^whsec_/, ""), "base64")) .update(`${id}.${ts}.`) .update(body) .digest(); return sigs.split(" ").some((sig) => { if (!sig.startsWith("v1,")) return false; const got = Buffer.from(sig.slice(3), "base64"); return got.length === expected.length && timingSafeEqual(got, expected); }); } ``` Pass the raw body bytes (`request.get_data()` in Flask, `await request.body()` in FastAPI). ```python import base64 import hashlib import hmac import time def verify_grid_webhook(body: bytes, headers, secret: str, tolerance: int = 300) -> bool: msg_id = headers.get("webhook-id") ts = headers.get("webhook-timestamp") sigs = headers.get("webhook-signature") if not msg_id or not ts or not sigs or not ts.isdigit(): return False if abs(time.time() - int(ts)) > tolerance: return False key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{ts}.".encode() + body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() return any( hmac.compare_digest(sig[3:], expected) for sig in sigs.split(" ") if sig.startswith("v1,") ) ``` Compute a signature by hand, for example to send a signed request to your own receiver while you build it: ```bash SECRET='whsec_…' # your endpoint's secret MSG_ID='msg_test0000000001' TS=$(date +%s) BODY='{"id":"evt_test_1","type":"job.completed","api_version":"2026-10-01","created_at":"2026-10-01T12:00:00.000Z","test":true,"data":{}}' KEY_HEX=$(printf '%s' "${SECRET#whsec_}" | base64 -d | xxd -p -c 256) SIG=$(printf '%s' "$MSG_ID.$TS.$BODY" \ | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$KEY_HEX" -binary | base64) curl -X POST https://example.com/webhooks/gridrouter \ -H "content-type: application/json" \ -H "webhook-id: $MSG_ID" \ -H "webhook-timestamp: $TS" \ -H "webhook-signature: v1,$SIG" \ --data-binary "$BODY" ``` ## Rotate the secret [#rotate-the-secret] `POST /v1/webhooks/endpoints/{id}/rotate-secret` issues a new secret and returns it once. The old one keeps signing alongside it for `overlap_s` (default 24 hours, up to 7 days; `0` retires it at once). During the overlap, `webhook-signature` carries two `v1,` signatures, the new secret's first, so a receiver that still has the old secret keeps verifying while you deploy the new one. The endpoint's `secrets` list shows both, with the old one's `expires_at`. ## Retries [#retries] An attempt succeeds when your endpoint answers `2xx` within 15 seconds. Anything else is a failed attempt and is retried: timeouts, network errors, `5xx`, `4xx` (receivers often return them while deploying) and redirects, which are never followed. The only failure that isn't retried is a URL that the [URL rules](#url-rules) now block. | Attempt | Sent | Time since the first attempt | | --- | --- | --- | | 1 | When the event happens | 0 s | | 2 | 5 seconds after attempt 1 failed | About 5 s | | 3 | 5 minutes after attempt 2 failed | About 5 min 5 s | | 4 | 30 minutes after attempt 3 failed | About 35 min 5 s | | 5 | 2 hours after attempt 4 failed | About 2 h 35 min 5 s | | 6 | 5 hours after attempt 5 failed | About 7 h 35 min 5 s | | 7 | 8 hours after attempt 6 failed | About 15 h 35 min 5 s | | 8 | 8 hours after attempt 7 failed | About 23 h 35 min 5 s | After the eighth attempt the delivery is marked `failed`. It stays in the delivery log, and you can [replay](#delivery-log-and-replay) it. ### Auto-disable [#auto-disable] An endpoint that has failed at least 10 attempts in a row and delivered nothing for 3 days is disabled automatically, with the reason in `disabled_reason`. GridRouter opens a warning alert, "Webhook endpoint disabled", and sends it to every destination. Fix the receiver, re-enable the endpoint (`PUT /v1/webhooks/endpoints/{id}` with `{ "enabled": true }`, which clears its failure count), then replay the failed deliveries. ## Idempotency and ordering [#idempotency-and-ordering] * **Dedupe on `webhook-id`.** A retry or replay carries the same `webhook-id` and body; only the timestamp and signature are new. Record the ids you've processed and skip repeats. * **Once per endpoint.** The same event is created for an endpoint once, even if GridRouter's producer retries. * **No ordering guarantee.** Retries and parallel deliveries can arrive out of order: a `job.completed` can land after a later event. Order by `created_at`, and treat the object's own status in `data` as the truth. ## Payload size [#payload-size] A delivery body is at most 256 KB. A larger event is sent as a stub: `data.truncated` is `true`, nested objects keep only their `id`, and top-level scalar fields are kept. Fetch the full object from the API by its id. ## Delivery log and replay [#delivery-log-and-replay] Every delivery is logged with each attempt's status code, latency, error class (`timeout`, `network`, `redirect`, `blocked_url` or `HTTP `) and the first 500 characters of your response, with secrets redacted. The log also keeps the first 2,000 characters of the signed body. Deliveries are kept for 30 days (the newest 5,000 per workspace). * `GET /v1/webhooks/deliveries?endpoint_id=…&status=failed` lists deliveries, newest first. * `POST /v1/webhooks/deliveries/{id}/replay` sends a delivery again with the same `webhook-id` and a fresh retry schedule. The endpoint must be enabled. * **Send test event** (`POST /v1/webhooks/endpoints/{id}/test` with `{ "event_type": "job.completed" }`, default `alert.triggered`) sends that type's example payload from the [reference](#event-reference), marked `test: true`, right away. It's one attempt, not retried, and the result is returned and logged. ## URL rules [#url-rules] Endpoint URLs are checked when you save them and again before every attempt: * `https` only, on the default port (443). * No IP addresses, `localhost`, single-label or internal hostnames. * No username or password in the URL. * Redirects are never followed; a `3xx` is a failed attempt. ## API and MCP [#api-and-mcp] Every operation is a REST route and an [MCP tool](/docs/mcp) of the same name. Reads need `logs:read`; endpoints hold signing secrets, so changes need `credentials:write`. Reads, with `logs:read`: * `webhooks_event_types`: `GET /v1/webhooks/event-types` * `webhooks_endpoints_list` and `webhooks_endpoints_get`: `GET /v1/webhooks/endpoints` and `GET /v1/webhooks/endpoints/{id}` * `webhooks_deliveries_list` and `webhooks_deliveries_get`: `GET /v1/webhooks/deliveries` and `GET /v1/webhooks/deliveries/{id}` Changes, with `credentials:write`: * `webhooks_endpoints_create`: `POST /v1/webhooks/endpoints` * `webhooks_endpoints_update` and `webhooks_endpoints_delete`: `PUT` and `DELETE /v1/webhooks/endpoints/{id}` * `webhooks_endpoints_rotate_secret`: `POST /v1/webhooks/endpoints/{id}/rotate-secret` * `webhooks_endpoints_test`: `POST /v1/webhooks/endpoints/{id}/test` * `webhooks_deliveries_replay`: `POST /v1/webhooks/deliveries/{id}/replay` A workspace can have up to 10 endpoints. Deleting one deletes its secrets and its delivery log. ## Event reference [#event-reference] Generated from the event schemas. Every example below is validated against its type's schema when the docs are built, and its `data` is what **Send test event** sends for that type. | Event | Group | Summary | | --- | --- | --- | | `call.completed` | Calls | A call finished with a hit or a miss. | | `call.failed` | Calls | A call failed. | | `job.completed` | Jobs and lists | An async job succeeded. | | `job.failed` | Jobs and lists | An async job failed or expired. | | `list.completed` | Jobs and lists | A list finished processing every row. | | `waterfall.run.completed` | Waterfalls | A waterfall run finished. | | `alert.triggered` | Alerts | An alert rule fired. | | `alert.resolved` | Alerts | An alert resolved. | | `vendor_key.failed` | Vendors and billing | A vendor rejected one of your own vendor keys. | | `billing.mismatch_detected` | Vendors and billing | A vendor billed a call against its own published rule. | | `budget.threshold_reached` | Vendors and billing | A budget crossed a threshold. | | `key.created` | Access | An API key was created. | | `key.revoked` | Access | An API key was revoked. | | `member.added` | Access | Someone joined the workspace. | | `member.removed` | Access | Someone left or was removed from the workspace. | ### Calls #### `call.completed` A call finished with a hit or a miss. After every successful call (hit or miss). High volume: subscribe only if you need every call; log drains batch the same data. ```json { "id": "evt_call_completed_01j9x7k2m9q4", "type": "call.completed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "call": { "call_id": "call_01j9x7k2m9q4w8x1c5v3b6", "ts": "2026-10-01T12:00:00.000Z", "capability": "people.email.find", "endpoint_id": "example/email-finder", "provider": "example", "mode": "sync", "outcome": "hit", "http_status": 200, "error_code": null, "total_ms": 412, "cost_micro": 4000, "key_id": "key_2m9q4w8x1c5v", "app_id": null, "run_id": null, "credential": "managed", "cache": "miss", "billing_verdict": "managed" } } } ``` #### `call.failed` A call failed. After every call whose outcome is failed, with the error code and HTTP status. ```json { "id": "evt_call_failed_01j9x7k2m9q4", "type": "call.failed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "call": { "call_id": "call_01j9x7k2m9q4w8x1c5v3b6", "ts": "2026-10-01T12:00:00.000Z", "capability": "people.email.find", "endpoint_id": "example/email-finder", "provider": "example", "mode": "sync", "outcome": "failed", "http_status": 502, "error_code": "upstream_error", "total_ms": 412, "cost_micro": 0, "key_id": "key_2m9q4w8x1c5v", "app_id": null, "run_id": null, "credential": "managed", "cache": "miss", "billing_verdict": "managed" } } } ``` ### Jobs and lists #### `job.completed` An async job succeeded. When a job created with POST /v1/jobs reaches succeeded. ```json { "id": "evt_job_completed_01j9x7k2m9q4", "type": "job.completed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "job": { "object": "job", "id": "job_01j9x7k2m9q4w8x1", "endpoint_id": "example/company-enrich", "mode": "async", "status": "succeeded", "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-01T12:00:00.000Z", "polls": 3 } } } ``` #### `job.failed` An async job failed or expired. When a job reaches failed or expired. ```json { "id": "evt_job_failed_01j9x7k2m9q4", "type": "job.failed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "job": { "object": "job", "id": "job_01j9x7k2m9q4w8x2", "endpoint_id": "example/company-enrich", "mode": "async", "status": "failed", "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-01T12:00:00.000Z", "polls": 5, "error": { "code": "upstream_error", "message": "The vendor returned HTTP 502" } } } } ``` #### `list.completed` A list finished processing every row. When the last row of a list is done, with its totals. ```json { "id": "evt_list_completed_01j9x7k2m9q4", "type": "list.completed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "list": { "object": "list", "id": "list_01j9x7k2m9q4", "status": "completed", "total": 500, "done": 500, "hits": 431, "failed": 3, "cost_micro": 1724000, "created_at": "2026-10-01T12:00:00.000Z" } } } ``` ### Waterfalls #### `waterfall.run.completed` A waterfall run finished. When a waterfall run completes or fails, with the merged record and what it cost. ```json { "id": "evt_waterfall_run_completed_01j9x7k2m9q4", "type": "waterfall.run.completed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "run": { "object": "waterfall_run", "id": "wfr_01j9x7k2m9q4w8x1", "waterfall_id": "work-email", "version": "3", "mode": "sync", "status": "completed", "outcome": "hit", "stop_reason": "first_hit", "fields_filled": [ "email" ], "cost_micro": 8000, "latency_ms": 1840, "batch_id": null, "created_at": "2026-10-01T12:00:00.000Z", "completed_at": "2026-10-01T12:00:00.000Z", "attempts": 2, "data": { "email": "jane@example.com" } } } } ``` ### Alerts #### `alert.triggered` An alert rule fired. When an alert opens (after dedupe, cooldown and mute), for rules that notify this endpoint. ```json { "id": "evt_alert_triggered_01j9x7k2m9q4", "type": "alert.triggered", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "alert": { "object": "alert", "id": "alt_7k2m9q4w8x1c5v3b6n0z", "rule_id": "alr_4f8k2m9q4w8x1c5v", "rule_name": "Error-rate spike", "metric": "error_rate", "severity": "warning", "status": "triggered", "subject": null, "title": "Error-rate spike", "message": "Error rate is 62% over the last 5 minutes (alert at or above 50%).", "value": 0.62, "threshold": 0.5, "count": 1, "started_at": "2026-10-01T12:00:00.000Z", "last_seen_at": "2026-10-01T12:00:00.000Z", "acknowledged_at": null, "acknowledged_by": null, "resolved_at": null, "resolved_reason": null, "muted": false } } } ``` #### `alert.resolved` An alert resolved. When an alert resolves on its own or someone resolves it. ```json { "id": "evt_alert_resolved_01j9x7k2m9q4", "type": "alert.resolved", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "alert": { "object": "alert", "id": "alt_7k2m9q4w8x1c5v3b6n0z", "rule_id": "alr_4f8k2m9q4w8x1c5v", "rule_name": "Error-rate spike", "metric": "error_rate", "severity": "warning", "status": "resolved", "subject": null, "title": "Error-rate spike", "message": "Error rate is 62% over the last 5 minutes (alert at or above 50%).", "value": 0.62, "threshold": 0.5, "count": 1, "started_at": "2026-10-01T12:00:00.000Z", "last_seen_at": "2026-10-01T12:00:00.000Z", "acknowledged_at": null, "acknowledged_by": null, "resolved_at": "2026-10-01T12:00:00.000Z", "resolved_reason": "auto", "muted": false } } } ``` ### Vendors and billing #### `vendor_key.failed` A vendor rejected one of your own vendor keys. When a call made with your vendor key gets HTTP 401 or 403 from the vendor. At most once per vendor per 10 minutes. ```json { "id": "evt_vendor_key_failed_01j9x7k2m9q4", "type": "vendor_key.failed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "provider": "example", "capability": "people.email.find", "endpoint_id": "example/email-finder", "call_id": "call_01j9x7k2m9q4w8x1c5v3b7", "upstream_status": 401, "key_id": "key_2m9q4w8x1c5v" } } ``` #### `billing.mismatch_detected` A vendor billed a call against its own published rule. When vendor billing verification finds a charge for a miss, a double-charged retry or a price mismatch on a call made with your key. ```json { "id": "evt_billing_mismatch_detected_01j9x7k2m9q4", "type": "billing.mismatch_detected", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "call_id": "call_01j9x7k2m9q4w8x1c5v3b8", "provider": "example", "endpoint_id": "example/email-finder", "verdict": "charged_for_miss", "expected_credits": 0, "reported_credits": 1 } } ``` #### `budget.threshold_reached` A budget crossed a threshold. When a workspace or key budget reaches a budget alert rule's threshold (80% and 100% by default). ```json { "id": "evt_budget_threshold_reached_01j9x7k2m9q4", "type": "budget.threshold_reached", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "scope": "key", "scope_id": "key_2m9q4w8x1c5v", "period": "month", "limit_micro": 50000000, "spent_micro": 40250000, "percent": 80.5, "threshold_percent": 80 } } ``` ### Access #### `key.created` An API key was created. When anyone in the workspace creates an API key. The secret is never included. ```json { "id": "evt_key_created_01j9x7k2m9q4", "type": "key.created", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "key": { "object": "api_key", "id": "key_2m9q4w8x1c5v", "name": "Production", "prefix": "grid_live_2m9q", "scopes": [ "call", "logs:read" ], "status": "active", "created_at": "2026-10-01T12:00:00.000Z" }, "actor": "user:usr_2m9q4w8x" } } ``` #### `key.revoked` An API key was revoked. When a key is revoked from the dashboard, the API or automatically (refresh-token reuse). ```json { "id": "evt_key_revoked_01j9x7k2m9q4", "type": "key.revoked", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "key": { "object": "api_key", "id": "key_2m9q4w8x1c5v", "name": "Production", "prefix": "grid_live_2m9q", "scopes": [ "call", "logs:read" ], "status": "revoked", "created_at": "2026-10-01T12:00:00.000Z" }, "actor": "user:usr_2m9q4w8x" } } ``` #### `member.added` Someone joined the workspace. When an invitation is accepted or a member is added. ```json { "id": "evt_member_added_01j9x7k2m9q4", "type": "member.added", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "member": { "user_id": "usr_4w8x1c5v", "email": "sam@example.com", "role": "developer" }, "actor": "user:usr_2m9q4w8x" } } ``` #### `member.removed` Someone left or was removed from the workspace. When a member leaves or is removed. ```json { "id": "evt_member_removed_01j9x7k2m9q4", "type": "member.removed", "api_version": "2026-10-01", "created_at": "2026-10-01T12:00:00.000Z", "data": { "member": { "user_id": "usr_4w8x1c5v", "email": "sam@example.com", "role": "developer" }, "actor": "user:usr_2m9q4w8x" } } ``` # Discovery documents (/docs/discovery) Agents and tools find the API, the MCP server and our skills from these documents. All of them are public, CORS-open (`Access-Control-Allow-Origin: *`) and cached for an hour. They are generated from one set of origins, so the three hosts always agree. ## Site [#site] | Document | URL | Media type | Purpose | | --- | --- | --- | --- | | llms.txt | `https://gridrouter.io/llms.txt` | `text/plain; charset=utf-8` | Index of the site, API, MCP server and catalog for language models. | | llms-full.txt | `https://gridrouter.io/llms-full.txt` | `text/plain; charset=utf-8` | Every guide, capability and provider inline, plus the customer integration skill. | | API catalog (site) | `https://gridrouter.io/.well-known/api-catalog` | `application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"` | RFC 9727 linkset pointing at the OpenAPI descriptions, docs and MCP server. | | AI Catalog (site) | `https://gridrouter.io/.well-known/ai-catalog.json` | `application/ai-catalog+json` | Points agents at the MCP Server Card. | | Agent Skills index | `https://gridrouter.io/.well-known/agent-skills/index.json` | `application/json` | Agent Skills discovery v0.2.0: downloadable SKILL.md files with sha256 digests. | | Agent Skills index (v0.1.0) | `https://gridrouter.io/.well-known/skills/index.json` | `application/json` | Legacy Agent Skills discovery path for older clients. | | security.txt (site) | `https://gridrouter.io/.well-known/security.txt` | `text/plain; charset=utf-8` | RFC 9116 vulnerability disclosure contact and policy. | ## API [#api] | Document | URL | Media type | Purpose | | --- | --- | --- | --- | | OpenAPI 3.1 | `https://api.gridrouter.io/openapi.json` | `application/vnd.oai.openapi+json;version=3.1` | The full API description. | | OpenAPI 3.0 | `https://api.gridrouter.io/openapi-3.0.json` | `application/json` | The same description down-converted for tools that only read 3.0. | | API llms.txt | `https://api.gridrouter.io/llms.txt` | `text/plain; charset=utf-8` | The API's own endpoint index for language models. | | API catalog (api) | `https://api.gridrouter.io/.well-known/api-catalog` | `application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"` | RFC 9727 linkset served by the API host. | | security.txt (api) | `https://api.gridrouter.io/.well-known/security.txt` | `text/plain; charset=utf-8` | RFC 9116 disclosure contact on the API host. | ## MCP server [#mcp-server] | Document | URL | Media type | Purpose | | --- | --- | --- | --- | | MCP Server Card | `https://mcp.gridrouter.io/mcp/server-card` | `application/mcp-server-card+json` | Name, transport, auth header and protocol versions of the MCP server. | | OAuth protected resource metadata | `https://mcp.gridrouter.io/.well-known/oauth-protected-resource/mcp` | `application/json` | RFC 9728 metadata naming the authorization server for the MCP endpoint. | | OAuth authorization server metadata | `https://mcp.gridrouter.io/.well-known/oauth-authorization-server` | `application/json` | RFC 8414 endpoints for the MCP OAuth 2.1 flow. | | AI Catalog (mcp) | `https://mcp.gridrouter.io/.well-known/ai-catalog.json` | `application/ai-catalog+json` | Points agents at the MCP Server Card from the MCP host. | | security.txt (mcp) | `https://mcp.gridrouter.io/.well-known/security.txt` | `text/plain; charset=utf-8` | RFC 9116 disclosure contact on the MCP host. | ## Why there is no agent.json [#why-there-is-no-agentjson] `/.well-known/agent.json` is an A2A Agent Card. It describes an autonomous agent that other agents delegate tasks to over the A2A protocol. GridRouter is not an A2A agent: it is an API and an MCP server that your agents call as tools. The MCP Server Card describes exactly that (transport, auth header and protocol versions), and the AI Catalog points to it, so those are the documents we publish instead. # Errors (/docs/errors) Every error, from every route and MCP tool, has the same shape: ```json { "error": { "code": "vendor_key_required", "message": "Add your Hunter key in Settings → Vendor keys. GridRouter runs Hunter on your own key.", "request_id": "req_…", "call_id": "call_…", "details": { "provider": "hunter" } } } ``` | Field | Meaning | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `code` | Stable and machine-readable. Branch on this, never on `message` | | `message` | Human-readable; may change | | `request_id` | Quote it to support | | `call_id` | Present when a call was created; it is in your [logs](/docs/concepts/logs-and-drains) | | `retry_after_ms` | When to retry; `429` responses also send `Retry-After` | | `details` | Code-specific context: `issues` with field paths on validation errors, `layer` on rate limits, the partial `run` on waterfall stops | A provider that answered but found nothing is **not** an error: the call succeeds with `hit: false`. ## Codes [#codes] | Status | Code | Meaning | | --- | --- | --- | | 400 | `invalid_meta` | `meta` must be up to 16 string values (500 chars) under `[A-Za-z0-9_.-]{1,40}` keys. | | 400 | `invalid_request` | The body, query or a header failed validation. | | 401 | `unauthorized` | No API key, or the key is unknown, revoked or expired. | | 402 | `insufficient_balance` | The wallet cannot hold the call's maximum cost. | | 402 | `max_cost_exceeded` | The quoted price is above `max_cost_micro` (or `X-Grid-Max-Cost`). | | 403 | `account_frozen` | The organization is on a dispute or fraud hold. | | 403 | `budget_blocked` | A key, app or workspace budget is spent for the period. | | 403 | `plan_limit_reached` | A plan limit (keys, workspaces, drains, retention) is reached. | | 403 | `scope_denied` | The key lacks the scope this route needs, or the IP is not on its allowlist. | | 403 | `vendor_key_required` | The vendor runs on your own key and none is stored; add it in Settings → Vendor keys. | | 404 | `not_found` | No such endpoint, capability or resource in this workspace. | | 409 | `cancelled` | The run was cancelled by the caller. | | 409 | `conflict` | The request conflicts with the resource's current state. | | 422 | `idempotency_mismatch` | An `Idempotency-Key` was reused with a different body. | | 422 | `strict_filters` | Strict provider filters (`only`, `ignore`, no fallbacks, max price) left no endpoint. | | 422 | `validation_failed` | A definition or input failed validation; `details.issues` has field paths. | | 429 | `rate_limited` | A rate limit was hit; wait `retry_after_ms` or the `Retry-After` seconds. | | 500 | `internal_error` | Something failed on our side; the `request_id` identifies it. | | 502 | `response_buffer_limit` | The vendor's response was larger than the gateway buffers. | | 502 | `upstream_error` | The vendor returned an error; `details.upstream_status` has its status. | | 503 | `grid_saturated` | The gateway is shedding load; retry after the hint. | | 503 | `provider_capacity_unavailable` | The vendor's concurrency or rate budget is exhausted right now. | | 504 | `deadline_exceeded` | A waterfall hit its total deadline; the partial result is in `details`. | | 504 | `upstream_timeout` | The vendor did not answer within the timeout. | ## Retrying [#retrying] * **Retry with backoff:** `429` (after `retry_after_ms`), `503` and `502`/`504` from a provider. A routed `/v1/run` has already tried the other providers before returning one of these. * **Fix the request:** `400`, `404`, `409`, `422`. * **Fix the account or key:** `401`, `402`, `403`. Retrying cannot help. Failed calls are never charged. ## Idempotency [#idempotency] Send `Idempotency-Key` on any `POST` that runs something: 8 to 128 characters of letters, digits and `_ . : -`. * The same key with the same body returns the stored first response, free. * The same key with a different body is `422 idempotency_mismatch`. * The same key while the first request is still running is `409`. * Streaming responses and 5xx errors are not stored, so the key is released and you can retry. # Create an API key (/docs/getting-started/api-keys) Open Settings → **API keys** (`/settings/keys`) and choose **Create key**. The secret is shown once; store it in your secret manager as `GRID_API_KEY`. ```text grid_live_<12-character lookup>_<32-character secret><6-character checksum> ``` The checksum lets secret scanners and the gateway reject a mistyped key without a lookup. `grid_test_` keys reach sandbox providers only, and `grid_agent_` keys belong to an agent with its own budget. ## Scopes [#scopes] A key can only do what its scopes allow. The dashboard offers three presets: | Preset | Scopes | | --------------------- | ---------------------------------------------------------------------- | | Backend app (default) | `call`, `run`, `jobs`, `pipelines:run`, `catalog:read`, `balance:read` | | Read only | `catalog:read`, `balance:read`, `logs:read`, `pipelines:read` | | Agent / MCP | the backend scopes plus `lists`, `logs:read`, `pipelines:read` | A key never grants scopes its creator does not hold. `*` (full access, including future scopes) is for owners only. ## Limits on a key [#limits-on-a-key] * **Expiry**: never, or a date after which the key stops working. * **IP allowlist**: up to 50 IPv4 or IPv6 addresses and CIDR ranges, matched against the connecting IP. A request from anywhere else fails with `403 scope_denied`. * **Credit limit**: a cap on what the key spends on charged calls, reset daily, weekly, monthly or never (`403 budget_blocked` once reached). Calls on your own vendor keys cost `0` and never count against it. * **Label**: `primary`, `backup`, `ci`. Keep a backup key so rotating or revoking one never causes downtime. **Rotate** mints a replacement with the same scopes and limits; the old key keeps working for a grace period (24 hours by default, 7 days at most). **Revoke** stops billable calls immediately. The same operations are in the API: [create](/docs/api/access/keys_create), [rotate](/docs/api/access/keys_rotate), [set a credit limit](/docs/api/access/keys_limit_set) and [revoke](/docs/api/access/keys_revoke). # Connect an MCP client (/docs/getting-started/connect-mcp) The GridRouter MCP server is at: ```text https://mcp.gridrouter.io/mcp ``` GridRouter implements MCP 2026-07-28 stateless Streamable HTTP. Earlier clients that require the `initialize` handshake cannot connect. Add the URL to a client that supports this protocol revision; the exact configuration format depends on the client: ```json title="Example client configuration" { "mcpServers": { "gridrouter": { "url": "https://mcp.gridrouter.io/mcp" } } } ``` ## Sign in with OAuth [#sign-in-with-oauth] Clients that support MCP authorization send you to GridRouter on first use. Sign in and approve, and the client is granted access to your active workspace. The grant can never exceed your role: developers cannot grant key or agent management, and billing and viewer members grant read scopes only. Each grant appears as a key named `mcp: ` in Settings → **API keys**, where you can revoke it. Access tokens last an hour and refresh for 30 days. A reused refresh token revokes the grant. ## Headless clients: use an API key [#headless-clients-use-an-api-key] Scripts, CI and clients without OAuth send a GridRouter [API key](/docs/getting-started/api-keys) instead. The **Agent / MCP** key preset has the scopes most agents need. ```json title="Example client configuration" { "mcpServers": { "gridrouter": { "url": "https://mcp.gridrouter.io/mcp", "headers": { "Authorization": "Bearer ${GRID_API_KEY}" } } } } ``` ## Try it [#try-it] Ask the client to find a work email. It should call `catalog_search` to find an endpoint, then `run` with `people.email.find`. The built-in `find_verified_email` prompt does exactly that and verifies the result. The [MCP reference](/docs/mcp) lists every tool, its REST equivalent and the scope it needs. ## TypeScript client [#typescript-client] For a native TypeScript client, install the MCP SDK and a TypeScript runner: ```sh npm install @modelcontextprotocol/client@2.2.0 tsx ``` Set `GRID_API_KEY` in your environment, then save and run this as `connect.mts`: ```ts title="connect.mts" import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client"; const apiKeyFromEnv = process.env.GRID_API_KEY; if (!apiKeyFromEnv) throw new Error("Set GRID_API_KEY in the environment."); const client = new Client( { name: "gridrouter-example", version: "1.0.0" }, { versionNegotiation: { mode: "auto" } }, ); const transport = new StreamableHTTPClientTransport(new URL("https://mcp.gridrouter.io/mcp"), { authProvider: { token: async () => apiKeyFromEnv }, }); try { await client.connect(transport); const { tools } = await client.listTools(); console.log(tools.map(({ name }) => name)); } finally { await client.close(); } ``` Run the example with: ```sh npx tsx connect.mts ``` The client negotiates the modern protocol before listing tools. This example only discovers tools; it does not call a vendor. # Make a first call (/docs/getting-started/first-call) The base URL is `https://api.gridrouter.io`. Send your key as a bearer token and a JSON body whose `input` matches the endpoint's input schema. Money is always integer **micro-USD** (1,000,000 = $1). ## Call one endpoint [#call-one-endpoint] `POST /v1/call/{provider}/{endpoint}` runs exactly the endpoint you name. This one is Hunter's email finder, so add a Hunter key first. ```bash curl https://api.gridrouter.io/v1/call/hunter/email.find \ -H "Authorization: Bearer $GRID_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: lead-8841" \ -d '{"input": {"first_name": "Ada", "last_name": "Lovelace", "domain": "example.com"}}' ``` ```ts const res = await fetch("https://api.gridrouter.io/v1/call/hunter/email.find", { method: "POST", headers: { Authorization: `Bearer ${process.env.GRID_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": "lead-8841", }, body: JSON.stringify({ input: { first_name: "Ada", last_name: "Lovelace", domain: "example.com" }, }), }); const call = await res.json(); if (!res.ok) throw new Error(`${call.error.code}: ${call.error.message}`); console.log(call.hit, call.data.email); ``` ```python import os import requests res = requests.post( "https://api.gridrouter.io/v1/call/hunter/email.find", headers={ "Authorization": f"Bearer {os.environ['GRID_API_KEY']}", "Idempotency-Key": "lead-8841", }, json={"input": {"first_name": "Ada", "last_name": "Lovelace", "domain": "example.com"}}, timeout=60, ) call = res.json() if not res.ok: raise RuntimeError(f"{call['error']['code']}: {call['error']['message']}") print(call["hit"], call["data"].get("email")) ``` The response is a call object: ```json { "object": "call", "id": "call_…", "endpoint_id": "hunter/email.find", "provider": "hunter", "status": "succeeded", "hit": true, "cost_micro": 0, "latency_ms": 640, "credential": "byok", "data": { "email": "ada@example.com", "confidence": 94 }, "attempts": [ { "endpoint_id": "hunter/email.find", "provider": "hunter", "outcome": "hit", "cost_micro": 0, "latency_ms": 640 } ] } ``` * `status` is whether the provider answered; `hit` is whether it found what the capability promises (here an email). A miss is a successful call with `hit: false`, not an error. * `data` holds the endpoint's normalized output fields. Add `"include_raw": true` for the provider's own response in `raw`. * `cost_micro` is what GridRouter charged: always `0` on your own key. * The same `Idempotency-Key` with the same body replays the first answer; with a different body it is `422 idempotency_mismatch`. ## Let GridRouter pick the provider [#let-gridrouter-pick-the-provider] `POST /v1/run/{capability}` takes the capability instead of one endpoint and tries the providers you have connected until one hits. Every try is listed in `attempts`. ```bash curl https://api.gridrouter.io/v1/run/people.email.find \ -H "Authorization: Bearer $GRID_API_KEY" \ -H "Content-Type: application/json" \ -H "X-Grid-Max-Cost: 0.05" \ -d '{ "input": {"first_name": "Ada", "last_name": "Lovelace", "domain": "example.com"}, "provider": {"order": ["prospeo", "hunter"]} }' ``` `X-Grid-Max-Cost` is in **USD** (`0.05` is 50,000 micro-USD); in the body the same cap is `max_cost_micro`. See [routing](/docs/concepts/routing) for `order`, `only`, `ignore`, `sort` and fallbacks. ## Find endpoints [#find-endpoints] The catalog is public: `GET /v1/catalog/endpoints?q=email` searches it and `GET /v1/catalog/endpoints/{provider}/{endpoint}` returns one endpoint's input JSON Schema, price and quality. `POST /v1/quote/{provider}/{endpoint}` prices a call without making it. # Quickstart (/docs/getting-started) ### Create a workspace [#create-a-workspace] [Sign up](/docs/getting-started/sign-up) with your work email. You land in a workspace on the Free plan. ### Add a vendor key [#add-a-vendor-key] [Paste the API key](/docs/getting-started/vendor-keys) you already have for a provider such as Hunter or Prospeo. GridRouter encrypts it in your workspace vault and calls the provider with it. ### Create a GridRouter API key [#create-a-gridrouter-api-key] [One `grid_live_…` key](/docs/getting-started/api-keys) reaches every provider you have connected. ### Make a first call [#make-a-first-call] [`POST /v1/call/hunter/email.find`](/docs/getting-started/first-call) with curl, TypeScript or Python. ### Connect an MCP client [#connect-an-mcp-client] [Connect an MCP 2026-07-28 client](/docs/getting-started/connect-mcp) at `https://mcp.gridrouter.io/mcp`. # Create a workspace (/docs/getting-started/sign-up) 1. Open [gridrouter.io/sign-up](https://gridrouter.io/sign-up) and enter your name, work email and a password: 12 to 128 characters, with at least one letter and one number, and not containing the part of your email before the `@`. 2. Open the verification link we email you. It is valid for 24 hours and signs you in. 3. You land in a personal workspace. Its owner is you, and it is on the Free plan. Every workspace is on **Free** at launch, and calls run on your own vendor keys. See [plans](/docs/concepts/plans) for what Free includes. ## Invite your team [#invite-your-team] Settings → **Members** invites people by email. An invitation is valid for 7 days and the invitee verifies their email before joining. Each member has one role: | Scope | Owner | Admin | Developer | Billing | Viewer | | --- | --- | --- | --- | --- | --- | | `catalog:read` | Yes | Yes | Yes | Yes | Yes | | `balance:read` | Yes | Yes | Yes | Yes | Yes | | `logs:read` | Yes | Yes | Yes | Yes | Yes | | `billing:write` | Yes | Yes | | Yes | | | `keys:write` | Yes | Yes | Yes | | | | `agents:write` | Yes | Yes | | | | | `credentials:write` | Yes | Yes | Yes | | | | `presets:write` | Yes | Yes | Yes | | | | `pipelines:read` | Yes | Yes | Yes | Yes | Yes | | `pipelines:write` | Yes | Yes | Yes | | | | `cache:write` | Yes | Yes | Yes | | | Roles decide what a person can do in the dashboard. Dashboard sessions never make billable calls themselves; they create the [API keys](/docs/getting-started/api-keys) that do. # Add a vendor key (/docs/getting-started/vendor-keys) GridRouter calls each provider with **your** account on that provider. At launch there are no managed vendor accounts, so a provider you have not connected returns `403 vendor_key_required`, naming the provider to add. ## Add a key [#add-a-key] 1. Open Settings → **Vendor keys** (`/settings/vendors`). 2. Pick the provider and paste its API key. The dialog says where the key lives in the provider's own dashboard (for Hunter: account menu → API). 3. Optionally choose **Test connection** first. Where the provider has a free, read-only endpoint (usually its credit balance), GridRouter calls it with the key without storing anything. 4. **Save**. The stored key is tested once more and its status shows in the list. Each provider has a **primary** and an optional **fallback** key. A call uses the primary; when the primary's rate limit or circuit breaker refuses, it moves to the fallback. **Swap** makes the fallback the primary. ## What GridRouter stores [#what-gridrouter-stores] * The secret, sealed with AES-256-GCM under a data key that only your workspace's vault can unwrap. It is write-only: no API, dashboard page or log ever returns it. * A label, the last four characters, the last test result and when the key was last used. Calls on your key are never charged by GridRouter (`cost_micro` is `0`). Your provider bills you as usual, and the log shows whether it billed each call by its own rules: see [billing verification](/docs/concepts/billing-verification). ## From the API [#from-the-api] Vendor keys are managed with the `credentials:write` scope: [add](/docs/api/access/credentials_put), [test before saving](/docs/api/access/credentials_verify), [test a stored key](/docs/api/access/credentials_test), [swap](/docs/api/access/credentials_swap) and [remove](/docs/api/access/credentials_remove). # GridRouter docs (/docs) GridRouter puts email finders, enrichment, phone, signals and the rest of the go-to-market data stack behind one REST API, one API key and one MCP server. Every provider endpoint is described in the same catalog: the same input shape, the same normalized output fields, a price and a quality score measured on real calls. Every workspace is on the Free plan. Calls run on the vendor keys you add (BYOK), GridRouter never charges for them, and nothing is sold yet. Paid plans and managed vendor accounts are coming soon. ## Start here [#start-here] ## How it fits together [#how-it-fits-together] * **[Capabilities and endpoints](/docs/concepts/capabilities-and-endpoints).** An endpoint is one provider's API call (`hunter/email.find`). A capability is the task it performs (`people.email.find`), shared by every provider that can do it. * **[`/v1/call` and `/v1/run`](/docs/concepts/routing).** `call` runs exactly the endpoint you name. `run` takes a capability and tries providers in order until one finds the answer. * **[Waterfalls](/docs/concepts/waterfalls)** save a provider order, stop rules and a per-field merge as your own endpoint. * **[Execution options](/docs/concepts/execution-options)** control timeouts, cost caps, cache and logging per request, key, preset or workspace. * **[Logs](/docs/concepts/logs-and-drains)** record every call, stream live and say whether the provider [billed it correctly](/docs/concepts/billing-verification). ## For agents [#for-agents] Every page is also Markdown: add `.md` to its URL, or send `Accept: text/markdown`. The index is at [`/llms.txt`](/llms.txt) and every written page in one file at [`/llms-full.txt`](/llms-full.txt). The OpenAPI document is at `https://api.gridrouter.io/openapi.json`. # MCP server (/docs/mcp) `https://mcp.gridrouter.io/mcp` serves the same operations as the REST API. Each tool is one operation: the same input schema, the same result, the same errors. Tools a connection's scopes do not cover are not listed; public tools such as `catalog_search` are always listed. Every tool result includes the call's cost in `_meta["io.relaygrid/cost_micro"]`. A failed call returns `isError: true` with `code: message` text and the [error body](/docs/errors) as structured content. ## Resources [#resources] | URI | What | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grid://catalog/endpoints/{provider}/{endpoint}` | One endpoint's definition, pricing and quality | | `grid://catalog/capabilities` | Every capability and the endpoints that serve it | | `logs://live` | The newest calls, waterfall steps, jobs, lists and alerts; subscribable. Filter with a query: `logs://live?capability=people.email.find&status=error` (`logs:read`) | | `grid://jobs/{id}` | Status and result of a job (`jobs`) | | `grid://lists/{id}` | Progress of a list run (`lists`) | Tools that start a job or list return a `resource_link` to its `grid://` URI. ## Prompts [#prompts] * `find_verified_email` (`first_name`, `last_name`, `domain`): runs `people.email.find`, then `email.verify` on the result, and reports the total cost. * `research_account` (`domain`, `budget_usd`, default `0.50`): quotes each call and keeps the research under budget. ## Waterfall templates [#waterfall-templates] An agent can go from a goal to a running waterfall with four tools: 1. `waterfall_templates` (public) lists the templates with `availability.status`, the vendor keys that unlock each one and its cost range. `waterfall_template_get` shows one template's inputs, outputs and step-by-step explanations. 2. `waterfall_estimate` with `{"template":"work-email"}` prices it without calling a provider. 3. `waterfall_create_from_template` copies it into the workspace and publishes it (`pipelines:write`), with optional `pins`, `speed` and `max_cost_micro`. 4. `waterfall_run` with `{"id":"wf_…","input":{…}}` returns the golden record. With `"async": true`, it returns a run id to poll with `waterfall_status`. See [waterfall templates](/docs/concepts/waterfall-templates). The public [gridrouter-waterfalls skill](/.well-known/agent-skills/gridrouter-waterfalls/SKILL.md) walks an agent through it. ## Tools [#tools] The same list is available as JSON from `GET https://api.gridrouter.io/v1/tools?format=mcp` (or `openai` / `anthropic` for function-calling schemas). | Tool, REST route and scope | Description | | --- | --- | | `catalog_search` `GET /v1/catalog/endpoints` public | Find vendor endpoints by keyword (capability, vendor, what they return). Returns price and quality. | | `catalog_get` `GET /v1/catalog/endpoints/{provider}/{endpoint}` public | Full definition of one endpoint: input JSON Schema, pricing model and quality. | | `vendor_search` `GET /v1/catalog/vendors` public | Every GTM data vendor GridRouter knows about (integrated or researched): API access, spec status, published rate limits and marketplace listings. | | `vendor_get` `GET /v1/catalog/vendors/{slug}` public | One vendor's sourced record: company, API surface, docs, pricing, data, compliance, relationships and marketplace listings, each with sources and confidence. | | `vendor_openapi` `GET /v1/catalog/vendors/{slug}/openapi` public | The stored OpenAPI document for a vendor: the vendor's official spec, or one GridRouter reconstructed from its docs (x-reconstructed, x-confidence, x-source-url on every operation). | | `vendor_rate_limits` `GET /v1/catalog/vendors/{slug}/rate-limits` public | Published rate limits (per window, concurrency, headers, 429 behaviour) with source and check date, and the pacing GridRouter derives from them. | | `capabilities_list` `GET /v1/catalog/capabilities` public | Capabilities (normalized tasks like people.email.find) and the endpoints that serve each. | | `categories_list` `GET /v1/catalog/categories` public | Top-level GTM data categories. | | `leaderboard_get` `GET /v1/catalog/leaderboards/{capability}` public | Endpoints for a capability ranked by usage-derived quality (Wilson lower bound). | | `quote` `POST /v1/quote/{provider}/{endpoint}` `call` | Worst-case cost of calling an endpoint with this input, without calling it. | | `call` `POST /v1/call/{provider}/{endpoint}` `call` | Call one vendor endpoint. Reserves the worst-case cost, charges the actual cost. Async vendors return a job. Runs as an MCP task. | | `run_auto` `POST /v1/run/auto` `run` | Auto router: GridRouter picks the capability from the input fields you have (and the output fields you ask for), then routes it like run. The chosen capability and the alternatives are returned. | | `run` `POST /v1/run/{capability}` `run` | Routed call: GridRouter picks vendors (waterfall/cheapest/best) until one hits. Only hits are charged on per-success vendors. | | `call_get` `GET /v1/calls/{id}` `call` | Cost, timings (total, upstream, overhead, TTFB, queue), provider, outcome and every routed attempt of one call, like OpenRouter's generation lookup. Keys without logs:read only see calls they made. Available a few seconds after the call. | | `presets_list` `GET /v1/presets` `catalog:read` | Saved routing presets for this org: provider preferences, field selection, max cost and stop rule. Use one as preset: "@slug" on run. | | `presets_get` `GET /v1/presets/{slug}` `catalog:read` | One saved routing preset. | | `presets_create` `POST /v1/presets` `presets:write` | Create or replace a routing preset shared within the org (order/only/ignore/sort/max price/data policy, credential, fields, max cost, stop rule). | | `presets_delete` `DELETE /v1/presets/{slug}` `presets:write` | Delete a preset. Requests that name it fail with not_found afterwards. | | `job_create` `POST /v1/jobs` `jobs` | Run any endpoint in the background through the job queue, with per-vendor pacing. Runs as an MCP task. | | `job_get` `GET /v1/jobs/{id}` `jobs` | Status and result of a queued or async job. | | `list_create` `POST /v1/lists` `lists` | Run an endpoint or capability over up to 10,000 rows in the background. Runs as an MCP task. | | `list_get` `GET /v1/lists/{id}` `lists` | Progress and cost of a list run. | | `list_rows` `GET /v1/lists/{id}/rows` `lists` | One page of per-row results for a list. | | `balance_get` `GET /v1/balance` `balance:read` | Prepaid balance, amount held for in-flight calls, and what is available. | | `budget_set` `PUT /v1/budgets` `keys:write` | Cap spend for the org, one key, or one agent per day, month or total. | | `budgets_list` `GET /v1/budgets` `balance:read` | Every spend cap (workspace, key, agent) with its period and what it used in the current window. | | `budget_remove` `DELETE /v1/budgets` `keys:write` | Remove the spend cap for the org, one key, or one agent. | | `keys_list` `GET /v1/keys` `keys:write` | API keys for this org (never the secret). | | `keys_create` `POST /v1/keys` `keys:write` | Mint a scoped key. The secret is returned once. | | `keys_revoke` `DELETE /v1/keys/{id}` `keys:write` | Revoke a key. Billable calls stop immediately. | | `recovery_codes_create` `POST /v1/recovery-codes` `keys:write` | Owner only (a * key): issue 10 one-time recovery codes that can mint a new owner key if every key is lost. Replaces earlier codes; shown once. | | `keys_rotate` `POST /v1/keys/{id}/rotate` `keys:write` | Mint a replacement key with the same scopes and limits; the old key keeps working for grace_seconds (default 24 h), then expires. | | `keys_limit_set` `PUT /v1/keys/{id}/limit` `keys:write` | Cap what one key can spend, resetting daily, weekly, monthly or never. null removes the cap. Calls over the cap fail with budget_blocked. | | `agents_create` `POST /v1/agents` `agents:write` | Create an agent with its own budget and mint an agent key for it. | | `log_views_list` `GET /v1/logs/views` `logs:read` | Your saved log views plus views shared with the workspace, newest first. A view is a query in the log query language and the visible columns. | | `log_views_create` `POST /v1/logs/views` `logs:read` | Save the query and visible columns under a name. `shared: true` (owners and admins only) makes it visible to the whole workspace; `replace: true` overwrites your view with the same name. | | `log_views_update` `PUT /v1/logs/views/{id}` `logs:read` | Rename a view or change its query, columns or sharing. You can change your own views; owners and admins can also change shared ones. | | `log_views_delete` `DELETE /v1/logs/views/{id}` `logs:read` | Delete one of your views (owners and admins can also delete shared views). | | `log_views_import` `POST /v1/logs/views/import` `logs:read` | One-time move of views and pins the dashboard kept in the browser. Views whose names you already use and calls already pinned are skipped. | | `log_pins_list` `GET /v1/logs/pins` `logs:read` | Calls you pinned to the top of the log viewer, newest pin first, each with its current log row (null once the call is past log retention). | | `log_pins_create` `POST /v1/logs/pins` `logs:read` | Pin a call to the top of the log viewer. You keep up to 20 pins; the oldest drops off. | | `log_pins_delete` `DELETE /v1/logs/pins/{call_id}` `logs:read` | Remove a pinned call. | | `logs_list` `GET /v1/logs` `logs:read` | Every call and routed attempt for this org, newest first (360-day retention). Filter by time, outcome, status, provider, capability, endpoint, key, agent, client, mode, credential, error code, latency and cost; cursor-paginated. | | `logs_facets` `GET /v1/logs/facets` `logs:read` | Counts per value (outcome, status, provider, capability, endpoint, key, client…) and latency/cost ranges for the same filters as logs_list. | | `logs_stats` `GET /v1/logs/stats` `logs:read` | Calls, error rate, p50/p95/p99 latency, spend, a hit/miss/failed timeline and spend by provider over time, for the same filters as logs_list. | | `logs_billing` `GET /v1/logs/billing` `logs:read` | Per vendor, how many of your own-key (BYOK) calls were billed as the vendor's published rule says, how many were charged for a miss, double-charged on a retry or at the wrong price, and the credits and dollars at stake. Same filters as logs_list. | | `logs_get` `GET /v1/logs/{id}` `logs:read` | One call with timings, its redacted request/response body (audit-logged), the other attempts in its routed run or list, and its ledger entries. | | `settings_get` `GET /v1/settings` `logs:read` | Org data settings, such as whether request/response bodies are stored. | | `settings_update` `PUT /v1/settings` `keys:write` | Turn body storage on or off (off stops new bodies from being kept) and set how many days of call log members and keys can read (30, 90, 180 or 360). | | `credentials_list` `GET /v1/credentials` `credentials:write` | Your own vendor keys (BYOK) stored for this org: provider, slot, label, field names, the key's last four characters and its last test result. Secrets are write-only and never returned. | | `credentials_put` `PUT /v1/credentials/{provider}` `credentials:write` | Store your own key for a provider as the primary or fallback slot, envelope-encrypted. BYOK calls are never charged by GridRouter. | | `credentials_remove` `DELETE /v1/credentials/{provider}` `credentials:write` | Delete one slot of your own key for a provider. Calls fall back to the next slot. | | `credentials_test` `POST /v1/credentials/{provider}/test` `credentials:write` | Call the provider's free, read-only test endpoint (for example a credit balance) with your stored key. Never charged; the call is logged. | | `credentials_verify` `POST /v1/credentials/{provider}/verify` `credentials:write` | Call the provider's free, read-only test endpoint with a key that is not stored yet. Nothing is saved; the key is used for this one call. Never charged; the call is logged. | | `credentials_update` `PUT /v1/credentials/{provider}/label` `credentials:write` | Set or clear the label of a stored key. The secret is not touched. | | `credentials_swap` `POST /v1/credentials/{provider}/swap` `credentials:write` | Make the fallback key the primary and the primary the fallback for one provider. Takes effect on the next call. | | `apps_list` `GET /v1/apps` `logs:read` | Apps attributed on your calls (X-Grid-App, or HTTP-Referer + X-Title like OpenRouter) with 30-day usage, plus how each is listed. | | `apps_put` `PUT /v1/apps/{id}` `keys:write` | Name an attributed app and opt it in (or out) of the public rankings and showcase. A domain-style id must match its URL; another org's public id is refused. | | `auth_code_create` `POST /v1/auth/codes` `keys:write` | Consent step of Sign in with GridRouter (OAuth PKCE, S256): a signed-in member approves an app and gets a one-time code (10 minutes) to redirect back with. | | `auth_keys_exchange` `POST /v1/auth/keys` public | Final step of Sign in with GridRouter: exchange the one-time code and its PKCE code_verifier for a user-controlled key with call/run scopes and any credit limit the user set. | | `rankings_get` `GET /v1/rankings` public | Top capabilities, providers, categories and opted-in apps by calls and hits over the last day, week or month across all GridRouter traffic, with change vs the previous window and trending movers. | | `apps_directory` `GET /v1/catalog/apps` public | Public apps built on GridRouter (owners opted in), ranked by calls with their top capabilities and providers. | | `app_profile_get` `GET /v1/catalog/apps/{id}` public | One public app: 30-day usage by day, top capabilities and providers. | | `activity_get` `GET /v1/catalog/activity` public | Per-endpoint uptime (share of calls without a vendor-side failure), p50/p95 latency and volume over time for a capability or provider, plus the top public apps using it. | | `status_get` `GET /v1/status` public | Live health per provider: vendor failures in the last 30 seconds (the router's outage signal), last-hour error rate and latency, and 24-hour and 30-day uptime with daily bars. | | `tools_export` `GET /v1/tools` public | Endpoint and capability tools in OpenAI, Anthropic or MCP format. | | `registry_validate` `POST /v1/registry/validate` public | Lint a provider + endpoints YAML submission against the registry schema and margin guard. | | `usage_by_tag` `GET /v1/usage` `balance:read` | Spend and calls grouped by a meta tag over a window (reads the Postgres mirror). (planned: not yet available) | | `registry_submit` `POST /v1/registry/submissions` `keys:write` | Submit catalog YAML (validated as in registry_validate) for review by the GridRouter team. | | `announcements_list` `GET /v1/announcements` public | Current platform announcements (maintenance windows, incidents, launches). | | `review_create` `POST /v1/reviews/{provider}/{endpoint}` `call` | Leave a rating backed by your verified call count. (planned: not yet available) | | `waterfall_catalog` `GET /v1/waterfalls/catalog` `pipelines:read` | Every capability with its inputs, normalized output fields, and the endpoints a waterfall can use: price, quality, fill, p50 and rate limits. | | `waterfall_templates` `GET /v1/waterfalls/templates` public | Prebuilt GTM waterfalls (work email, mobile, verification, catch-all, person and company enrichment, job change, full lead enrichment, CRM hygiene and more). Each item has its inputs, outputs, sample_input, recommended speed and run_mode, the explained steps, and availability computed from the catalog: status (ready = runnable now, sandbox = runs on a test key, needs_integration = preview only), vendor_keys (add any one per stage in Settings > Vendor keys) and a list-price cost range in micro-USD. future lists recipes that aren't buildable yet and why. Public: no key needed. | | `waterfall_template_get` `GET /v1/waterfalls/templates/{template_id}` public | One template by id (or an earlier id): its definition, inputs and outputs, sample_input, explained steps and catalog availability (status, vendor_keys, cost range). Public: no key needed. | | `waterfall_create_from_template` `POST /v1/waterfalls/from-template` `pipelines:write` | Copy a template into your workspace in one call, optionally pinning vendors per stage, overriding speed or capping cost, and publish it (default) so waterfall_run works right away. Returns the waterfall (id, name, endpoint). Templates with status needs_integration are rejected with validation_failed. Next: waterfall_run with {id, input}. | | `waterfall_list` `GET /v1/waterfalls` `pipelines:read` | Waterfalls and pipelines in this org, newest first, with their published version. | | `waterfall_create` `POST /v1/waterfalls` `pipelines:write` | Create a draft waterfall (one capability, ordered vendor steps, speed profile, stop rules, per-field merge) or a multi-stage pipeline. Start from a definition, a template or a routing preset. | | `waterfall_get` `GET /v1/waterfalls/{id}` `pipelines:read` | One waterfall: its draft definition, versions and published endpoint. | | `waterfall_update` `PUT /v1/waterfalls/{id}` `pipelines:write` | Replace the draft definition, title or description. Published versions never change. | | `waterfall_delete` `DELETE /v1/waterfalls/{id}` `pipelines:write` | Delete a waterfall and its versions; its published endpoint stops answering. | | `waterfall_estimate` `POST /v1/waterfalls/estimate` `pipelines:read` | Price a waterfall before running it, without calling any vendor: per-step quote, p50 latency, fill and reach, plus worst-case and expected cost (micro-USD) and ETA. Pass a definition, or a template id with the same pins/speed/max_cost_micro choices as waterfall_create_from_template. | | `waterfall_versions` `GET /v1/waterfalls/{id}/versions` `pipelines:read` | Every published version (immutable), newest first. | | `waterfall_publish` `POST /v1/waterfalls/{id}/versions` `pipelines:write` | Freeze the draft as a new semver version and serve it at /v1/x/{workspace}/{name} (REST, MCP x_run and OpenAPI). | | `waterfall_rollback` `POST /v1/waterfalls/{id}/rollback` `pipelines:write` | Serve an earlier published version again. Nothing is deleted. | | `waterfall_preset` `GET /v1/waterfalls/{id}/preset` `pipelines:read` | The waterfall's vendor order as a routing preset body for presets_create, so /v1/run can use it as @slug. | | `waterfall_openapi` `GET /v1/waterfalls/{id}/openapi` `pipelines:read` | OpenAPI 3.1 for the waterfall's published endpoint /v1/x/{workspace}/{name}. | | `waterfall_run` `POST /v1/waterfalls/{id}/run` `pipelines:run` | Run a waterfall on one input and get the golden record: data, _provenance per field (vendor, confidence, verified, conflicts), _attempts, outcome (hit, partial, miss, failed) and cost_micro. Sync by default (up to 50 s). wait: N seconds falls back to a queued run; async: true returns at once with status queued and the run id: poll waterfall_status with {id, run_id}. version defaults to published; use draft for an unpublished waterfall. Set max_cost_micro to cap spend. A vendor you have no key for is skipped; when none can run, the error is vendor_key_required naming them. For lists use waterfall_batch_run. | | `waterfall_batch_run` `POST /v1/waterfalls/batch-run` `pipelines:run` | Run a waterfall over up to 1,000 inputs (JSON rows or CSV) in the background through gr-rows, paced per vendor. Returns the batch (a list) to poll. Runs as an MCP task. | | `waterfall_runs` `GET /v1/waterfalls/{id}/runs` `pipelines:read` | Recent runs of one waterfall: outcome, cost, time, attempts and fields filled. | | `waterfall_status` `GET /v1/waterfalls/{id}/runs/{run_id}` `pipelines:read` | Poll a run started with async or wait: status (queued, running, completed, failed, cancelled), then the golden record with _provenance per field, every attempt with its timing and error, and cost per filled field. | | `waterfall_run_events` `GET /v1/waterfalls/{id}/runs/{run_id}/events.json` `pipelines:read` | Progress events of a run after a sequence number (the SSE stream's JSON form). | | `waterfall_cancel` `POST /v1/waterfalls/{id}/runs/{run_id}/cancel` `pipelines:run` | Stop a queued or running run. In-flight attempts are aborted and released; the partial result is kept. | | `x_run` `POST /v1/x/{workspace}/{name}` `pipelines:run` | Call your own published waterfall by name: /v1/x/{workspace}/{name}, where workspace is your org id. Same modes as waterfall_run. | | `plans_list` `GET /v1/plans` public | Every GridRouter plan with its price, limits, features and managed-call markup, plus the shared overage rates and always-free list. | | `entitlements_get` `GET /v1/entitlements` `balance:read` | This org's plan, resolved limits (null means no cap), features and usage this month, including logged calls and overage blocks. | | `billing_get` `GET /v1/billing` `balance:read` | Billing mode, plan and subscription status, balance (with any simulated test credit), auto-recharge and receipts. | | `billing_checkout_create` `POST /v1/billing/checkout` `billing:write` | Buy credits (amount_usd, the 5.5% top-up fee is added) or upgrade to a paid plan. Returns a URL: Stripe Checkout, or the test purchase page when billing is simulated. | | `billing_checkout_get` `GET /v1/billing/checkout/{id}` `balance:read` | One checkout session and its status (open, completed, declined, requires_action). | | `billing_checkout_complete` `POST /v1/billing/checkout/{id}/complete` `billing:write` | Simulated billing only: approve, decline or require card action on a test checkout. Emits the same events Stripe would; no card is charged. | | `billing_plan_change` `PUT /v1/billing/plan` `billing:write` | Move to a lower plan, or to Free to cancel. Upgrades go through billing_checkout_create. | | `billing_autorecharge_set` `PUT /v1/billing/auto-recharge` `billing:write` | Top up by amount_usd whenever the balance drops below threshold_usd. | | `billing_simulate` `POST /v1/billing/simulate` `billing:write` | Test and simulated modes only: payment failure, dispute (freezes the org), refund, renewal, downgrade, cancel, auto-recharge, grant expiry, or reset simulated state. | | `options_schema` `GET /v1/options/schema` public | JSON Schema of ExecutionOptions: timing, concurrency, rate limits, cost, routing, data and cache, delivery, identity and observability. Every request body accepts it as `options`. | | `options_resolve` `POST /v1/options/resolve` `catalog:read` | What a request would run with: request options over the preset, your key's defaults and the workspace defaults, clamped by your plan. Returns where each value came from and what was clamped. | | `options_defaults_get` `GET /v1/options/defaults` `logs:read` | The workspace's default ExecutionOptions (the lowest precedence layer). | | `options_defaults_put` `PUT /v1/options/defaults` `presets:write` | Replace the workspace's default ExecutionOptions (cache TTLs per field class, log level, timeouts…). Applies to every key within 30 seconds. | | `keys_options_set` `PUT /v1/keys/{id}/options` `keys:write` | Default ExecutionOptions for one API key, between the preset and the workspace defaults. Send `{}` to clear. | | `cache_stats` `GET /v1/cache/stats` `logs:read` | Records (entities and exact responses), bytes, hits and the vendor spend cache hits saved this month and all time, plus daily hit/partial/miss counts. Cache hits are always free. | | `cache_list` `GET /v1/cache` `logs:read` | The cache explorer: each cached entity or response with its masked label, fields, their ages and freshness, hits and savings. Values are never returned here. | | `cache_purge` `DELETE /v1/cache` `cache:write` | Delete cached records by `key`, `tag` or `capability`, or everything with `all=true` (crypto-shreds the workspace cache key: nothing sealed before can be read again). | | `cache_forget` `POST /v1/cache/forget` `cache:write` | DSAR delete for the private cache: every cached record about this subject (entity records under all its identities and exact responses naming it) is removed. | | `cache_feedback` `POST /v1/cache/feedback` `cache:write` | Negative feedback, such as a bounce: the named fields are dropped from the subject's cached record so the next request fetches them again. | | `logs_tail` `GET /v1/logs/live/recent` `logs:read` | The newest events from the live tail (calls, waterfall run steps, jobs, lists and alerts), newest last, with the same filters as the stream: provider, capability, status, key, app, run or waterfall, minimum latency and cost, sample and fields. Stream them with GET /v1/logs/live or the logs://live MCP resource. | | `logs_live_ticket` `POST /v1/logs/live/ticket` `logs:read` | A single-use ticket valid for 60 seconds that opens GET /v1/logs/live without an Authorization header (browsers). Carries logs:read for this org only. | | `drains_list` `GET /v1/drains` `logs:read` | Log drains with their target, filter, batching and delivery health. Credentials are never returned. | | `drains_create` `POST /v1/drains` `credentials:write` | Send the live log to an HTTPS webhook (HMAC-signed), Axiom, Datadog, or S3, GCS or R2 as NDJSON. Credentials are stored encrypted in the vault and are write-only. Webhook drains return their signing secret once. | | `drains_get` `GET /v1/drains/{id}` `logs:read` | One drain with its delivery health. | | `drains_update` `PUT /v1/drains/{id}` `credentials:write` | Rename, pause or resume, change the target, filter or batching, or replace credentials. | | `drains_delete` `DELETE /v1/drains/{id}` `credentials:write` | Stop sending and remove the drain and its stored credentials. | | `drains_test` `POST /v1/drains/{id}/test` `credentials:write` | Send one sample event to the drain now and report the result; updates drain health. | | `alerts_summary` `GET /v1/alerts/summary` `logs:read` | Open alerts by severity, when the last one fired, and how many rules, destinations and webhook endpoints the workspace has. | | `alerts_rules_list` `GET /v1/alerts/rules` `logs:read` | Every alert rule with its metric, threshold, window, scope, severity, destinations, mute and live state (ok, firing, muted, no_data). New workspaces start with defaults (a vendor key failing, budgets at 80% and 100%, billing mismatches, error-rate and spend spikes, a key on a new IP, failing deliveries, security events). | | `alerts_rules_create` `POST /v1/alerts/rules` `keys:write` | Alert when a metric crosses a threshold over a window: error_rate, p95_latency, spend, budget_used, vendor_failure_spike, vendor_key_failing, billing_mismatch, cache_hit_rate, delivery_backlog, security_event or new_ip. Scope it to the workspace, a key, a vendor or a capability; route it to every destination or to chosen ones. | | `alerts_rules_get` `GET /v1/alerts/rules/{id}` `logs:read` | One alert rule with its state. | | `alerts_rules_update` `PUT /v1/alerts/rules/{id}` `keys:write` | Change any field; fields you leave out keep their value. Changing what the rule measures resolves its open alerts. | | `alerts_rules_delete` `DELETE /v1/alerts/rules/{id}` `keys:write` | Delete the rule and resolve its open alerts. | | `alerts_rules_mute` `POST /v1/alerts/rules/{id}/mute` `keys:write` | Snooze a rule for `minutes` (or until `until`); it keeps evaluating and recording alerts but sends nothing. `minutes: 0` unmutes. | | `alerts_rules_test` `POST /v1/alerts/rules/{id}/test` `keys:write` | Send a test alert to every destination the rule notifies, now, and report each result. Nothing is recorded as a real alert. | | `alerts_destinations_list` `GET /v1/alerts/destinations` `logs:read` | Where alerts go (email, webhook endpoints, Slack, Discord, Microsoft Teams, PagerDuty, Opsgenie) with delivery health. Secrets are masked. | | `alerts_destinations_create` `POST /v1/alerts/destinations` `credentials:write` | Connect email recipients (with optional hourly or daily digests), a webhook endpoint, a Slack or Discord incoming webhook, a Microsoft Teams Workflows URL, a PagerDuty Events API v2 integration key or an Opsgenie API key. The secret is stored encrypted in the vault and never returned. | | `alerts_destinations_get` `GET /v1/alerts/destinations/{id}` `logs:read` | One destination with its delivery health. | | `alerts_destinations_update` `PUT /v1/alerts/destinations/{id}` `credentials:write` | Rename, pause or resume, change the minimum severity or settings, or replace the secret. | | `alerts_destinations_delete` `DELETE /v1/alerts/destinations/{id}` `credentials:write` | Stop sending there and delete its stored secret. Rules that listed it stop routing to it. | | `alerts_destinations_test` `POST /v1/alerts/destinations/{id}/test` `credentials:write` | Deliver a test alert now and report the result (PagerDuty and Opsgenie tests open and immediately resolve their own incident). Test emails are queued. | | `alerts_list` `GET /v1/alerts` `logs:read` | Alerts newest first: open (triggered or acknowledged) or resolved, with how often each repeated and its timeline of notifications. | | `alerts_get` `GET /v1/alerts/{id}` `logs:read` | One alert with its full timeline. | | `alerts_acknowledge` `POST /v1/alerts/{id}/acknowledge` `keys:write` | Mark an open alert as being handled. PagerDuty and Opsgenie destinations are acknowledged too. | | `alerts_resolve` `POST /v1/alerts/{id}/resolve` `keys:write` | Close an open alert now; destinations that get resolve notifications are told. The rule's cooldown starts from here. | | `webhooks_event_types` `GET /v1/webhooks/event-types` `logs:read` | Every event a webhook endpoint can subscribe to, with when it is sent and the current api_version. | | `webhooks_endpoints_list` `GET /v1/webhooks/endpoints` `logs:read` | Webhook endpoints with their subscriptions, status and delivery health. Secrets are never returned. | | `webhooks_endpoints_create` `POST /v1/webhooks/endpoints` `credentials:write` | Receive events at an HTTPS URL, signed per Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature). Returns the whsec_ signing secret once. | | `webhooks_endpoints_get` `GET /v1/webhooks/endpoints/{id}` `logs:read` | One endpoint with its delivery health. | | `webhooks_endpoints_update` `PUT /v1/webhooks/endpoints/{id}` `credentials:write` | Change the URL, description or subscribed events, or enable and disable it (re-enabling an automatically disabled endpoint clears its failure count). | | `webhooks_endpoints_delete` `DELETE /v1/webhooks/endpoints/{id}` `credentials:write` | Stop delivering, delete its secrets and delivery log. | | `webhooks_endpoints_rotate_secret` `POST /v1/webhooks/endpoints/{id}/rotate-secret` `credentials:write` | Issue a new signing secret. The old one keeps signing alongside it for `overlap_s` (default 24 hours), so both verify while you deploy the new one. Returns the new secret once. | | `webhooks_endpoints_test` `POST /v1/webhooks/endpoints/{id}/test` `credentials:write` | Deliver an example event of the given type (marked test: true) to the endpoint now and return the delivery with its attempt. | | `webhooks_deliveries_list` `GET /v1/webhooks/deliveries` `logs:read` | Recent deliveries newest first with every attempt's status code, latency and a redacted response snippet. Kept 30 days. | | `webhooks_deliveries_get` `GET /v1/webhooks/deliveries/{id}` `logs:read` | One delivery with its attempts and the start of the signed body. | | `webhooks_deliveries_replay` `POST /v1/webhooks/deliveries/{id}/replay` `credentials:write` | Send a delivery again with the same webhook-id (receivers that dedupe on it ignore a duplicate) and a fresh retry schedule. | # Rate limits (/docs/rate-limits) Limits apply in layers. Every `429` says when to retry in `retry_after_ms`, and the request-rate limits name themselves in `error.details.layer` (`ip`, `burst`, `recovery`). | Layer | Applies to | Limit | On limit | | ------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------------- | | `ip` | Anonymous routes (catalog, `/openapi.json`, `/llms.txt`), per IP | 60 per 60 s | `429 rate_limited` | | `burst` | Each API key | 150 per 10 s | `429 rate_limited`, `Retry-After: 10` | | Concurrency | Calls in flight per workspace | 200 at once | `429 rate_limited`, retry after 250 ms | | `recovery` | Recovery-code redemption, per IP | 30 per 60 s, and a workspace lockout after 5 failed codes in 15 min | `429 rate_limited` | | Credit limits and budgets | Keys, agents, apps and runs with a spend cap | as configured | `403 budget_blocked` | | Provider capacity | Each provider and credential, from the provider's published limits | per provider | `503 provider_capacity_unavailable` | | Platform | Everyone, under extreme load | — | `503 grid_saturated` with `Retry-After` | Dashboard sign-in, sign-up and password reset have their own per-IP limits. ## Headers [#headers] Responses carry the IETF `RateLimit-Policy` header for the limiter that applied: ```http RateLimit-Policy: "burst";q=150;w=10 ``` A `429` also carries `RateLimit` with nothing remaining and `Retry-After`: ```http HTTP/1.1 429 Too Many Requests RateLimit: "burst";r=0;t=10 Retry-After: 10 ``` These headers are exposed to browsers through CORS. ## Provider limits [#provider-limits] Each provider has a token bucket, a concurrency limit and a circuit breaker per credential, set from the provider's published limits and your plan with them. When a provider answers `429`, GridRouter honors its `Retry-After`. A routed `/v1/run` moves on to the next provider instead of waiting, and returns `503 provider_capacity_unavailable` only when no provider has capacity. Adding a [fallback vendor key](/docs/getting-started/vendor-keys) gives the governor a second bucket. ## Handling a 429 [#handling-a-429] 1. Wait `retry_after_ms` (or `Retry-After` seconds), with jitter. 2. For bulk work, use [lists](/docs/api/async/list_create) or [batch waterfall runs](/docs/api/waterfalls/waterfall_batch_run), which pace rows per provider instead of failing them. 3. Spread high-volume traffic across several keys only if they belong to separate services; the workspace concurrency limit still applies. # TypeScript SDK (/docs/sdk) `@relaygrid/sdk` is not published yet. Until it is, call the [REST API](/docs/api) with `fetch` (see the [first call](/docs/getting-started/first-call)). This page documents the client as it stands, so you know what is coming. The SDK covers calls (one endpoint or a routed capability), waterfalls (templates, create, estimate, run and poll) and the live log. It runs anywhere with `fetch` and web streams on the server: Node 20+, Bun, Deno and Workers. Never ship an API key to a browser. ## Create a client [#create-a-client] ```ts import { createGrid } from "@relaygrid/sdk"; const grid = createGrid({ apiKey: process.env.GRID_API_KEY! }); ``` | Option | Default | | | ----------- | --------------------------- | ------------------------------------------------------------------------------------------------------------- | | `apiKey` | — | A key with `call` and `run` for calls, `pipelines:read`/`write`/`run` for waterfalls, `logs:read` for the log | | `baseUrl` | `https://api.gridrouter.io` | | | `fetch` | global `fetch` | Inject your own (tests, proxies) | | `userAgent` | — | Sent as `User-Agent` | | `app` | — | Sent as `X-Grid-App`, so calls are attributed to your app in logs | | `title` | — | Sent as `X-Title`: your app's display name | ## Run a capability [#run-a-capability] `run` lets GridRouter route: it tries the providers for a capability in route order and stops at the first hit. The body is the [run request](/docs/api/calls/run). ```ts const result = await grid.run("people.email.find", { input: { first_name: "Ada", last_name: "Lovelace", domain: "stripe.com" }, options: { cost: { max_cost_micro: 50_000 } }, }); console.log(result.provider, result.data); ``` ## Call one endpoint [#call-one-endpoint] `call` pins a provider endpoint. Async endpoints return a `Job` to poll instead of a result. ```ts const res = await grid.call("hunter/email.find", { input: { first_name: "Ada", last_name: "Lovelace", domain: "stripe.com" }, include_raw: true, }); ``` ## Stream the live log [#stream-the-live-log] ```ts const tail = grid.logs.tail( { filter: { kinds: "call", capability: "people.email.find", status: "failed" }, onControl: (frame) => console.error(frame.kind), onError: (err) => console.error(err), }, (event) => { if (event.kind === "call") console.log(event.row.call_id, event.row.outcome); }, ); // later tail.close(); await tail.done; console.log(`dropped ${tail.dropped} events`); ``` `filter` takes the same keys as the [live tail](/docs/concepts/logs-and-drains#live-tail). `tail` streams over SSE, reconnects with backoff from 0.5 s to 10 s, asks for `replay=100` on reconnect and skips events it has already delivered. It stops on a 4xx other than 429 and reports it to `onError`. Pass `signal` to stop with an `AbortSignal`, or `reconnect: false` to stop at the first disconnect. ## Read recent events [#read-recent-events] ```ts const { items } = await grid.logs.recent({ kinds: "call", limit: 20 }); ``` `items` is newest last, up to 1,000 (default 50). ## Waterfalls [#waterfalls] ```ts // The library, with which vendor keys unlock each template and its list-price cost const { items } = await grid.waterfalls.templates.list({ category: "contacts", runnable: true }); const template = await grid.waterfalls.templates.get("work-email"); // Price it, then copy it into your workspace (published as 1.0.0) const estimate = await grid.waterfalls.estimate( { template: "work-email", speed: "balanced" }, template.sample_input, ); const wf = await grid.waterfalls.fromTemplate("work-email", { pins: { email: ["hunter"] }, max_cost_micro: 100_000, idempotencyKey: "wf-work-email-1", }); // Sync run, or async plus polling for multi-stage templates const run = await grid.waterfalls.run(wf.id, { first_name: "Ada", last_name: "Lovelace", domain: "example.com" }); const queued = await grid.waterfalls.run(wf.id, { email: "ada@example.com" }, { async: true }); const done = await grid.waterfalls.waitFor(wf.id, queued.id, { intervalMs: 1000, timeoutMs: 120_000 }); ``` | Method | Calls | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `templates.list(query?)` | `GET /v1/waterfalls/templates` (`category`, `q`, `runnable`, `sandbox`) | | `templates.get(id)` | `GET /v1/waterfalls/templates/{id}` | | `fromTemplate(template, options?)` | `POST /v1/waterfalls/from-template` (`pins`, `pins_only`, `speed`, `max_cost_micro`, `name`, `publish`, `idempotencyKey`) | | `estimate(body, input?)` | `POST /v1/waterfalls/estimate` with `{definition}` or `{template, …choices}` | | `run(id, input, options?)` | `POST /v1/waterfalls/{id}/run` (`version`, `max_cost_micro`, `wait`, `async`, `webhook_url`, `fields`, `idempotencyKey`) | | `status(id, runId)` | `GET /v1/waterfalls/{id}/runs/{run_id}` | | `waitFor(id, runId, options?)` | Polls `status` until `completed`, `failed` or `cancelled`; throws `wait_timeout` after `timeoutMs` (default 120 s) | See [waterfall templates](/docs/concepts/waterfall-templates) and [build a waterfall](/docs/concepts/build-a-waterfall). ## Errors [#errors] Failed calls throw `GridApiError`, which carries the [error envelope](/docs/errors)'s `code`, `message` and HTTP `status`. ## Skill: gridrouter-customer-integration Source: https://gridrouter.io/.well-known/agent-skills/gridrouter-customer-integration/SKILL.md ````markdown --- name: gridrouter-customer-integration description: Integrates an application or agent with GridRouter, one API key and MCP server for go-to-market data vendors — key setup, catalog search, quotes, routed runs and direct endpoint calls, your own vendor keys, waterfalls, logs and live tail, errors, rate limits and idempotency. Use when calling the GridRouter API or connecting an agent to the GridRouter MCP server. --- # GridRouter customer integration GridRouter gives you one API, one key and one MCP server for go-to-market data vendors (email finders, enrichment, verification, search and more), with a quality score on every endpoint. ## When to use - Calling `https://api.gridrouter.io`, connecting an agent to `https://mcp.gridrouter.io/mcp`, or choosing a capability, vendor or waterfall. ## Prerequisites - An account at https://gridrouter.io and an API key from Settings > API keys. Keys look like `grid_live_…` (real vendors) or `grid_test_…` (sandbox endpoints only). Give the key only the scopes you need: `call`, `run`, `logs:read`, `credentials:write`, `pipelines:read`, `pipelines:write`, `pipelines:run`. - Store it in an environment variable (`export GRID_API_KEY=…` from your secret manager). Never print it, log it, commit it or paste it into chat or a prompt. - Machine-readable references: OpenAPI at https://api.gridrouter.io/openapi.json, docs index at https://gridrouter.io/llms.txt (also https://api.gridrouter.io/llms.txt). ## Steps 1. Find what to call (public, no key): `GET /v1/catalog/capabilities?category=people`, `GET /v1/catalog/endpoints?q=email&capability=people.email.find`, `GET /v1/catalog/endpoints/{provider}/{endpoint}` (input JSON Schema, pricing, quality), `GET /v1/catalog/leaderboards/{capability}`. 2. Price it without spending: `POST /v1/quote/{provider}/{endpoint}` with `{"input": {...}}` returns `quote_micro`. 3. Run a capability (GridRouter routes across vendors until one hits; per-success vendors bill only hits): ```bash curl -sS https://api.gridrouter.io/v1/run/people.email.find \ -H "Authorization: Bearer $GRID_API_KEY" -H "Idempotency-Key: lead-8841" \ -H 'content-type: application/json' \ -d '{"input":{"first_name":"Ada","last_name":"Lovelace","domain":"example.com"},"max_cost_micro":50000,"provider":{"sort":"quality"}}' ``` Optional body fields: `provider` (`order`, `only`, `ignore`, `allow_fallbacks`, `sort`: price|reliability|latency|throughput|quality, `max_price_micro`), `fields` (return only these output fields), `stop_when` (`hit`|`success`), `credential` (`auto`|`managed`|`byok`), `preset` (`@slug`). Don't know the capability? `POST /v1/run/auto` with your input picks one. 4. Or call one endpoint verbatim: `POST /v1/call/{provider}/{endpoint}` with `{"input": {...}, "max_cost_micro": 50000}`. Async vendors return `202` with a job; poll `GET /v1/jobs/{id}`. 5. Read the cost: every money field is integer micro-USD (1 USD = 1,000,000). Buffered call responses carry `cost_micro` and `credential` (`managed` or `byok`); routed results also carry `attempts[]`. Headers include `X-Grid-Call-Id` and `X-Grid-Cost-Micro`. Look a call up later with `GET /v1/logs/{id}` to verify credential provenance, upstream status and cost; balance at `GET /v1/balance`. 6. Your own vendor keys (BYOK, never charged by GridRouter): Settings > Vendor keys in the dashboard, or the API with scope `credentials:write`: inspect the `providers` array in `GET /v1/credentials`; when `testable` is true, test first with `POST /v1/credentials/{provider}/verify` `{"fields":{"api_key":"…"}}` (nothing stored). Save with `PUT /v1/credentials/{provider}` `{"slot":"primary","fields":{"api_key":"…"},"label":"Prod"}`, re-test testable providers with `POST /v1/credentials/{provider}/test`, and list metadata with `GET /v1/credentials`. For supported RapidAPI integrations, save one shared `X-RapidAPI-Key` under provider `rapidapi`; subscribe to each API separately in RapidAPI. A provider-specific key takes priority over the shared key. Shared RapidAPI credentials have no generic free test; verify them with an authorized call within your subscription's allowance. Research listings need an integration before they can run. An unknown field name returns `invalid_request` with the allowed names in `details.allowed`. Read vendor keys from your secret store; never echo them. 7. Waterfalls (saved multi-vendor recipes; the full workflow is in [gridrouter-waterfalls](../gridrouter-waterfalls/SKILL.md)): list templates with `GET /v1/waterfalls/templates?runnable=true` (public), create and publish one in a call with `POST /v1/waterfalls/from-template` `{"template":"work-email","max_cost_micro":100000}`, or build your own with `POST /v1/waterfalls`; price with `POST /v1/waterfalls/estimate`, publish with `POST /v1/waterfalls/{id}/versions` `{"bump":"minor"}`, run with `POST /v1/waterfalls/{id}/run` `{"input":{...},"max_cost_micro":100000}` (add `"wait": 30` or header `Prefer: respond-async` for long runs; poll `GET /v1/waterfalls/{id}/runs/{run_id}`). Batch up to 1,000 rows: `POST /v1/waterfalls/batch-run`. 8. Logs (scope `logs:read`): `GET /v1/logs` (filters, `limit`, `cursor`), `GET /v1/logs/{id}`, `GET /v1/logs/stats`, `GET /v1/logs/facets`. Live tail: `curl -N "https://api.gridrouter.io/v1/logs/live?format=sse&status=error" -H "Authorization: Bearer $GRID_API_KEY"` (or a WebSocket upgrade); recent events at `GET /v1/logs/live/recent?limit=50`. 9. MCP: point your client at `https://mcp.gridrouter.io/mcp` (Streamable HTTP). Interactive clients sign in with OAuth; headless agents send `Authorization: Bearer $GRID_API_KEY`. Server card: `https://mcp.gridrouter.io/mcp/server-card`. Tools share the REST names (`catalog_search`, `catalog_get`, `quote`, `run`, `call`, `waterfall_templates`, `waterfall_create_from_template`, `waterfall_run`, `logs_list`, …); call `tools/list` to see what your key's scopes allow. ## Verify - `curl -sS "https://api.gridrouter.io/v1/catalog/endpoints?q=email" | jq '.items[0].id'` works without a key. - A quote returns `quote_micro`; a run returns `object: "call"` with `hit`, `cost_micro` and `attempts`. - The call appears in `GET /v1/logs` and in the dashboard's logs page. ## Errors, limits and retries - Every error body is `{"error":{"code","message","request_id","call_id","retry_after_ms","details"}}`. Common codes: `invalid_request` 400, `unauthorized` 401, `insufficient_balance` and `max_cost_exceeded` 402, `scope_denied`, `budget_blocked`, `vendor_key_required` and `account_frozen` 403, `not_found` 404, `conflict` 409, `idempotency_mismatch` and `strict_filters` 422, `rate_limited` 429, `upstream_error` 502, `provider_capacity_unavailable` and `grid_saturated` 503, `upstream_timeout` 504. - On 429 and 503 wait for `Retry-After` (or `retry_after_ms`), then retry with backoff; `RateLimit` and `RateLimit-Policy` headers show your remaining budget. Don't retry 4xx other than 409 and 429 without changing the request. - Send `Idempotency-Key` (1–128 characters) on every run, call and create. A retry with the same key and body within 24 hours replays the stored response for free; the same key with a different body is `422 idempotency_mismatch`; one still in flight is `409 conflict`. - Failed calls, and misses on per-success vendors, are not charged. Set `max_cost_micro` (or header `X-Grid-Max-Cost` in USD) on every paid request. ## Safety rules - Keep GridRouter and vendor keys in env vars or a secret manager; never print, log or commit them. - Use `grid_test_` keys while developing; switch to `grid_live_` only when ready to spend. - Only look up people and companies you have a lawful basis to process. ```` ## Skill: gridrouter-waterfalls Source: https://gridrouter.io/.well-known/agent-skills/gridrouter-waterfalls/SKILL.md ````markdown --- name: gridrouter-waterfalls description: Builds and runs GridRouter waterfalls, multi-vendor recipes that return one golden record per input, from prebuilt templates (work email, mobile, verification, person, company, job change, full lead enrichment, CRM hygiene) — choosing a template and speed, pinning vendors, estimating and capping cost, sync, async and batch runs, reading provenance and conflicts, and fixing vendor_key_required. Use when enriching records through the GridRouter API or MCP server with more than one vendor. --- # GridRouter waterfalls A waterfall tries vendors for one capability until the stop rule holds, merges their answers field by field into a golden record, and records who supplied each field. Templates are prebuilt waterfalls; every step is a routed pool, so GridRouter picks the vendors unless you pin them. ## When to use - One input needs several vendors (find, then verify; profile, then email), or a list of rows needs the same recipe. For a single vendor call use `/v1/run/{capability}` instead. ## Prerequisites - API key in `$GRID_API_KEY` (never print, log or paste it) with `pipelines:read`, `pipelines:write`, `pipelines:run` (+ `lists` to poll batches). `grid_test_…` keys run only the `sandbox-*` templates (no vendor key needed; sandbox calls still draw on credit at list price). - Vendor keys: at launch every vendor call uses your own key (BYOK). GridRouter charges $0 on it and the vendor bills its own rate; template costs are list-price guidance. Add keys in Settings > Vendor keys or `PUT /v1/credentials/{provider}` (scope `credentials:write`). - REST base `https://api.gridrouter.io`; MCP `https://mcp.gridrouter.io/mcp`. Each MCP tool shares the REST operation's name (shown in brackets below). ## Steps 1. Pick a template (public, no key) [`waterfall_templates`, `waterfall_template_get`]: `curl -sS "https://api.gridrouter.io/v1/waterfalls/templates?runnable=true&q=email" | jq '.items[] | {id, status: .availability.status, inputs: [.inputs[].name]}'`. `GET /v1/waterfalls/templates/{id}` shows inputs, `input_rule`, outputs, `sample_input`, explained steps and `availability` (`status`, `vendor_keys` per stage, `cost` range). Only `ready` and `sandbox` run; `needs_integration` is preview only. | Goal | Template id | | --- | --- | | Work email from name + domain; from a profile URL | `work-email`; `email-from-profile` | | Mobile number; verify an email; resolve catch-alls | `mobile-number`; `email-verification`; `catch-all-resolution` | | Who owns an email; enrich a person | `reverse-email-lookup`; `person-enrichment` | | Job changes; people by role; staff list | `job-change-detection`; `decision-makers`; `employee-list` | | Firmographics; everything on a lead | `company-enrichment`; `full-lead-enrichment` | | Form fill (email in); CRM cleanup; role + verified email | `inbound-lead-enrichment`; `crm-hygiene`; `decision-maker-emails` | | Try it free on a test key (`scenario` input scripts vendors) | `sandbox-work-email`, `sandbox-mobile-number`, `sandbox-company-enrichment`, `sandbox-email-then-mobile` | 2. Choose speed: `fast` races vendors (lowest latency, may pay more than one), `balanced` goes one at a time and hedges a slow vendor, `thorough` goes cheapest first with the longest deadline. Leave it unset to keep the template's. 3. Estimate without calling a vendor [`waterfall_estimate`]: `POST /v1/waterfalls/estimate` `{"template":"work-email","speed":"balanced","pins":{"email":["hunter"]}}` (or `{"definition":{…}}`) returns `worst_case_cost_micro`, `expected_cost_micro`, `expected_ms`, `steps[]` and `issues[]`. Money is integer micro-USD (1 USD = 1,000,000). 4. Create and publish in one call [`waterfall_create_from_template`]: ```bash curl -sS https://api.gridrouter.io/v1/waterfalls/from-template \ -H "Authorization: Bearer $GRID_API_KEY" -H "Idempotency-Key: wf-work-email-1" -H 'content-type: application/json' \ -d '{"template":"work-email","speed":"balanced","max_cost_micro":100000,"pins":{"email":["hunter"]}}' | jq '{id, name, published_version}' ``` `pins` maps a stage id to vendor slugs tried first; the router still falls back unless `"pins_only": true`. `name` defaults to the template id (`-2`, `-3`… if taken); `publish: false` keeps a draft (run it with `"version":"draft"`). 5. Run one record [`waterfall_run`]: `POST /v1/waterfalls/{id}/run` `{"input":{"first_name":"Ada","last_name":"Lovelace","domain":"example.com"},"max_cost_micro":100000}`. Sync by default (up to 50 s). Multi-stage or slow templates (`run_mode: async`): add `"async": true` (or `"wait": 20` to fall back to `202`), optional `webhook_url` (https), then poll [`waterfall_status`] `GET /v1/waterfalls/{id}/runs/{run_id}` until `status` is `completed`, `failed` or `cancelled`. `fields` trims the output. 6. Lists (`run_mode: batch`) [`waterfall_batch_run`]: `POST /v1/waterfalls/batch-run` `{"waterfall_id":"wf_…","inputs":[{…}],"max_cost_micro_per_run":50000}` (≤ 1,000 rows, or `"csv":"email\n…"`). It returns `202` with `id` and `status_url`; poll `GET /v1/lists/{id}` (`done`/`total`, `hits`, `failed`, `cost_micro`, `status`) and page results with `GET /v1/lists/{id}/rows`. ## Reading a run - `outcome`: `hit` (every stage's stop rule held), `partial` (some fields filled), `miss`, `failed`; `stop_reason` says why it ended (`first_hit`, `exhausted`, `budget_exceeded`, `deadline_exceeded`, …). - `data` is the golden record. `_provenance.` names the `provider`, `endpoint_id`, `call_id`, `stage_id`, `confidence`, `verified` and merge `strategy`; `conflicts[]` lists other vendors' disagreeing values: surface them, don't silently drop them. - `_attempts[]` is every vendor try with `status` (hit, miss, failed, skipped, timeout, cancelled), `reason` (`missing_input`, `over_run_budget`, `low_confidence`, …), `cost_micro`, `latency_ms` and `error`. `cost_micro` and `cost_per_field_micro` total the run. ## Verify - The template returns `availability.status` `ready` (or `sandbox` on a test key), the estimate has no `issues`, and a run on the template's `sample_input` returns `object: "waterfall_run"` with `outcome` and `_attempts`. ## Errors - `403 vendor_key_required`: no vendor that could run has your key. `error.message` and `error.details` name the vendors; add a key for any one of them (see Prerequisites), or re-create with `pins` (plus `pins_only`) on vendors you already have keys for. While at least one vendor can run, vendors without a key are just skipped. - `422 validation_failed`: bad input, pin or template (`details.issues[].path`); `needs_integration` templates always return it on create. - `stop_reason: budget_exceeded` (partial `data`): the next attempt would pass `max_cost_micro`; re-run the estimate before raising it. `404 not_found`: wrong waterfall, run or template id. - `429`/`503`: wait `retry_after_ms`, retry with the same `Idempotency-Key`. ## Safety - Set `max_cost_micro` on every create and run (`max_cost_micro_per_run` on batches); estimate before large batches. Develop on `grid_test_` keys and `sandbox-*` templates. - Keys stay in env vars or a secret manager; never echo GridRouter or vendor keys. Only enrich people you have a lawful basis to process. ````