Provider status

BetterJobs depends on six partner providers and its own index. When one is slow or down, your results can be thinner. GET /v1/providers tells you the live state of each source, and every search response tells you which sources actually answered.

Check status

GET /v1/providers is free. It lists every source BetterJobs can route to, whether your plan includes it, and its status.

curl

curl https://api.betterjobs.cc/v1/providers \
  -H "Authorization: Bearer $BETTERJOBS_API_KEY" \
  -H "BetterJobs-Version: 2026-10-01"

Python

import os
import requests

resp = requests.get(
    "https://api.betterjobs.cc/v1/providers",
    headers={
        "Authorization": f"Bearer {os.environ['BETTERJOBS_API_KEY']}",
        "BetterJobs-Version": "2026-10-01",
    },
    timeout=30,
)
resp.raise_for_status()
for p in resp.json()["data"]:
    print(p["slug"], p["status"], "enabled" if p["enabled_on_your_plan"] else "not on plan")

TypeScript

const res = await fetch("https://api.betterjobs.cc/v1/providers", {
  headers: {
    Authorization: `Bearer ${process.env.BETTERJOBS_API_KEY}`,
    "BetterJobs-Version": "2026-10-01",
  },
});
if (!res.ok) throw new Error(`BetterJobs ${res.status}: ${await res.text()}`);
const { data } = await res.json();
for (const p of data) {
  console.log(p.slug, p.status, p.enabled_on_your_plan ? "enabled" : "not on plan");
}

Illustrative response, seen from a Growth plan:

{
  "data": [
    { "slug": "betterjobs", "name": "BetterJobs index", "enabled_on_your_plan": true, "status": "operational", "last_checked_at": "2026-10-11T09:00:00Z" },
    { "slug": "reqbeat", "name": "Reqbeat", "enabled_on_your_plan": false, "status": "operational", "last_checked_at": "2026-10-11T09:00:00Z" },
    { "slug": "signalsapi", "name": "SignalsAPI", "enabled_on_your_plan": false, "status": "operational", "last_checked_at": "2026-10-11T09:00:00Z" },
    { "slug": "theirstack", "name": "TheirStack", "enabled_on_your_plan": true, "status": "operational", "last_checked_at": "2026-10-11T09:00:00Z" },
    { "slug": "jobspipe", "name": "JobsPipe", "enabled_on_your_plan": false, "status": "operational", "last_checked_at": "2026-10-11T09:00:00Z" },
    { "slug": "coresignal", "name": "Coresignal", "enabled_on_your_plan": false, "status": "degraded", "last_checked_at": "2026-10-11T09:00:00Z" },
    { "slug": "techmap", "name": "Techmap", "enabled_on_your_plan": true, "status": "operational", "last_checked_at": "2026-10-11T09:00:00Z" }
  ]
}

Fields

Field	Type	Meaning
slug	betterjobs | reqbeat | signalsapi | theirstack | jobspipe | coresignal | techmap	Source id. The same slug appears in sources[].provider, waterfall.providers and metadata.providers. betterjobs is the BetterJobs index.
name	string	Display name.
enabled_on_your_plan	boolean	Whether your plan can route to this source. GET /v1/account lists the same set as providers_enabled.
status	operational | degraded | down	Live state of the source.
last_checked_at	date-time	When this status was last checked.

What each status means for you:

status	What to expect
operational	Normal.
degraded	The source is answering badly, for example slowly or with errors. It is more likely to show up in metadata.providers.failed.
down	The source is not answering. Expect it in metadata.providers.failed on every request that tries it.

Sending a provider that is not enabled on your plan in waterfall.providers returns 403 plan_required, with error.required_plan and error.upgrade_url. See Errors.

How degradation affects your results

A failing provider never fails your request. BetterJobs waits up to waterfall.timeout_ms (default 10,000 ms), drops any provider that errors or misses it, and returns what the others found.

You get 200 with metadata.status: "partial". The failed provider is in metadata.providers.failed:

{
  "metadata": {
    "status": "partial",
    "credits_charged": 1,
    "providers": {
      "tried": ["betterjobs", "techmap", "theirstack", "coresignal"],
      "hit": ["betterjobs", "techmap", "theirstack"],
      "failed": [{ "provider": "coresignal", "code": "provider_timeout" }],
      "contributions": { "betterjobs": 1, "techmap": 0, "theirstack": 0 }
    }
  }
}

• code is provider_timeout (missed timeout_ms) or provider_error (the provider returned an error).
• You pay only for jobs returned. A provider that failed costs nothing.
• Jobs only that provider would have found are missing from this page.
• An async search that ends this way has status: "partial".

metadata.providers is the receipt for each request: tried (asked), hit (returned at least one match), failed, and contributions (unique jobs each source added first).

When a partial result is not good enough

• Retry later. A repeat is cheap: jobs you already paid for come back free.
• Give slow providers more time. Raise waterfall.timeout_ms, up to 30,000.
• Route around it. Set waterfall.providers to the list without the failing source.
• Branch in code. Treat metadata.status: "partial" as “complete, but maybe not exhaustive”. For backfills, re-run partial pages once the provider is operational again.

What this page does not show

• Uptime history and latency percentiles. Not published during the preview. They are published at GA. Each response reports its own latency_ms in metadata.
• Per-provider coverage and freshness. These differ by source. What each provider says about itself is on its card under Providers, attributed to that provider. For your own queries, read metadata.field_coverage and metadata.providers.contributions.

Related

• Waterfall for how providers are tried.
• Choose a strategy for picking a strategy and providers.
• Troubleshooting for partial and empty results.