--- title: "Request cancellation of a durable job" method: DELETE path: "/job/{jobId}" tags: ["Jobs"] --- # Request cancellation of a durable job `DELETE /job/{jobId}` ## Request - Base URL: `https://api.domscout.io` - URL: `https://api.domscout.io/job/{jobId}` - Auth: API key in header `x-api-key` Cancellation is cooperative. Work already running may finish, while unstarted children are cancelled without consuming page quota. **Work already in flight is still charged.** A capture is claimed by its worker within about a second of submission, so a cancellation for a single capture almost always arrives after the browser has started and that capture is billed as a completed one; the credit is not refunded. What cancellation saves is the unstarted remainder — for a batch or crawl, every child that had not yet been claimed. Read the response's counts rather than assuming a cancelled job cost nothing, and treat `GET /credits` as authoritative for what was actually spent. ## Response `200` The job was already terminal or cancellation completed. - JobStatus - `status` 'pending' | 'processing' | 'retrying' | 'done' | 'error' | 'cancel_requested' | 'cancelled', required - `jobId` string, uuid, required - `createdAt` string, date-time - `startedAt` string, date-time, nullable - `doneAt` string, date-time, nullable - `completedAt` string, date-time, nullable - `message` string - `result` ScreenshotResponse - `status` 'success', required - `metadata` ScreenshotMetadata - `url` string, nullable - `format` string - `httpStatus` integer, nullable - `viewport` Viewport - `width` integer, required - `height` integer, required - `isMobile` boolean - `deviceScaleFactor` number - `durationMs` integer - `timing` object - `totalMs` integer - `navigationMs` integer - `actionMs` integer - `render` object: Applied render controls and any non-fatal render warnings. - `captureId` string, uuid - `saved` boolean - `retentionDays` 7 | 30 | 90 | 365: Effective retention selected for a successful save. - `captureExpiresAt` string, date-time: Effective expiry time for a successful saved capture. - `partialResult` boolean - `framesCompleted` integer - `actionsRemaining` integer - `budgetWarning` string: Present when the action budget was exhausted and remaining steps were skipped. The budget is 24s on the synchronous path and 52s for async, monitor, batch-child and crawl-child work, and the message states the one that applied. - `syncTip` string - `warning` string: Primary non-fatal capture warning. Values include network_idle_timeout, navigation_aborted_after_document_load, access_challenge, and hide_selector_invalid (a hideSelectors entry was not valid CSS and was skipped). - `warningDetail` string - `warnings` object[]: All non-fatal capture warnings in detection order. The scalar warning and warningDetail fields retain the primary warning for backward compatibility. - `code` string, required - `detail` string, required - `accessChallenge` object: Present when the rendered document strongly resembles a target-side access or anti-bot verification page. Detection is advisory and the artifact is still returned. - `detected` boolean, required - `provider` string, nullable - `signals` string[], required - `ignoredFields` string[]: Top-level request fields this API does not understand, echoed back so a misspelled option is visible. Unknown fields remain accepted and ignored so that existing requests stay valid — but an ignored option changes both what you receive and what you are charged, so it is named here. Absent when every field was recognised. - `forceState` ForceStateResult[]: One entry per forceState requested, reporting whether it was applied. Present only when forceState was sent. An identical-looking capture with applied:false and reason SELECTOR_NOT_MATCHED means the element was never found. - `selector` string - `state` string - `applied` boolean - `matched` integer: How many elements the selector matched. Present when applied. - `note` string: Present when the selector matched more than one element. - `reason` 'SELECTOR_NOT_MATCHED' | 'STATE_NOT_APPLIED': Why it was not applied. SELECTOR_NOT_MATCHED means the page has no such element. - `error` string: Redacted browser error, when one was raised. - `credits` CaptureCredits: What this request cost and what is left. Present on billable JSON responses only. - `cost` integer: Credits this request consumed. - `chargedTo` string: Which bucket paid. - `remaining` integer, nullable - `quotaRemaining` integer, nullable - `overage` boolean: True when the paying bucket was beyond the plan's included quota and therefore metered. - `screenshotBase64` string, byte - `pdfBase64` string, byte - `mobileBase64` string, byte - `tabletBase64` string, byte - `desktopBase64` string, byte - `skeletonBase64` string, byte - `hydratedBase64` string, byte - `timelineBase64` string[] - `markdown` string - `markdownMeta` MarkdownMetadata - `title` string - `description` string - `finalUrl` string - `wordCount` integer - `charCount` integer - `estimatedTokens` integer - `contentQuality` 'ok' | 'likely_blocked' | 'empty' | 'low_text' | 'too_large': Heuristic extraction quality: empty means zero extracted words; low_text means 1-149 words. Callers must still detect target-side blocks and interstitials. - `ogTitle` string: og:title, empty when the page declares none. - `ogDescription` string: og:description, empty when the page declares none. - `ogImage` string: Absolute og:image URL, empty when the page declares none. - `links` ExtractedLink[] - `text` string, required - `href` string, required - `interactiveNodes` InteractiveNode[]: Legacy interactive-node summary. - `id` union - integer - string - `type` string: The element's tag name. - `role` string, nullable: The declared role, or the implicit one resolved from the tag (button, link, checkbox, radio, combobox, textbox). - `roleSource` 'explicit' | 'implicit' | 'null', nullable: Whether the page declared the role or it was resolved from the tag. - `text` string: The accessible name, truncated to 120 characters. - `nameSource` 'text' | 'aria-label' | 'aria-labelledby' | 'value' | 'title' | 'placeholder' | 'alt' | 'null', nullable: Where the name came from. An empty name with a null source is a genuinely unlabelled control — an accessibility defect on the page. - `disabled` boolean: Disabled by the attribute or by aria-disabled. - `expanded` boolean, nullable: aria-expanded, or null when the element does not declare it. - `pressed` boolean, nullable: aria-pressed, or null when the element does not declare it. - `placeholder` string, nullable - `href` string, nullable - `selector` string - `box` BoundingBox - `x` number, required - `y` number, required - `width` number, required - `height` number, required - `viewportX` number - `viewportY` number - `screenshotX` number - `screenshotY` number - `screenshotWidth` number - `screenshotHeight` number - `normalizedX` number - `normalizedY` number - `normalizedWidth` number - `normalizedHeight` number - `simplifiedDom` string - `performanceMetrics` PerformanceMetrics - `fcp` number - `lcp` number - `ttfb` number - `cls` number - `actionResults` ActionResult[] - `index` integer, required - `action` string, required - `status` 'passed' | 'failed' | 'skipped', required - `durationMs` integer, required - `tabId` string - `target` string, nullable - `code` string - `error` string - `details` unknown - `tabs` string[]: IDs of tabs that remain open after the action sequence. - `analysis` Analysis: Structured rich analysis is available on every JSON response mode, including grid and skeleton captures. - `semanticSnapshot` union - SemanticSnapshot - `version` integer, required: Versioned snapshot format identifier. - `generatedAt` string, date-time - `detail` 'summary' | 'full' - `document` SnapshotDocument - `title` string - `url` string - `viewport` SnapshotViewport - … - `nodes` SemanticNode[], required - `id` string, required: Per-snapshot evidence ID. It is not a cross-request action locator. - `stableKey` string: Node identity based on persistent identifiers or structural position, independent of mutable text and accessible names. - `tag` string, required - `role` string, nullable - `accessibleName` string - `text` string - `attributes` object: Allowed, non-sensitive attributes only. - `form` FormState: Form-control state. Field values are intentionally omitted and valueRedacted is true when a control value existed. - … - `parentId` string, nullable - `childIds` string[] - `visible` boolean, required - `inViewport` boolean - `box` BoundingBox, required - … - `screenshotBox` BoundingBox - … - `normalizedBox` BoundingBox - … - `normalizedScreenshotBox` NormalizedCoordinateBox - … - `viewportIntersection` ViewportIntersection - … - `zIndex` integer, nullable - `clickable` boolean - `obscuredBy` string, nullable: A redacted description of the element returned by elementFromPoint, when safe to report. - `selectorBundles` SelectorCandidate[], required - … - `iframe` IframeNodeMetadata, nullable - … - `frames` FrameMetadata[], required - `url` string, required - `name` string, nullable - `sameOrigin` boolean, required - `accessible` boolean, required - `truncated` boolean - object - `beforeActions` SemanticSnapshot - `version` integer, required: Versioned snapshot format identifier. - `generatedAt` string, date-time - `detail` 'summary' | 'full' - `document` SnapshotDocument - … - `nodes` SemanticNode[], required - … - `frames` FrameMetadata[], required - … - `truncated` boolean - `afterActions` SemanticSnapshot - `version` integer, required: Versioned snapshot format identifier. - `generatedAt` string, date-time - `detail` 'summary' | 'full' - `document` SnapshotDocument - … - `nodes` SemanticNode[], required - … - `frames` FrameMetadata[], required - … - `truncated` boolean - `diagnostics` Diagnostics: Bounded, redacted HAR-like diagnostics. It deliberately omits cookies, authorization, form values, and request/response bodies. - `console` ConsoleEvent[] - `type` string - `text` string - `at` string, date-time - `pageErrors` PageError[] - `message` string - `at` string, date-time - `failedRequests` FailedRequest[] - `url` string - `method` string - `resourceType` string - `error` string - `responses` NetworkResponse[] - `url` string - `method` string - `status` integer - `resourceType` string - `fromCache` boolean - `redirects` Redirect[] - `from` string - `to` string - `status` integer - `resources` ResourceTiming[] - `name` string - `initiatorType` string - `duration` number - `transferSize` integer - `encodedBodySize` integer - `decodedBodySize` integer - `summary` DiagnosticsSummary - `consoleCount` integer - `pageErrorCount` integer - `failedRequestCount` integer - `responseCount` integer - `resourceCount` integer - `thirdPartyDomains` string[] - `transferBytes` integer - `truncated` boolean - `truncated` boolean - `extraction` ExtractionResult - `fields` object, required - `cleanup` CleanupReport - `removed` integer - `categories` object - `probe` boolean - `loadTimeMs` integer - `bodyTextLength` integer - `estimate` ProbeEstimate - `remainingBudgetMs` integer - `safeScrollActions` integer - `safeClickActions` integer - `safeTypeActionsAt20Chars` integer - `warning` string, nullable - `error` union - string - JobError - `code` string, required - `message` string, required - `code` string - `suggestions` string[] - `recovered` boolean - `cancellationRequestedAt` string, date-time, nullable - `accepted` boolean: Present on a successful cooperative cancellation response. ## Other responses - `202`: Cancellation was requested and will be observed by the worker. - `403`: The request was refused. Returned when the x-api-key header is missing, revoked, or invalid, and when a valid key is blocked by a plan entitlement, the trusted-JavaScript account entitlement, a global product pause, or a security policy. A plan-only restriction returns code PLAN_FEATURE_UNAVAILABLE and can include upgrade_url. FEATURE_NOT_ENABLED identifies either the global product emergency pause or an eligible Business account without trusted-JavaScript permission; it carries no upgrade_url, so upgrading or retrying cannot clear it. Browser capture can return BROWSER_ISOLATION_REQUIRED or BROWSER_EXECUTION_DENIED with reason public_capture_not_enabled when browser work is unavailable for your account. These platform restrictions carry no upgrade_url and are not resolved by changing plan or key. Check GET /credits for current account capabilities. The API does not use 401: it authenticates with an API key header rather than an HTTP authentication scheme, so there is no WWW-Authenticate challenge to issue. - `404`: The resource does not exist, has expired, or is not owned by this API key. - `503`: A dependency this request needs is unavailable or not configured for this deployment. Codes: SUPABASE_TIMEOUT and SUPABASE_INVALID_RESPONSE (a storage operation did not answer, or answered unreadably — the write may have committed, so any retry must be idempotent), CAPTURE_ARTIFACT_UNAVAILABLE and CAPTURE_ARTIFACT_CORRUPT (a stored artifact could not be read or parsed), ASYNC_JOBS_NOT_CONFIGURED and CAPTURE_RETRIEVAL_NOT_CONFIGURED (the capability is not configured here, on any plan). Retryable unless the code names a deployment configuration. --- [API](https://skmtc.dev/domscout/apis/domscout-api.md) · [All operations](https://skmtc.dev/domscout/apis/domscout-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domscout/apis/domscout-api/revisions/20562d5b5d94?raw)