Skip to the content
EnrichedNowDocs

    Type to search every page.

    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.

    StatusFinalRecordsChargedMeaning
    queuedNo——Accepted and waiting for a worker.
    runningNo——Being executed now.
    okYesZero or moreYesThe target was read. Zero records means there was nothing to find.
    partialYesOne or moreYesRecords were found, but something stopped the run from reading everything. reason says what.
    failedYesNoneNoThe run could not read the target. reason says why.
    unsupportedYesNoneNoThe target needs something we do not do. reason says what.
    cancelledYesZero or moreNoYou 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:

    200 · JSON
    {
      "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 blocked or rate_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.

    200 · JSON
    {
      "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.

    200 · JSON
    {
      "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#

    ReasonStatusWhat happenedWhat to do
    render_requiredunsupportedThe 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_requiredpartialSome 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_boardunsupportedats.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#

    ReasonStatusWhat happenedWhat to do
    cancelledcancelledYou 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_exceededpartial or failedThe 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_restartfailedOur service restarted while the run was queued or running. The run was not resumed.Start the run again.

    The target could not be read#

    ReasonStatusWhat happenedWhat to do
    no_careers_pagefailedcareers.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_urlfailedThe 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_blockedfailedThe 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_timeoutfailedThe careers page you gave did not answer in time. Already retried once.Try again later.
    careers_page_networkfailedA network error on the way to the careers page you gave. Already retried once.Try again later.
    adapter_failedfailedThe 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_refusedfailed or partialThe 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_failedfailedWe 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#

    ReasonStatusWhat happenedWhat to do
    temporarily_unavailablefailed, unsupported or partialThe 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_errorfailed or unsupportedA 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_errorfailedThe scraper stopped with an unexpected error.Try once more. If it repeats, send us the run id.
    contract_errorfailedThe scraper returned something the platform could not accept.Send us the run id.
    errorfailedAn unexpected error while working on the target.Try once more. If it repeats, send us the run id.
    crawl_failedfailedThe 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:

    200 · JSON
    {
      "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:

    • partial with an unknown reason — use the records, expect gaps.
    • failed with an unknown reason — retry later, a limited number of times.
    • unsupported with 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:

    extractionThe record came fromHow far to trust it
    atsThe 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.
    pageThe 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:

    ReasonStatusWhat happenedWhat to do
    unverified_page_extractionpartialThere 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_recognisedfailedRecords 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.

    ReasonStatusWhat happenedWhat to do
    blockedfailed or partialLinkedIn refused the request, with a 403, a 999 or a challenge page.Try again later.
    rate_limitedfailed or partialLinkedIn answered "too many requests" (429).Try again later.
    auth_wallfailed or partialLinkedIn 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_foundfailedlinkedin.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_pagefailed or partialThe 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_statusfailed or partialLinkedIn 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:

    FactMeaning
    pages_readlinkedin.jobs_search: result pages read.
    stoplinkedin.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_titlelinkedin.jobs_search: results left out because they carried no title. Present only when there were any.
    job_idlinkedin.job: the posting's id.
    sluglinkedin.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 404 or 500 is the page you asked for: the run ends ok with one record whose status is 404 or 500, and it is charged.
    • A site refusing the request is a failed run. There is no record, record_count and units are 0, and reason says how it was refused:
    ReasonStatusWhat happenedWhat to do
    blockedfailedThe 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_limitedfailedThe site answered "too many requests" (429).Try again later.
    captchafailedThe site answered with a CAPTCHA instead of the page. We do not solve CAPTCHAs.Retrying soon rarely helps.
    timeoutfailedNo complete answer within timeout_s.Try again, with a larger timeout_s if the site is slow (120 at most).
    network_errorfailedThe connection to the site failed.Try again later.
    dns_failedfailedThe 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#

    Python
    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, running

    Diagnostics#

    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).

    FieldMeaning
    requestsRequests the run made, in total.
    bytesBytes fetched. null when they were not measured — never a made-up 0.
    wall_msHow long the run took, in milliseconds.
    factsWhat the scraper learned about the target — see below. A fact that is not known is left out.

    For the careers scrapers, facts can include:

    FactMeaning
    careers_urlThe careers page, or board, that was read.
    discoveryHow that page was found: supplied (you gave it), homepage_link, path_guess, or none.
    atsThe applicant tracking system detected, such as greenhouse. generic means the page itself was parsed.
    pages_readPages fetched successfully.
    renders_refusedFetches that needed a JavaScript render and were not made.
    private_addresses_refusedConnections not made because the address was not on the public internet. Present only when there were any.

    The diagnostics of the ok run above:

    JSON
    {
      "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.