Results and statuses
What each run status means, every reason code, and what to do about each.
Every run ends with a status, and — unless the status is ok — a reason. Together they tell you what
happened and what, if anything, to do about it.
The rule behind them: we report what happened. A site we could not read is not an empty result, and a partial result is not passed off as a complete one.
Statuses#
A run starts queued, becomes running, and ends in exactly one of five final statuses.
| Status | Final | Records | Charged | Meaning |
|---|---|---|---|---|
| queued | No | — | — | Accepted and waiting for a worker. |
| running | No | — | — | Being executed now. |
| ok | Yes | Zero or more | Yes | The target was read. Zero records means there was nothing to find. |
| partial | Yes | One or more | Yes | Records were found, but something stopped the run from reading everything. reason says what. |
| failed | Yes | None | No | The run could not read the target. reason says why. |
| unsupported | Yes | None | No | The target needs something we do not do. reason says what. |
| cancelled | Yes | Zero or more | No | You cancelled the run and it stopped. What it had found before the stop stays readable. |
How charging works is in Usage and units.
ok#
The scraper read what it set out to read. reason is null.
ok with record_count 0 is a real, complete answer — for example a careers page that lists no openings today.
It is charged like any other ok.
ok means we read the target, not the data is perfect. A scraper can be wrong about a site. The careers
scrapers therefore say on every record how it was obtained (extraction), and a result read entirely off a
company's own pages is not reported as a plain ok — see Careers and job boards. Look at
diagnostics.facts when a result surprises you — it names the page that was read.
This is a finished ok run, as the API returned it:
{
"id": "run_6cce2b12aaf37a10b5e1b885",
"scraper_id": "ats.board",
"scraper_version": 1,
"status": "ok",
"reason": null,
"input": {
"board_url": "https://boards.greenhouse.io/acme"
},
"record_count": 19,
"units": 1,
"diagnostics": {
"requests": 1,
"bytes": 232779,
"wall_ms": 565,
"facts": {
"careers_url": "https://boards.greenhouse.io/acme",
"discovery": "supplied",
"ats": "greenhouse",
"pages_read": 1,
"renders_refused": 0
}
},
"created_at": "2026-11-16T20:27:29.009834Z",
"started_at": "2026-11-16T20:27:29.013803Z",
"finished_at": "2026-11-16T20:27:29.582787Z"
}partial#
There are records, and there is a known gap. Use the records, and read reason to learn what is missing:
render_required— part of the site needs a JavaScript render, which we do not do yet. The records come from the parts that did not need one. The list may be incomplete.deadline_exceeded— the run ran out of time. The records are what was read before then.temporarily_unavailable— part of the site could not be fetched at the moment. Running again later can give more.private_address_refused— part of the site sits at an address that is not on the public internet, and was not read.unverified_page_extraction— every record was read off the company's own pages, none from an applicant tracking system. Some may not be job postings.- a refusal such as
blockedorrate_limited— a search that reads several pages was refused part-way. The records are what was read before.
failed#
Nothing could be read, and the cause is on the way to the target or at the target: the site did not answer, the
page does not exist, or we had an error fetching it. A failed run costs nothing. Whether to try again depends on the
reason — see the tables below.
{
"id": "run_9b6e0a489a34069dd67dc112",
"scraper_id": "ats.board",
"scraper_version": 1,
"status": "failed",
"reason": "adapter_failed",
"input": {
"board_url": "https://boards.greenhouse.io/acme-board-that-does-not-exist"
},
"record_count": 0,
"units": 0,
"diagnostics": {
"requests": 1,
"bytes": 38,
"wall_ms": 394,
"facts": {
"careers_url": "https://boards.greenhouse.io/acme-board-that-does-not-exist",
"discovery": "supplied",
"ats": "greenhouse",
"pages_read": 1,
"renders_refused": 0
}
},
"created_at": "2026-11-16T20:27:29.628500Z",
"started_at": "2026-11-16T20:27:29.632396Z",
"finished_at": "2026-11-16T20:27:30.028545Z"
}unsupported#
The honest answer when the target needs something we do not have. Today that is mostly one thing: a careers page
or board that only shows its content after running JavaScript. We do not render pages yet — see How we fetch.
An unsupported run costs nothing.
{
"id": "run_9eebae2bc0db3036c9893cda",
"scraper_id": "ats.board",
"scraper_version": 1,
"status": "unsupported",
"reason": "render_required",
"input": {
"board_url": "https://jobs.dayforcehcm.com/en-US/acme/CANDIDATEPORTAL"
},
"record_count": 0,
"units": 0,
"diagnostics": {
"requests": 0,
"bytes": null,
"wall_ms": 0,
"facts": {
"ats": "dayforce"
}
},
"created_at": "2026-11-16T20:27:29.617445Z",
"started_at": "2026-11-16T20:27:29.619938Z",
"finished_at": "2026-11-16T20:27:29.623160Z"
}unsupported is not a temporary error. Do not retry it; the answer will be the same until the scraper changes.
The one exception is the reason temporarily_unavailable, which says so itself.
cancelled#
You asked for the run to stop with POST /v1/runs/{id}/cancel and it did. Its reason is cancelled, it costs
nothing, and the records it had found before the stop — if any — can still be read. Cancelling is cooperative, so a
run that was already finishing can still end with another status — see Cancel a run.
Reason codes#
reason is a stable, lowercase code. It is null when the status is ok and set otherwise. Match on the code;
never on a message.
The tables in this section hold the codes every scraper and the platform can give, and those of finding and
fetching a careers page. Codes that belong to one family of scrapers — LinkedIn's refusals, what a blocked
web.fetch looks like, how a careers record was obtained — are in
Reasons by scraper family.
The target needs something we do not do#
| Reason | Status | What happened | What to do |
|---|---|---|---|
render_required | unsupported | The page, or the whole board, shows its content only after running JavaScript. Nothing could be read without a render. Dayforce boards always end this way. | Do not retry. If the company's jobs are also on a board we read, run ats.board with that board's address. |
render_required | partial | Some pages needed a render and were skipped; the other pages gave the records you have. | Use the records, knowing the list may be incomplete. Do not retry expecting more. |
unknown_board | unsupported | ats.board only: the address is not a board of an applicant tracking system we recognise. No request was made to it. | Check that the address is the board's own listing page. For a company's own careers site, use careers.company instead. |
The run was stopped#
| Reason | Status | What happened | What to do |
|---|---|---|---|
cancelled | cancelled | You cancelled the run and it stopped. Records found before the stop are kept and readable; nothing is charged. | Nothing. Start a new run if you want the full result. |
deadline_exceeded | partial or failed | The run reached its time limit of 5 minutes. partial keeps the records read before then. | Use the records you have, or run again with a smaller max_detail_pages so that fewer posting pages are read. |
process_restart | failed | Our service restarted while the run was queued or running. The run was not resumed. | Start the run again. |
The target could not be read#
| Reason | Status | What happened | What to do |
|---|---|---|---|
no_careers_page | failed | careers.company: no careers page was found. Either the site did not answer, or it links to no page we recognise as careers. | Check the domain. If you know the careers page, pass it as careers_url. |
careers_page_dead_url | failed | The careers page you gave does not exist (the site answered "not found" or similar). | Fix the address, or pass the domain and let the scraper look for the page. |
careers_page_target_blocked | failed | The site refused our request for the careers page you gave. | Retrying soon rarely helps. Try the company's ATS board with ats.board if it has one. |
careers_page_timeout | failed | The careers page you gave did not answer in time. Already retried once. | Try again later. |
careers_page_network | failed | A network error on the way to the careers page you gave. Already retried once. | Try again later. |
adapter_failed | failed | The applicant tracking system was recognised, but every feed we tried on it returned an error. A board that does not exist ends this way. diagnostics.facts.ats names the system. | Check that the board still exists; if it does, try again later. |
private_address_refused | failed or partial | The site's name led to an address that is not on the public internet. We do not connect to such addresses. partial keeps what was read elsewhere. | Check the domain. Retrying gives the same answer. |
fetch_failed | failed | We could not fetch the target, and the failure was on our side of the connection rather than the site's. Already retried once. Reported as a failure rather than as "no openings". | Try again later. If it keeps happening, send us the run id. |
careers_page_ is followed by the kind of fetch outcome. The four above are the ones a run can produce today;
treat any other careers_page_… code as "the careers page you gave could not be read".
We could not do it, or something went wrong on our side#
| Reason | Status | What happened | What to do |
|---|---|---|---|
temporarily_unavailable | failed, unsupported or partial | The service could not fetch the target, or part of it, at the moment. partial keeps the records that were read. | Try again later — also when the status is unsupported. If it keeps happening, send us the run id. |
internal_error | failed or unsupported | A fault or a safety check on our side. The result, if there was one, was not returned. | Nothing you did. Try once more; if it repeats, send us the run id. |
scraper_error | failed | The scraper stopped with an unexpected error. | Try once more. If it repeats, send us the run id. |
contract_error | failed | The scraper returned something the platform could not accept. | Send us the run id. |
error | failed | An unexpected error while working on the target. | Try once more. If it repeats, send us the run id. |
crawl_failed | failed | The run ended without producing a result for the target. | Try once more. If it repeats, send us the run id. |
A run that ended this way, as the API returned it:
{
"id": "run_7f1acf070c6d54392a95e3e9",
"scraper_id": "careers.company",
"scraper_version": 1,
"status": "unsupported",
"reason": "temporarily_unavailable",
"input": {
"domain": "example.com"
},
"record_count": 0,
"units": 0,
"diagnostics": {
"requests": 0,
"bytes": 0,
"wall_ms": 697,
"facts": {
"discovery": "none",
"pages_read": 0,
"renders_refused": 0
}
},
"created_at": "2026-11-16T20:27:30.032722Z",
"started_at": "2026-11-16T20:27:30.035206Z",
"finished_at": "2026-11-16T20:27:30.734390Z"
}Codes you have not seen#
New scrapers bring new reasons. Write your code so that an unknown reason falls back on the status:
partialwith an unknown reason — use the records, expect gaps.failedwith an unknown reason — retry later, a limited number of times.unsupportedwith an unknown reason — do not retry.
Reasons by scraper family#
The codes above are shared by every scraper, or belong to how the careers scrapers find and fetch a careers page. The codes below belong to one family of scrapers. Each scraper's page links to its family here.
Careers and job boards#
careers.company and ats.board. Every record they return says how it was obtained, in its extraction field:
extraction | The record came from | How far to trust it |
|---|---|---|
ats | The feed or board of an applicant tracking system we recognise. The record's ats field names the system. | It is the employer's own list of openings. |
page | The company's own web pages, read by us. The record's ats field is generic. | Unverified. It may be a page that is not a job posting. |
Two reasons follow from it:
| Reason | Status | What happened | What to do |
|---|---|---|---|
unverified_page_extraction | partial | There are records, and every one of them is a page record: none came from an applicant tracking system. In our own checks, results read entirely off pages were wrong often enough that they are not reported as a plain ok. | Use the records knowing that some may not be postings; page_url shows where each was read. If the company has a board on an applicant tracking system, run ats.board on it. |
no_postings_recognised | failed | Records were read off the company's pages, and every one was evidently not a job posting — a department heading, a handbook or product page, a list of search results — so all were dropped. This is not reported as "no openings": we could not tell. | If you know the careers page, pass it as careers_url; if the company has a board, run ats.board on it. |
A run with at least one ats record ends ok, with each record still carrying its own extraction. A known gap is
reported first: a run that also skipped pages needing a JavaScript render ends partial with render_required, not
with unverified_page_extraction. partial is charged and failed is not — see Usage and units.
LinkedIn#
linkedin.jobs_search, linkedin.job and linkedin.company read LinkedIn's public pages as a visitor who is not
signed in sees them. When LinkedIn does not answer with the page, the run says which way it went. linkedin.jobs_search
reads several pages: a refusal after the first ends the run partial with the postings read before it.
| Reason | Status | What happened | What to do |
|---|---|---|---|
blocked | failed or partial | LinkedIn refused the request, with a 403, a 999 or a challenge page. | Try again later. |
rate_limited | failed or partial | LinkedIn answered "too many requests" (429). | Try again later. |
auth_wall | failed or partial | LinkedIn answered with its sign-in page instead of the public page. We do not sign in. | Try again later. If it repeats for one page, that page is not shown to visitors who are not signed in. |
not_found | failed | linkedin.job, linkedin.company: LinkedIn says the posting or the company page does not exist. | Check the address or the id. Retrying gives the same answer. |
unexpected_page | failed or partial | The answer was neither the page that was asked for nor a refusal we recognise. | Try once more. If it repeats, send us the run id. |
unexpected_status | failed or partial | LinkedIn answered with an HTTP status the page does not normally give. diagnostics.facts.http_status carries it. | Try once more. If it repeats, send us the run id. |
An empty search is ok with zero records only when LinkedIn answered with its own empty result page.
diagnostics.facts of a LinkedIn run can include:
| Fact | Meaning |
|---|---|
pages_read | linkedin.jobs_search: result pages read. |
stop | linkedin.jobs_search: why the search stopped — limit (max_results was reached), end or empty (LinkedIn had no more results), repeating (LinkedIn kept returning postings already seen) or last_page (LinkedIn's last page for any search). |
cards_without_title | linkedin.jobs_search: results left out because they carried no title. Present only when there were any. |
job_id | linkedin.job: the posting's id. |
slug | linkedin.company: the company page's name in its address. |
Web#
web.fetch makes one GET request and returns what the server sent. Two cases are easy to confuse:
- The site's own answer is a successful fetch, whatever its status. A page the site answers with
404or500is the page you asked for: the run endsokwith one record whosestatusis404or500, and it is charged. - A site refusing the request is a failed run. There is no record,
record_countandunitsare0, andreasonsays how it was refused:
| Reason | Status | What happened | What to do |
|---|---|---|---|
blocked | failed | The site refused the request: a 403, a 999, or a challenge page with any status. diagnostics.facts.http_status carries the status. A 403 the site would give any visitor cannot be told from one it gives us, so every 403 ends this way. | Retrying soon rarely helps. |
rate_limited | failed | The site answered "too many requests" (429). | Try again later. |
captcha | failed | The site answered with a CAPTCHA instead of the page. We do not solve CAPTCHAs. | Retrying soon rarely helps. |
timeout | failed | No complete answer within timeout_s. | Try again, with a larger timeout_s if the site is slow (120 at most). |
network_error | failed | The connection to the site failed. | Try again later. |
dns_failed | failed | The host name does not resolve. | Check the address. |
web.fetch can also end with private_address_refused,
temporarily_unavailable, cancelled and
deadline_exceeded, as described above. A run that follows more than 5 redirects, or is led by a redirect to an
address that may not be fetched, ends failed with internal_error today; send "follow_redirects": false to get
the redirect itself as the record.
What web.fetch does not do: it sends no method other than GET, runs no JavaScript, and cuts the body after
max_bytes (2,000,000 by default) — the record's truncated says when it did. See
Limits and How we fetch.
A decision in code#
RETRY_LATER = {
"fetch_failed", "temporarily_unavailable", "process_restart", "internal_error", "scraper_error", "error",
"crawl_failed", "careers_page_timeout", "careers_page_network", "adapter_failed",
"rate_limited", "timeout", "network_error", "unexpected_page", "unexpected_status",
}
REFUSED_BY_SITE = {"blocked", "captcha", "auth_wall"}
def handle(run: dict) -> str:
status, reason = run["status"], run["reason"]
if status == "ok":
return "use" # complete, even when record_count is 0
if status == "partial":
return "use-with-gaps" # records are real; `reason` says what is missing
if status == "cancelled":
return "stop" # you stopped it; what it had found is still readable
if status in ("failed", "unsupported"):
if reason in RETRY_LATER:
return "retry-later" # a limited number of times
if reason in REFUSED_BY_SITE:
return "stop" # the site refused us: retrying soon rarely helps
if status == "unsupported":
return "stop" # render_required, unknown_board: the answer will not change
return "fix-input" # no_careers_page, careers_page_dead_url, not_found, dns_failed, …
return "still-running" # queued, runningDiagnostics#
A finished run carries diagnostics: what the run did, for when you need to understand a result. It is null
until the run ends, and stays null for a run that ended before the scraper reported anything (a run cancelled
while queued, a process_restart).
| Field | Meaning |
|---|---|
requests | Requests the run made, in total. |
bytes | Bytes fetched. null when they were not measured — never a made-up 0. |
wall_ms | How long the run took, in milliseconds. |
facts | What the scraper learned about the target — see below. A fact that is not known is left out. |
For the careers scrapers, facts can include:
| Fact | Meaning |
|---|---|
careers_url | The careers page, or board, that was read. |
discovery | How that page was found: supplied (you gave it), homepage_link, path_guess, or none. |
ats | The applicant tracking system detected, such as greenhouse. generic means the page itself was parsed. |
pages_read | Pages fetched successfully. |
renders_refused | Fetches that needed a JavaScript render and were not made. |
private_addresses_refused | Connections not made because the address was not on the public internet. Present only when there were any. |
The diagnostics of the ok run above:
{
"requests": 1,
"bytes": 232779,
"wall_ms": 565,
"facts": {
"careers_url": "https://boards.greenhouse.io/acme",
"discovery": "supplied",
"ats": "greenhouse",
"pages_read": 1,
"renders_refused": 0
}
}Other scrapers add facts of their own: those of the LinkedIn scrapers are listed under LinkedIn, and a
refused web.fetch carries the site's HTTP status in http_status. diagnostics is for understanding a result —
build your logic on status, reason and the records.