Provider router

Router options

The object and all four fields are optional. Omitting router keeps the account's existing routing behavior.

Mode and provider names ignore surrounding whitespace and capitalization. Unknown names or modes are ignored. Omitting mode leaves the account's existing routing behavior unchanged. It is not the same as sending fallback. A field with the wrong JSON type, such as a number for mode or a string for credentials, is rejected.

Setup and examples

Save a provider key

1. Get an API key using your provider's setup documentation below.
2. Sign in to Vendor keys, choose the provider, and save its key.
3. Once routing is available for your account, allow about a minute for a saved key change to take effect.

Stored keys let you omit inline credentials for fallback requests. A stored key alone does not qualify a request for first; send provider and token as shown below.

Try Spider first

Set SPIDER_API_KEY in your shell before running this example. With no provider preference, the router chooses among eligible routes. Without a usable key of your own, a provider attempt can use Spider's credentials and pooled billing.

curl https://api.spider.cloud/scrape \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "return_format": "markdown",
    "router": { "mode": "fallback" }
  }'

Request a provider first

Set SPIDER_API_KEY and ZYTE_API_KEY in your environment. This Python example uses only the standard library. Spider authentication stays in the header. The provider key goes in router.token.

import json
import os
from urllib.request import Request, urlopen

body = {
    "url": "https://example.com",
    "return_format": "markdown",
    "router": {
        "mode": "first",
        "provider": "zyte",
        "token": os.environ["ZYTE_API_KEY"],
    },
}
request = Request(
    "https://api.spider.cloud/scrape",
    data=json.dumps(body).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['SPIDER_API_KEY']}",
        "Content-Type": "application/json",
    },
)
with urlopen(request) as response:
    print(json.load(response))

The request still has to meet the route's capability and budget checks. first does not force a specific provider or bypass account availability.

Multiple keys and credential precedence

Replace these placeholders with your own keys in server-side code. Leaving out provider lets the router choose among eligible providers.

{
  "url": "https://example.com",
  "router": {
    "mode": "fallback",
    "credentials": {
      "ZYTE_API_KEY": "YOUR_ZYTE_API_KEY",
      "FIRECRAWL_API_KEY": "YOUR_FIRECRAWL_API_KEY"
    }
  }
}

For the same credential name, the highest-priority value wins:

1. router.token, mapped to the named provider.
2. router.credentials.
3. The legacy top-level vendor_credentials map.
4. The key saved in Vendor keys.

Keys for different providers merge. The legacy top-level provider still works. router.provider takes precedence when supplied. Use the nested object for new requests.

Billing follows the provider route that actually runs. Your own key must cover that route for BYOK billing, where you pay the provider directly and Spider charges its markup. A provider preference alone does not change billing, and failover can reach a route using Spider's pooled credentials.

Provider setup links

These providers accept a single key through router.token or Vendor keys. The credential name column is for router.credentials. Each link opens the provider's own documentation for account and API setup.

oxylabs and dataforseo are recognized provider preferences, but their paired credentials are not supported by the current BYOK allowlist. token, credentials, and Vendor keys cannot supply BYOK credentials for them. They do not qualify for the token-based first request. Their eligible routes use pooled credentials.

Provider-specific options

Put vendor-native settings in the top-level provider_options object, outside router, keyed by provider name. Consult the provider's documentation for supported settings.

{
  "url": "https://example.com",
  "router": {
    "mode": "fallback",
    "provider": "zyte",
    "token": "YOUR_ZYTE_API_KEY"
  },
  "provider_options": {
    "zyte": {
      "geolocation": "US"
    }
  }
}

Spider applies these settings only when the route uses your own provider key. It drops them on pooled routes. Options for one provider never carry over to another provider during failover.

Supply the target in url and authentication in router.token or router.credentials. Target and authentication keys inside provider_options, including url, api_key, and token, are dropped.

Troubleshooting

• If routing appears unchanged, check account availability first. The API can accept the object while provider routing is disabled.
• If first does not try your provider first, check that you sent a supported provider and nonblank token. Stored keys and a credentials map do not substitute for that token. If those fields are correct, ask support whether provider-first routing is enabled for your account.
• If a token has no effect, check the provider spelling. The token contributes no key if it is blank, if the provider is unknown or missing, or if the provider requires paired credentials.
• If another provider handles the request, the preferred route may be unavailable, unsuitable for the request, or may have failed. A provider preference is not a restriction to that provider.
• If native settings have no effect, check that provider_options is outside router and that the dispatched route uses your own key.

Continue with the common parameter reference, Scrape API , or Crawl API.