Job lifecycle

Job types and endpointsCopy Anchor Link

The lists need project_id. The setup and the scraping lists also accept website_id. Each list shows the newest jobs first. limit sets the number of jobs, from 1 to 100, and the default is 20.

POST /jobs/{job_id}/cancel cancels a job of any type.

StatusesCopy Anchor Link

Each job type goes through its own statuses.

Setup jobsCopy Anchor Link

CREATED → ANALYZING → ESTIMATE_READY → TRAINING → COMPLETED

The analysis and the training move the job forward without action from you. A setup job can skip ANALYZING or TRAINING when DeepScout already knows the website. See Add a website.

Scrape and matching jobsCopy Anchor Link

AWAITING_APPROVAL → APPROVED → RUNNING → SETTLING → EXPORTING → COMPLETED

A free matching sample has a zero estimate. It starts without your approval.

End statusesCopy Anchor Link

COMPLETED, FAILED and CANCELLED are end statuses. A job in an end status does not change again. finished_at shows when it got there.

• FAILED can end a job of any type. See Failed jobs.
• CANCELLED ends a job that you cancelled, a quote that did not change for 7 days, or the waiting jobs of a removed website.

Common fieldsCopy Anchor Link

All job responses have these fields. A field without a value is not in the response.

Website stateCopy Anchor Link

GET /websites shows each website with one job: the newer of its setup job and its newest full scrape that is not cancelled. URL scrapes do not change it. The console shows the state of the website from this job:

The website also has scraped_at, the end of its last completed scrape, and added_at, the start of its setup.

PollingCopy Anchor Link

The API has no webhooks yet. To follow a job, read it again at an interval:

Stop when the job is in an end status, or in AWAITING_APPROVAL, which waits for you.

To follow all websites of a project with one request, read GET /websites. For the scrape jobs of one website, read GET /jobs/scraping with website_id.

Cancel a jobCopy Anchor Link

Send POST /jobs/{job_id}/cancel. You can cancel:

• A setup job before it is complete. You do not get the analysis back.
• A scrape or a matching that waits for approval (AWAITING_APPROVAL). This removes the quote.

You cannot cancel a paid job after its approval, or a free matching sample. The API then answers 409 JOB_NOT_CANCELLABLE.

A quote that you do not approve for 7 days changes to CANCELLED.

Failed jobsCopy Anchor Link

A failed job has an error text, an error_code and a contact_reason.

A failed paid job costs nothing. To ask for help, send POST /contact-requests:

{
  "reason": "JOB_FAILED",
  "job_id": "jobreq_01k7d0f1g2h3j4k5m6n7p8q9r0",
  "phone": "+420 123 456 789",
  "message": "The scrape failed two times."
}

• reason must be the contact_reason of the job. If not, the API answers 409 CONTACT_REASON_MISMATCH.
• phone is optional, with 6 to 20 digits. Without it, the team writes to the email of your account.
• message is optional, up to 2,000 characters.

The API answers 201 Created. A second request about the same job returns the first request with 200 OK. After the request, the job shows its contact_request_id.

Email notificationsCopy Anchor Link

DeepScout sends an email to the user who started the job:

There are no emails for quotes, cancellations or top-ups.