@hunt-labs/bytekit-sdk 0.9.3 → 0.11.0

package/dist/generated/api.d.ts

@@ -194,7 +194,17 @@ export interface paths {
         put?: never;
         /**
          * Scrape a URL
-         * @description Fetches and processes a URL, returning content in one or more formats wrapped in a ScrapeEnvelope. Most requests return synchronously in under a second; requests needing a full page render return HTTP 202 and complete asynchronously.
+         * @description Fetches and processes a URL, returning content in one or more formats wrapped in a ScrapeEnvelope.
+         *
+         *     **The response shape is decided by your request, not by how we route it.** In precedence order:
+         *
+         *     1. `async: true` → **202** with a `ScrapeQueuedEnvelope` receipt, returned immediately. Poll `GET /v1/scrape/{id}` for the result.
+         *     2. Otherwise, a request that needs a full page render — today that is `delay_ms > 0` — is **held open** until the render reaches a terminal state, then returns **200** with the content envelope (`success` or `failed`). If the render is still running when the hold window expires (28 seconds by default), the request returns the **202** receipt instead and the job continues in the background.
+         *     3. Otherwise the request is served by the fast HTTP path and returns **200** with the content envelope, typically in under a second.
+         *
+         *     **A failed fetch is a result, not a transport error.** An unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all come back on the same **200** as a `failed` envelope — never a 5xx. Narrow on the envelope's `status` before reading the body. A failure the fast path decides inline is recorded as a failed job, so its envelope normally carries that job's `id` and `GET /v1/scrape/{id}` returns the same envelope; if recording the failed job itself fails, the envelope still arrives on the same 200 with `id` set to `null` and there is nothing to poll. A failure a held render reaches carries that render's real `id`. Either way the request transfers no billable bytes and is charged nothing.
+         *
+         *     So a 202 means one of exactly two things: you asked for one with `async: true`, or the hold window expired. `wait_for_selector` and `wait_until` are `ScreenshotRequest` options, not `ScrapeRequest` options — sending either to this endpoint returns `422 validation_error`, so neither can produce a 202 here.
          */
         post: operations["createScrape"];
         delete?: never;
@@ -235,9 +245,10 @@ export interface paths {
         /**
          * Bulk scrape URLs
          * @description Enqueues multiple URLs for scraping. Results delivered via webhook.
-         *     Webhook deliveries include `X-ByteKit-Event: scrape.completed` or
-         *     `X-ByteKit-Event: scrape.failed` so receivers can dispatch on the
-         *     header without parsing the body shape.
+         *     Completion deliveries use `X-ByteKit-Event: bulk.completed` and the
+         *     `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
+         *     followed by cursor recovery through `GET /v1/scrape/bulk/{id}` whenever
+         *     `recovery_required` is true.
          */
         post: operations["createScrapeBulk"];
         delete?: never;
@@ -253,7 +264,20 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get scrape bulk job status */
+        /**
+         * Get scrape bulk job status
+         * @description Returns the job envelope plus its rehydrated per-URL scrape envelopes.
+         *
+         *     **Downloading item content.** A `raw` or `markdown` artifact within the
+         *     10-MiB inline cap is returned inline. An oversized one is replaced by a
+         *     **pre-signed** URL, minted fresh on every read of this endpoint and valid
+         *     for **86400 seconds (24 hours)**. The underlying objects are private, so an
+         *     unsigned URL returns `401`: download the content inside that window, or
+         *     re-poll this endpoint for a fresh signature. An artifact that was never
+         *     stored, or whose object cannot be signed, is omitted from `formats` and
+         *     reported as `artifact_unavailable` in `warnings`. The private unsigned
+         *     storage URL is never returned.
+         */
         get: operations["getScrapeBulk"];
         put?: never;
         post?: never;
@@ -305,6 +329,10 @@ export interface paths {
          * Bulk fetch URLs
          * @description Enqueues multiple URLs for HTTP fetching. Results delivered via webhook.
          *     Does not support options that require page rendering (wait_for_selector, etc.).
+         *     Completion deliveries use `X-ByteKit-Event: bulk.completed` and the
+         *     `BulkCompletedWebhook` contract: at most 500 complete items and 1 MiB,
+         *     followed by cursor recovery through `GET /v1/fetch/bulk/{id}` whenever
+         *     `recovery_required` is true.
          *
          *     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
          *     with no `Content-Length` header is capped at 2 MB before your API key
@@ -342,7 +370,9 @@ export interface paths {
          *     objects are private, so an unsigned URL returns `401`: download the
          *     content inside that window, or re-poll this endpoint for a fresh
          *     signature. Items that are not `completed`, and completed items with no
-         *     stored object, carry `null` or the unsigned stored URL instead.
+         *     stored object, or completed items whose object cannot be signed, carry
+         *     `null`; the latter report `artifact_unavailable`. The private unsigned
+         *     storage URL is never returned.
          */
         get: operations["getFetchBulk"];
         put?: never;
@@ -361,9 +391,13 @@ export interface paths {
             cookie?: never;
         };
         /**
-         * List in-flight bulk jobs
-         * @description Returns the caller's bulk jobs, most recent first. Optionally filter
-         *     to a single status; when omitted, jobs of every status are returned.
+         * List bulk jobs
+         * @description Returns the caller's bulk jobs, most recent first, one cursor-paginated
+         *     page at a time. Optionally filter to a single status; when omitted, jobs
+         *     of every status are returned. `status` narrows the set and the cursor
+         *     addresses a position inside that already-ordered, already-filtered set,
+         *     so the two can be combined in one request. Follow `next_cursor` while
+         *     `has_more` is true.
          */
         get: operations["listBulk"];
         put?: never;
@@ -373,6 +407,9 @@ export interface paths {
          *     Provide `urls` (simple list) or `items` (per-item config), not both.
          *     Webhook deliveries include `X-ByteKit-Event: bulk.completed` so
          *     receivers can dispatch on the header without parsing the body shape.
+         *     The body follows `BulkCompletedWebhook`: at most 500 complete items and
+         *     1 MiB, followed by cursor recovery through the existing mixed-item route
+         *     whenever `recovery_required` is true.
          *
          *     **Limits:** request bodies are guarded in a two-tier shape. A streamed body
          *     with no `Content-Length` header is capped at 4 MB before your API key
@@ -424,15 +461,25 @@ export interface paths {
          * List bulk job items
          * @description Returns the bulk job's items, discriminated by `type`.
          *
-         *     **Downloading item artifacts.** `image_url` (`type: screenshot`) and both
-         *     `content_url` and `markdown_url` (`type: scrape`) are **pre-signed** URLs,
-         *     minted fresh on every read of this endpoint and valid for **600 seconds
-         *     (10 minutes)** —
+         *     **Downloading item artifacts.** For a `completed` item with a storage key,
+         *     `image_url` (`type: screenshot`) and both `content_url` and `markdown_url`
+         *     (`type: scrape`) are **pre-signed** URLs, minted fresh on every read of
+         *     this endpoint and valid for **600 seconds (10 minutes)** —
          *     the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}`.
-         *     The underlying objects are private, so an unsigned URL returns `401`:
-         *     download inside that window, or re-poll this endpoint for a fresh
-         *     signature. Items that are not `completed`, and completed items with no
-         *     stored object, carry `null` or the unsigned stored URL instead.
+         *     Download inside that window, or re-poll this endpoint for a fresh
+         *     signature.
+         *
+         *     **When no signature is minted.** Three cases mint none: an item that is not
+         *     `completed`, a `completed` item with no storage key, and a `completed` item
+         *     whose object could not be signed — during an object-storage outage, for
+         *     instance. In all three the item's stored value is returned unchanged: `null`
+         *     while nothing has been stored, and otherwise a **private, unsigned**
+         *     object-storage URL that answers `401`. These fields are neither nulled nor
+         *     flagged in that case, so treat an artifact URL as usable only once you have
+         *     downloaded it, and re-poll for a fresh signature otherwise.
+         *     `artifact_warnings` and its `artifact_unavailable` code describe the sibling
+         *     `artifacts` object on `type: scrape` items only — they say nothing about
+         *     `image_url`, `content_url`, or `markdown_url`.
          */
         get: operations["listBulkScreenshots"];
         put?: never;
@@ -673,7 +720,7 @@ export interface paths {
         };
         /**
          * Get the unified request log feed
-         * @description Returns a unified, newest-first feed of the account's capture requests across scrape, fetch, screenshots, and recordings, for the dashboard /logs screen. Cursor-paginated; default range is the last 30 days, max 366 days.
+         * @description Returns a unified, newest-first feed of the account's requests across scrape, fetch, screenshots, recordings and search, plus webhook delivery attempts, for the dashboard /logs screen. Monitor runs are listed as the scrape and screenshots rows they produce (`source: monitor`). Cursor-paginated; default range is the last 30 days, max 366 days.
          */
         get: operations["getLogs"];
         put?: never;
@@ -752,11 +799,13 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * One-time bandwidth purchase
-         * @description Creates a hosted Stripe Checkout session for a bandwidth top-up and
-         *     returns its URL. The caller redirects the user to `checkout_url`; the
-         *     balance is credited asynchronously by the `payment_intent.succeeded`
-         *     webhook once payment completes.
+         * One-time dollar deposit
+         * @description Creates a hosted Stripe Checkout session for a deposit into the account's
+         *     USD balance and returns its URL. The caller redirects the user to
+         *     `checkout_url`; the balance is credited asynchronously by the
+         *     `payment_intent.succeeded` webhook once payment completes. The balance
+         *     never expires and pays for usage beyond the included allowance, for
+         *     bandwidth and search credits alike, at the plan's rate when it is used.
          */
         post: operations["createTopup"];
         delete?: never;
@@ -765,29 +814,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/billing/credit-topup": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * One-time credit purchase
-         * @description Creates a hosted Stripe Checkout session for a credit top-up and returns
-         *     its URL. The caller redirects the user to `checkout_url`; credits are
-         *     added asynchronously by the `payment_intent.succeeded` webhook once
-         *     payment completes.
-         */
-        post: operations["createCreditTopup"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/v1/billing/cancel": {
         parameters: {
             query?: never;
@@ -881,8 +907,9 @@ export interface paths {
         get?: never;
         /**
          * Configure auto-topup
-         * @description Enable or disable automatic bandwidth top-ups. When enabling,
-         *     threshold_bytes, amount_bytes, and monthly_cap_cents are all required.
+         * @description Enable or disable automatic top-ups of the USD balance. When enabling,
+         *     threshold_cents, amount_cents, and monthly_cap_cents must all be present;
+         *     monthly_cap_cents may be null, which means no monthly cap.
          */
         put: operations["updateAutoTopup"];
         post?: never;
@@ -1413,6 +1440,95 @@ export interface components {
                 details?: unknown;
             };
         };
+        /**
+         * @description Item-local terminal artifact failure. The item's stable id remains usable for paginated recovery, but the requested stored content or signed reference could not be produced. Wherever this code is raised the URL field it describes is `null`; a private object-storage URL is never returned as a substitute for it. Endpoints that do not raise this code document their own fallback — see `image_url` on `GET /v1/bulk/{id}/screenshots`.
+         *
+         *     REFERENCE DOCUMENTATION ONLY (#4340). No operation `$ref`s this schema and no response ever carries an object of this shape, so no client model is generated from it and no SDK re-exports it. On the wire the value appears as the FLAT `error_code` / `error_message` fields on a bulk list item — `GET /v1/fetch/bulk/{id}`, `GET /v1/bulk/{id}/screenshots` — and on the `items[]` entries of the `bulk.completed` webhook body, never as a nested `{ code, message }` object. This schema names the `artifact_unavailable` code and the contract that goes with it; the two properties below describe that code and message, not a wire envelope.
+         */
+        BulkArtifactUnavailableError: {
+            /** @enum {string} */
+            code: "artifact_unavailable";
+            message: string;
+        };
+        /** @description Mandatory bounded scrape record emitted when the ordinary rehydrated envelope cannot fit within the 16-MiB page bound. The stable item identity and terminal outcome always remain available; bounded signed references and failure detail are included when they fit. */
+        BulkMandatoryScrapeItem: {
+            id: string;
+            /** @enum {string} */
+            type: "scrape";
+            /** @enum {string} */
+            terminal_outcome: "pending" | "processing" | "completed" | "failed" | "cancelled";
+            /** Format: uri */
+            url: string;
+            /** @description Bounded signed references retained from the ordinary scrape envelope. Only the formats the job requested are present; the key set is the `/v1/scrape` format vocabulary. */
+            formats?: {
+                raw?: string | null;
+                markdown?: string | null;
+                links?: null | (string | components["schemas"]["ScrapeScoredLink"])[];
+                images?: null | (string | components["schemas"]["ScrapeScoredImage"])[];
+            };
+            error?: {
+                code: string;
+                message: string | null;
+                /** Format: date-time */
+                failed_at: string | null;
+            };
+        };
+        /** @description Whole-job counters. These do not reset or shrink with the current page. */
+        BulkJobCounters: {
+            total: number;
+            completed: number;
+            failed: number;
+        };
+        /**
+         * @description Customer body for `X-ByteKit-Event: bulk.completed`. Delivery is bounded to
+         *     500 complete items and 1 MiB of customer-visible JSON, stopping only between
+         *     items. When either item coverage or artifact coverage is incomplete, follow
+         *     `recovery_url` with cursor pagination; stable `bulk_id` plus each item `id`
+         *     supports idempotent processing after duplicate, delayed, or retried delivery.
+         */
+        BulkCompletedWebhook: {
+            bulk_id: string;
+            /** @enum {string} */
+            status: "completed";
+            total: number;
+            completed: number;
+            failed: number;
+            total_credits_charged: number;
+            /** Format: uri */
+            webhook_url: string;
+            /** @description Complete item records included before the 500-item or 1-MiB manifest bound. Every record carries a stable `id`, a `type`, and a terminal `status`. */
+            items: ({
+                /** @description Stable prefixed item id; deduplicate with `bulk_id` plus this id. */
+                id: string;
+                /** @enum {string} */
+                type: "fetch" | "scrape" | "screenshot" | "recording";
+                /** @enum {string} */
+                status: "success" | "completed" | "failed" | "cancelled";
+                /** @description May be `artifact_unavailable` when no usable result reference exists. */
+                error_code?: string | null;
+                error_message?: string | null;
+                /** @description Present and true when the manifest bounded a long error message. */
+                error_message_truncated?: boolean;
+            } & {
+                [key: string]: unknown;
+            })[];
+            /** @enum {string} */
+            recovery_api: "fetch" | "scrape" | "mixed";
+            /**
+             * @description Existing paginated result-recovery path for this job.
+             * @example /v1/fetch/bulk/bulk_01j9abc123
+             */
+            recovery_url: string;
+            manifest_item_count: number;
+            /** @description True when every terminal job item is present in this webhook body. */
+            manifest_items_complete: boolean;
+            /** @description True when every included completed item has a usable artifact or reference. */
+            manifest_artifacts_complete: boolean;
+            /** @description True only when both item and artifact coverage are complete. */
+            manifest_complete: boolean;
+            /** @description Inverse of `manifest_complete`; follow `recovery_url` when true. */
+            recovery_required: boolean;
+        };
         Viewport: {
             width: number;
             height: number;
@@ -1535,11 +1651,17 @@ export interface components {
             formats: ("raw" | "markdown" | "links" | "images")[];
             /** @default US */
             country: string;
-            /** @default 0 */
+            /**
+             * @description Milliseconds to wait after page load before capturing, for content that renders late. Any value above 0 puts the request on the full browser render path. Unless `async: true` is also set, the request is then HELD until the render finishes and returns 200 with the content envelope, or returns the 202 receipt if the hold window expires first. `0` (the default) keeps the request on the fast HTTP path, which returns 200 in one round trip.
+             * @default 0
+             */
             delay_ms: number;
             /** @default 30000 */
             timeout_ms: number;
-            /** @default false */
+            /**
+             * @description When true, the request returns 202 with a `ScrapeQueuedEnvelope` receipt immediately and the scrape runs in the background; poll `GET /v1/scrape/{id}` for the result. This is the only way to ASK for a receipt, and it outranks every routing consequence: with `async: false` (the default) a browser-path request is held to completion instead of being receipted. A 202 can still arrive with `async: false`, but only when the hold window expires.
+             * @default false
+             */
             async: boolean;
             /**
              * Format: uri
@@ -1599,6 +1721,11 @@ export interface components {
              * @default false
              */
             mobile: boolean;
+            /**
+             * @description Attempts to clear a Cloudflare challenge; success is not guaranteed. Billed as a normal browser render.
+             * @default false
+             */
+            solve_challenge: boolean;
             /**
              * @description When true (default), base64-encoded `data:` image sources are stripped from the HTML before markdown conversion. Set to false to preserve base64 images in the pipeline output. Does not affect `raw`, which always returns the original source unchanged.
              * @default true
@@ -1829,17 +1956,19 @@ export interface components {
              *     from a prior cache entry (billed at 0.5×). `miss` — no reusable entry was
              *     found, so the result was freshly fetched. `bypass` — `cache_ttl: '0'`
              *     skipped the read. Cache-eligible fresh results are written through;
-             *     safety-classified WAF husks remain live-only. Present on the async success
-             *     envelope (synchronous and webhook delivery); omitted by paths with no cache
-             *     verdict (e.g. bulk results).
+             *     safety-classified WAF husks remain live-only. Present on the synchronous
+             *     response, on webhook delivery, and on `GET /v1/scrape/{id}` for a row whose
+             *     terminal write recorded a disposition; omitted by paths with no cache verdict
+             *     (e.g. bulk results) and for a stored row that recorded none, where absent
+             *     means unknown rather than `miss`.
              * @enum {string}
              */
             cache?: "miss" | "hit" | "bypass";
-            /** @description Age in whole seconds of the cache entry replayed on a `hit`. Clamped to ≥ 0 to absorb clock skew. Present only on `cache: hit`. */
+            /** @description Age in whole seconds of the cache entry replayed on a `hit`. Clamped to ≥ 0 to absorb clock skew. Present only on `cache: hit`. `GET /v1/scrape/{id}` reports `cache: hit` without this field: the age is a property of the replay that happened at completion time, is not persisted on the row, and cannot be derived honestly afterwards. */
             cache_age_s?: number;
         };
         /**
-         * @description Terminal asynchronous scrape failures are delivered to subscribers of `failed` as this payload with `X-ByteKit-Event: scrape.failed`.
+         * @description The canonical terminal failure payload. It is returned inline on a `POST /v1/scrape` that fails upstream (HTTP 200, `id` naming the failed job it is recorded as, or `null` in the rare case that recording itself failed), by `GET /v1/scrape/{id}` once a queued job has failed, and delivered to subscribers of `failed` with `X-ByteKit-Event: scrape.failed`.
          * @example {
          *       "schema_version": 1,
          *       "status": "failed",
@@ -2166,7 +2295,7 @@ export interface components {
             options?: {
                 [key: string]: unknown;
             };
-            /** @description Scrape monitor options (formats, country, headers, etc.). Only for type=scrape. */
+            /** @description Scrape monitor options (formats, country, wait_for_selector, wait_until, delay_ms). Only for type=scrape. */
             scrape_options?: {
                 [key: string]: unknown;
             };
@@ -2530,8 +2659,8 @@ export interface components {
             };
             auto_topup: {
                 enabled: boolean;
-                threshold_bytes: number;
-                amount_bytes: number;
+                threshold_cents: number;
+                amount_cents: number;
                 monthly_cap_cents: number;
             };
             /** Format: date-time */
@@ -2544,7 +2673,7 @@ export interface components {
             /** Format: date-time */
             created_at: string;
         };
-        /** @description Minimal account shape returned by GET /v1/account when authenticated with a Clerk session JWT. Omits api_key, subscription, and auto_topup. */
+        /** @description Minimal account shape returned by GET /v1/account when authenticated with a Clerk session JWT. Omits api_key, subscription, and auto_topup; the single boolean `has_subscription` stands in for the bearer path's `subscription` object. */
         AccountSessionResponse: {
             id: string;
             email: string;
@@ -2577,6 +2706,42 @@ export interface components {
             created_at: string;
             /** @description True once the account has SUCCESSFULLY COMPLETED at least one billable request (a scrape/screenshot/fetch/… that settled and was charged credits), regardless of whether it was authenticated with a Clerk session or an API key. All-time — never windowed. A request that failed does not flip it, even when its bandwidth was billed: the monitor terminal-preflight-failure path records bytes without credits, and only the credited settlement counts here. Powers the dashboard onboarding gate — the app shows the guided onboarding flow until this is true, then the dashboard. Lags by up to one usage rollup: the completion service writes the row after the response is returned, so a just-completed first request may still read false for a moment. Treat that as "not visible yet", never as "this account has never made a request". */
             has_activity: boolean;
+            /** @description True when the account has a Stripe subscription, keyed on the same `stripe_subscription_id` column that GET /v1/billing/change-plan's `no_subscription` guard tests — so a client can use it to decide whether that endpoint will answer at all. Stays TRUE while a subscription is mid-cancellation (cancelled but running to the period end): the subscription still exists and a booked plan change is still revocable. It is a boolean, not the bearer path's `subscription` object: this response has no role-dependent fields, so a non-admin member receives it too, and plan pricing does not belong there. */
+            has_subscription: boolean;
+        };
+        /** @description Account shape returned by PATCH /v1/account. Identical to AccountSessionResponse except that it omits `has_activity`: the PATCH handler returns the shared session-account body unchanged and does not run the extra activity lookup that GET /v1/account layers on top of it (issue #4187). */
+        AccountPatchResponse: {
+            id: string;
+            email: string;
+            name: string | null;
+            plan: {
+                id: string;
+                slug: string;
+                name: string;
+                included_screenshots: number;
+                has_overage: boolean;
+                overage_price_cents: number | null;
+                max_concurrency: number;
+                rate_limit_per_sec: number;
+                max_bulk_size: number;
+                max_monitors: number;
+                retention_days: number;
+            };
+            /** @description Prefixed user id of the calling admin user. Null for non-admin members. */
+            owner_user_id: string | null;
+            /** @description Account notification preferences (bandwidth alerts). */
+            notifications: {
+                /** @description Whether the account admin wants an email when bandwidth reaches 80 % of the plan limit. */
+                bandwidth_80_enabled: boolean;
+                /** @description Whether the account admin wants an email when bandwidth reaches 100 % of the plan limit. */
+                bandwidth_100_enabled: boolean;
+            };
+            /** @description The Terms of Service version this account has accepted. An empty string means the account predates clickwrap acceptance (issue #1025). The dashboard diffs this against the published current version to decide whether to show the re-acceptance prompt. */
+            terms_version: string;
+            /** @description True when the account has a Stripe subscription, keyed on the same `stripe_subscription_id` column that GET /v1/billing/change-plan's `no_subscription` guard tests. */
+            has_subscription: boolean;
+            /** Format: date-time */
+            created_at: string;
         };
         /** @description Partial update payload for PATCH /v1/account. All fields are optional; at least one of name, email, or notifications must be provided. */
         PatchAccountRequest: {
@@ -2618,24 +2783,24 @@ export interface components {
             used_bytes: number;
             limit_bytes: number;
             remaining_bytes: number;
-            /** @description Total spendable bytes remaining across purchased top-up and starter-grant lots, after active refund reservations. */
+            /** @description Total spendable top-up bytes: the USD balance's current-plan estimate (`purchased_topup_bytes`) plus the starter grant. */
             topup_bytes: number;
-            /** @description Bytes remaining in purchased top-up lots, after active refund reservations. Starter-grant bytes are excluded. */
+            /** @description Estimate of the bytes the USD balance buys at the current plan's rate, after amounts held by open refunds. Not a separate balance: it changes when the plan changes. Starter-grant bytes are excluded. */
             purchased_topup_bytes: number;
-            /** @description Bytes remaining in starter-grant lots, after active refund reservations. Purchased top-up bytes are excluded. */
+            /** @description Bytes remaining in starter-grant lots, after active refund reservations. The USD balance estimate is excluded. */
             granted_topup_bytes: number;
-            /** @description Unspent subscription allowance carried over from earlier billing periods: bytes remaining in allowance lots granted before the current period started, after active refund reservations. While your plan tier is unchanged, earlier lots are drawn first, so carried-over allowance is spent before the current period's; after an upgrade, allowance acquired at the higher tier is drawn first. Value is spent in one order: your plan's included allowance, including any rollover from earlier periods, then purchased top-ups, then the one-time starter grant. */
+            /** @description Unspent subscription allowance carried over from earlier billing periods: bytes remaining in allowance lots granted before the current period started, after active refund reservations. While your plan tier is unchanged, earlier lots are drawn first, so carried-over allowance is spent before the current period's; after an upgrade, allowance acquired at the higher tier is drawn first. Value is spent in one order: your plan's included allowance, including any rollover from earlier periods, then the USD balance, then the one-time starter grant. */
             rollover_bytes: number;
         };
         CreditBalance: {
             used: number;
             limit: number;
             remaining: number;
-            /** @description Total spendable credits remaining across purchased top-up and starter-grant lots, after active refund reservations. */
+            /** @description Total spendable top-up credits: the USD balance's current-plan estimate (`purchased_topup_credits`) plus the starter grant. */
             topup_credits: number;
-            /** @description Credits remaining in purchased top-up lots, after active refund reservations. Starter-grant credits are excluded. */
+            /** @description Estimate of the credits the USD balance buys at the current plan's rate, after amounts held by open refunds. Not a separate balance: it changes when the plan changes. Starter-grant credits are excluded. */
             purchased_topup_credits: number;
-            /** @description Credits remaining in starter-grant lots, after active refund reservations. Purchased top-up credits are excluded. */
+            /** @description Credits remaining in starter-grant lots, after active refund reservations. The USD balance estimate is excluded. */
             granted_topup_credits: number;
             /** @description Always `0`. Search credits do not carry over between billing periods; the field is retained for contract stability and will not become non-zero without an announced plan change. */
             rollover_credits: number;
@@ -2906,7 +3071,7 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["Account"];
+                    "application/json": components["schemas"]["AccountPatchResponse"];
                 };
             };
             /** @description Missing or invalid Clerk JWT. */
@@ -3423,7 +3588,7 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Scrape completed synchronously. */
+            /** @description Scrape reached a terminal state and the body is that terminal envelope: `success` carrying content, or `failed` carrying the error envelope. Returned by the fast HTTP path in one round trip, and by a browser-path request without `async: true` once its render reaches a terminal state inside the hold window. A held render that ends in failure answers 200 with the same `failed` envelope `GET /v1/scrape/{id}` returns — narrow on `status` before reading the body. A definitive upstream outcome is a result, not a transport error: an unreachable host, a refused connection, or a target whose bot protection defeats every proxy tier all answer 200 with the `failed` envelope, never a 5xx. An inline failure is recorded as a failed job, so its envelope normally carries that job's `id` and polling it returns the same envelope; `id` is `null` only when recording the failed job itself failed. `error.http_status` is present only when a real upstream HTTP status is known. */
             200: {
                 headers: {
                     /** @description Stable scrape identifier (also present on the envelope as `id`). */
@@ -3476,7 +3641,7 @@ export interface operations {
                     "X-Scrape-Markdown-Length"?: number;
                     /** @description Legacy numeric form of the tier that served: 1 datacenter, 2 residential, 3 mobile. Omitted for the lean-browser tier, which has no numeric form. Deprecated — use X-Scrape-Proxy-Tier-Label. */
                     "X-Scrape-Proxy-Tier"?: number;
-                    /** @description The proxy tier that actually served this request's fetch, after any escalation — never the tier first attempted. One of datacenter, residential, mobile, lean. Diagnostic only: it is never an input to routing, billing, caching or escalation. Present on sync fast-path responses. Omitted on a cache hit, which replayed stored bytes and ran no tier, and on responses the fast path did not serve. */
+                    /** @description The proxy tier that actually served this request's fetch, after any escalation — never the tier first attempted. One of datacenter, residential, mobile, lean. Diagnostic only: it is never an input to routing, billing, caching or escalation. Present on sync fast-path responses. Omitted on a cache hit, which replayed stored bytes and ran no tier; and on responses the fast path did not serve. A third omission — a response replayed from stored bytes after this request's own cache lookup missed, which reports X-Scrape-Cache: miss and likewise ran no tier — exists only as an internal deploy-skew safeguard and is not reachable through this API. */
                     "X-Scrape-Proxy-Tier-Label"?: string;
                     /** @description WAF vendor detected on the target, if any (diagnostic). May be "suspected" when a low-confidence fail-open block marker was served. Omitted when no WAF is detected. */
                     "X-Scrape-Waf"?: string;
@@ -3487,10 +3652,10 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["ScrapeSuccessEnvelope"];
+                    "application/json": components["schemas"]["ScrapeSuccessEnvelope"] | components["schemas"]["ScrapeErrorEnvelope"];
                 };
             };
-            /** @description Scrape accepted for async processing. */
+            /** @description Scrape accepted for background processing; the body is a receipt, not content. Returned when `async: true` was requested, or when a browser-path request's hold window expired before the render finished. Poll `GET /v1/scrape/{id}` for the result. */
             202: {
                 headers: {
                     /** @description Stable scrape identifier for the queued job. */
@@ -3779,7 +3944,14 @@ export interface operations {
     };
     getScrapeBulk: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Opaque cursor returned by the preceding page. It is bound to this bulk id, this recovery route, and the exact status filter; cross-scope cursors return 422. */
+                cursor?: string;
+                /** @description Maximum result rows considered for this page; the 16-MiB response bound may stop sooner. */
+                limit?: number;
+                /** @description Optional item-status filter. A cursor may be reused only with the same filter. */
+                status?: "pending" | "processing" | "completed" | "failed" | "cancelled";
+            };
             header?: never;
             path: {
                 id: string;
@@ -3818,8 +3990,12 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
-                        /** @description Rehydrated per-URL scrape envelopes — the terminal page of results (default 100 rows, `?limit=` up to 500). `routes/scrape-bulk.ts` spreads this key into the SAME body on both status branches, so it is present here exactly as it is on the 202; on the 200 the entries carry their final success or error envelopes (issue #3632). */
-                        items: components["schemas"]["ScrapeEnvelope"][];
+                        /** @description Opaque cursor for the next stable page; null when traversal is complete. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        /** @description Rehydrated per-URL scrape envelopes — the terminal page of results (default 500 rows, `?limit=` up to 500). `routes/scrape-bulk.ts` spreads this key into the SAME body on both status branches, so it is present here exactly as it is on the 202; on the 200 the entries carry their final success or error envelopes (issue #3632). */
+                        items: (components["schemas"]["ScrapeEnvelope"] | components["schemas"]["BulkMandatoryScrapeItem"])[];
                     };
                 };
             };
@@ -3853,8 +4029,12 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
-                        /** @description Rehydrated per-URL scrape envelopes — the same page the 200 returns (default 100 rows, `?limit=` up to 500). While the job is non-terminal most entries carry the `queued` envelope. */
-                        items: components["schemas"]["ScrapeEnvelope"][];
+                        /** @description Opaque cursor for the next stable page; null when traversal is complete. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        /** @description Rehydrated per-URL scrape envelopes — the same page the 200 returns (default 500 rows, `?limit=` up to 500). While the job is non-terminal most entries carry the `queued` envelope. */
+                        items: (components["schemas"]["ScrapeEnvelope"] | components["schemas"]["BulkMandatoryScrapeItem"])[];
                     };
                 };
             };
@@ -4220,7 +4400,14 @@ export interface operations {
     };
     getFetchBulk: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Opaque cursor returned by the preceding page. It is bound to this bulk id, this recovery route, and the exact status filter; cross-scope cursors return 422. */
+                cursor?: string;
+                /** @description Maximum result rows considered for this page; the 16-MiB response bound may stop sooner. */
+                limit?: number;
+                /** @description Optional item-status filter. A cursor may be reused only with the same filter. */
+                status?: "pending" | "processing" | "completed" | "failed" | "cancelled";
+            };
             header?: never;
             path: {
                 id: string;
@@ -4253,8 +4440,12 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
-                        /** @description Per-URL fetch items, oldest first, capped at 500 (listBulkFetchItemsWithLatestAttempt). */
-                        items: {
+                        /** @description Opaque cursor for the next stable page; null when traversal is complete. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        /** @description Stable per-URL fetch items, oldest first. Follow `next_cursor` while `has_more` is true to enumerate the complete filtered job; each page considers at most 500 rows and is bounded to 16 MiB. */
+                        items: ({
                             /**
                              * @description Scrape-row id, `sc_`-prefixed. Fetch-bulk items are rows of the same resource sync `/v1/scrape` returns, so they share its prefix. Not to be confused with the `ft_`-prefixed `X-Fetch-ID` correlation header on sync `/v1/fetch`, which identifies a request rather than a stored item.
                              * @example sc_01j9abc123
@@ -4264,25 +4455,46 @@ export interface operations {
                             url: string;
                             /** @enum {string} */
                             status: "pending" | "processing" | "completed" | "failed" | "cancelled";
-                            content_type: string | null;
-                            content_length: number | null;
-                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            content_type?: string | null;
+                            content_length?: number | null;
+                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body or whose object cannot be signed. In the latter case `error_code` is `artifact_unavailable`; the private unsigned storage URL is never returned. */
                             content_url: string | null;
-                            waf_vendor: string | null;
-                            cache_hit: boolean;
+                            waf_vendor?: string | null;
+                            cache_hit?: boolean;
                             /**
                              * @description Itemised account of this item's charge — the basis, the named factors
                              *     that composed the multiplier, and the resulting billed bytes. Omitted
                              *     for rows that completed before the billing node was persisted.
                              */
                             billing?: components["schemas"]["BillingNode"];
+                            /** @description Stable item-local error code. `artifact_unavailable` means the stored result or a usable signed reference could not be produced. */
                             error_code: string | null;
                             error_message: string | null;
                             /** Format: date-time */
-                            created_at: string;
+                            created_at?: string;
                             /** Format: date-time */
-                            completed_at: string | null;
-                        }[];
+                            completed_at?: string | null;
+                        } | {
+                            /**
+                             * @description Scrape-row id, `sc_`-prefixed — the same stable identity the ordinary item carries, so recovery pagination is unaffected.
+                             * @example sc_01j9abc123
+                             */
+                            id: string;
+                            /** @enum {string} */
+                            type: "fetch";
+                            /**
+                             * @description Terminal state of the item. This is the contract's terminal signal and outranks the ordinary item's legacy `status` spelling.
+                             * @enum {string}
+                             */
+                            terminal_outcome: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            /** Format: uri */
+                            url: string;
+                            /** @description Bounded pre-signed download URL retained from the ordinary item, or `null` when the reference did not fit or could not be produced. */
+                            content_url: string | null;
+                            error_code: string | null;
+                            /** @description Bounded failure detail; a long message is truncated. */
+                            error_message: string | null;
+                        })[];
                     };
                 };
             };
@@ -4319,8 +4531,12 @@ export interface operations {
                         estimated_credits: number | null;
                         /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
                         webhook_url: string;
-                        /** @description Per-URL fetch items, oldest first, capped at 500 (listBulkFetchItemsWithLatestAttempt). */
-                        items: {
+                        /** @description Opaque cursor for the next stable page; null when traversal is complete. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        /** @description Stable per-URL fetch items, oldest first. Follow `next_cursor` while `has_more` is true to enumerate the complete filtered job; each page considers at most 500 rows and is bounded to 16 MiB. */
+                        items: ({
                             /**
                              * @description Scrape-row id, `sc_`-prefixed. Fetch-bulk items are rows of the same resource sync `/v1/scrape` returns, so they share its prefix. Not to be confused with the `ft_`-prefixed `X-Fetch-ID` correlation header on sync `/v1/fetch`, which identifies a request rather than a stored item.
                              * @example sc_01j9abc123
@@ -4330,25 +4546,46 @@ export interface operations {
                             url: string;
                             /** @enum {string} */
                             status: "pending" | "processing" | "completed" | "failed" | "cancelled";
-                            content_type: string | null;
-                            content_length: number | null;
-                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            content_type?: string | null;
+                            content_length?: number | null;
+                            /** @description Pre-signed download URL for the fetched body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` on `GET /v1/bulk/{id}/screenshots`. A new signature is minted on every poll. Null for items with no stored body or whose object cannot be signed. In the latter case `error_code` is `artifact_unavailable`; the private unsigned storage URL is never returned. */
                             content_url: string | null;
-                            waf_vendor: string | null;
-                            cache_hit: boolean;
+                            waf_vendor?: string | null;
+                            cache_hit?: boolean;
                             /**
                              * @description Itemised account of this item's charge — the basis, the named factors
                              *     that composed the multiplier, and the resulting billed bytes. Omitted
                              *     for rows that completed before the billing node was persisted.
                              */
                             billing?: components["schemas"]["BillingNode"];
+                            /** @description Stable item-local error code. `artifact_unavailable` means the stored result or a usable signed reference could not be produced. */
                             error_code: string | null;
                             error_message: string | null;
                             /** Format: date-time */
-                            created_at: string;
+                            created_at?: string;
                             /** Format: date-time */
-                            completed_at: string | null;
-                        }[];
+                            completed_at?: string | null;
+                        } | {
+                            /**
+                             * @description Scrape-row id, `sc_`-prefixed — the same stable identity the ordinary item carries, so recovery pagination is unaffected.
+                             * @example sc_01j9abc123
+                             */
+                            id: string;
+                            /** @enum {string} */
+                            type: "fetch";
+                            /**
+                             * @description Terminal state of the item. This is the contract's terminal signal and outranks the ordinary item's legacy `status` spelling.
+                             * @enum {string}
+                             */
+                            terminal_outcome: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            /** Format: uri */
+                            url: string;
+                            /** @description Bounded pre-signed download URL retained from the ordinary item, or `null` when the reference did not fit or could not be produced. */
+                            content_url: string | null;
+                            error_code: string | null;
+                            /** @description Bounded failure detail; a long message is truncated. */
+                            error_message: string | null;
+                        })[];
                     };
                 };
             };
@@ -4366,6 +4603,9 @@ export interface operations {
     listBulk: {
         parameters: {
             query?: {
+                limit?: components["parameters"]["LimitParam"];
+                /** @description Pagination cursor from a previous response. */
+                cursor?: components["parameters"]["CursorParam"];
                 status?: "processing" | "completed" | "failed";
             };
             header?: never;
@@ -4381,27 +4621,31 @@ export interface operations {
                 };
                 content: {
                     "application/json": {
-                        /** @example bulk_01j9abc123 */
-                        id: string;
-                        /** @enum {string} */
-                        status: "processing" | "completed" | "failed";
-                        total: number;
-                        completed: number;
-                        failed: number;
-                        /** Format: date-time */
-                        created_at: string;
-                        /** Format: date-time */
-                        completed_at: string | null;
-                        /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
-                        total_credits_charged: number | null;
-                        /** @description Null in GET responses (computed at submission time only). */
-                        estimated_credits: number | null;
-                        /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
-                        webhook_url: string;
-                    }[];
+                        next_cursor: string | null;
+                        has_more: boolean;
+                        data: {
+                            /** @example bulk_01j9abc123 */
+                            id: string;
+                            /** @enum {string} */
+                            status: "processing" | "completed" | "failed";
+                            total: number;
+                            completed: number;
+                            failed: number;
+                            /** Format: date-time */
+                            created_at: string;
+                            /** Format: date-time */
+                            completed_at: string | null;
+                            /** @description Total credits billed for the job. Null until the job is billed. Fractional — credits are NUMERIC(10,2). */
+                            total_credits_charged: number | null;
+                            /** @description Null in GET responses (computed at submission time only). */
+                            estimated_credits: number | null;
+                            /** @description Webhook endpoint URL (HTTPS only; http:// rejected with 400 invalid_url, reason scheme_unsupported) */
+                            webhook_url: string;
+                        }[];
+                    };
                 };
             };
-            /** @description Validation error. Returned when `status` is not one of the documented values. */
+            /** @description Validation error. Returned when `status` is not one of the documented values, or when `cursor` is not a cursor this endpoint issued. */
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -4789,7 +5033,14 @@ export interface operations {
     };
     listBulkScreenshots: {
         parameters: {
-            query?: never;
+            query?: {
+                /** @description Opaque per-type seek cursor returned by the preceding page. It is bound to this bulk id, this mixed recovery route, and the exact status filter; cross-scope cursors return 422. */
+                cursor?: string;
+                /** @description Maximum rows selected per requested item type; the 16-MiB response bound may stop sooner. */
+                limit?: number;
+                /** @description Optional item-status filter. A cursor may be reused only with the same filter. */
+                status?: "pending" | "processing" | "completed" | "failed" | "cancelled";
+            };
             header?: never;
             path: {
                 id: string;
@@ -4809,8 +5060,13 @@ export interface operations {
                         bulk_id: string;
                         /** @description Number of items in `items` (page size, not the job total). */
                         total: number;
+                        /** @description Opaque per-type cursor for the next stable page; null when every selected item type is exhausted. Never advances past an item omitted by the byte bound. */
+                        next_cursor: string | null;
+                        /** @description True when another page is available through `next_cursor`. */
+                        has_more: boolean;
+                        job_counters: components["schemas"]["BulkJobCounters"];
                         /** @description Heterogeneous capture items discriminated by `type`. Fields outside the common set are present only for the matching `type`. */
-                        items: {
+                        items: ({
                             /** @enum {string} */
                             type: "screenshot" | "recording" | "scrape";
                             /** @description Prefixed id — `ss_` / `rec_` / `sc_` per `type`. */
@@ -4819,7 +5075,7 @@ export interface operations {
                             status: "pending" | "processing" | "completed" | "failed" | "cancelled";
                             /** Format: uri */
                             url: string;
-                            credits_charged: number | null;
+                            credits_charged?: number | null;
                             /**
                              * @description Itemised account of this item's charge — the basis, the named factors
                              *     that composed the multiplier, and the resulting billed bytes. Omitted
@@ -4827,12 +5083,13 @@ export interface operations {
                              */
                             billing?: components["schemas"]["BillingNode"];
                             error_code: string | null;
+                            /** @description Bounded human-readable failure detail. */
                             error_message: string | null;
                             /** Format: date-time */
-                            created_at: string;
+                            created_at?: string;
                             /** Format: date-time */
-                            completed_at: string | null;
-                            /** @description `type: screenshot` only. Presigned for completed rows with a storage key; raw image_url otherwise. */
+                            completed_at?: string | null;
+                            /** @description `type: screenshot` only. Pre-signed download URL for the image, minted fresh for completed rows with a storage key and valid for 600 seconds (10 minutes). For every other row the stored value is returned unchanged — `null` while no image has been stored, and otherwise a private, unsigned storage URL that returns 401 on download. That covers non-completed rows, completed rows with no storage key, and completed rows whose object could not be signed; none of them raise an `artifact_warnings` entry. */
                             image_url?: string | null;
                             /** @description `type: screenshot` and `type: scrape` only. */
                             page_title?: string | null;
@@ -4840,7 +5097,7 @@ export interface operations {
                             format?: string;
                             /** @description `type: recording` only. */
                             video_url?: string | null;
-                            /** @description `type: scrape` only. Pre-signed download URL for the scraped body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` above and of `content_url` on `GET /v1/fetch/bulk/{id}`. A new signature is minted on every poll. Null for items with no stored body; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            /** @description `type: scrape` only. Pre-signed download URL for the scraped body, valid for 600 seconds (10 minutes) from the moment this response was generated — matching the signing TTL of `image_url` above and of `content_url` on `GET /v1/fetch/bulk/{id}`. A new signature is minted on every poll for a completed item with a storage key. For every other item the stored value is returned unchanged — `null` while no body has been stored, and otherwise a private, unsigned storage URL that returns 401 on download. No `artifact_warnings` entry is raised for this field; unlike `GET /v1/fetch/bulk/{id}`, this endpoint reports no `artifact_unavailable` when signing fails. */
                             content_url?: string | null;
                             /** @description `type: scrape` only. */
                             content_type?: string | null;
@@ -4848,9 +5105,33 @@ export interface operations {
                             content_length?: number | null;
                             /** @description `type: scrape` only. Always null in bulk listings — fetch the body via `markdown_url`. */
                             markdown?: string | null;
-                            /** @description `type: scrape` only. Pre-signed download URL for the markdown rendering of the page, valid for 600 seconds (10 minutes) from the moment this response was generated — the same signing TTL as `content_url` and `image_url` above. A new signature is minted on every poll. Null for items with no stored markdown; a completed item whose object cannot be signed falls back to the unsigned stored URL, which returns 401 on download. */
+                            /** @description `type: scrape` only. Pre-signed download URL for the markdown rendering of the page, valid for 600 seconds (10 minutes) from the moment this response was generated — the same signing TTL as `content_url` and `image_url` above. A new signature is minted on every poll for a completed item with a markdown key. For every other item the stored value is returned unchanged — `null` while no markdown has been stored, and otherwise a private, unsigned storage URL that returns 401 on download. No `artifact_warnings` entry is raised for this field; unlike `GET /v1/fetch/bulk/{id}`, this endpoint reports no `artifact_unavailable` when signing fails. */
                             markdown_url?: string | null;
-                        }[];
+                            /** @description `type: scrape` only. Exact requested artifact values or signed references. Every key is present; unrequested or unavailable values are null, with nonfatal reference failures in `artifact_warnings`. */
+                            artifacts?: {
+                                raw: string | null;
+                                markdown: string | null;
+                                links: null | (string | components["schemas"]["ScrapeScoredLink"])[];
+                                images: null | (string | components["schemas"]["ScrapeScoredImage"])[];
+                            };
+                            /** @description Nonfatal artifact reference failures for this scrape item. */
+                            artifact_warnings?: components["schemas"]["ScrapeWarning"][];
+                        } | {
+                            /** @description Prefixed id — `ss_` / `rec_` / `sc_` per `type`. The same stable identity the ordinary item carries. */
+                            id: string;
+                            /** @enum {string} */
+                            type: "screenshot" | "recording" | "scrape";
+                            /**
+                             * @description Terminal state of the item. This is the contract's terminal signal and outranks the ordinary item's legacy `status` spelling.
+                             * @enum {string}
+                             */
+                            terminal_outcome: "pending" | "processing" | "completed" | "failed" | "cancelled";
+                            /** Format: uri */
+                            url: string;
+                            error_code: string | null;
+                            /** @description Bounded failure detail; a long message is truncated. */
+                            error_message: string | null;
+                        })[];
                     };
                 };
             };
@@ -5472,10 +5753,10 @@ export interface operations {
                 };
                 content: {
                     "application/json": {
-                        /** @description Extracted JSON conforming to the normalized schema, or `null` when the model returned a refusal. */
+                        /** @description Extracted JSON conforming to the normalized schema, or `null` when `validated` is `false` — see `validated` for the cases. A `validated: true` response always carries an object here, never `null`. */
                         data: Record<string, never> | null;
                         model: string;
-                        /** @description `true` when the output passed Ajv re-validation; `false` when retries were exhausted (`data` carries the last raw output, with `extract_validation_failed` in `warnings`). */
+                        /** @description `true` when the output passed Ajv re-validation and at least one leaf is non-null. An all-null output is also `true` when your schema explicitly allows it: every leaf the output returned as `null` sits at a node whose `type` is a union containing `"null"` in the schema you sent (only that form counts — `nullable: true`, an `enum` containing `null` and `const: null` do not). An output that is itself `null` rather than an object is never accepted, whatever your root schema declares. `false` (with `data: null`) when the model refused (`model_refusal`), when retries were exhausted (`extract_validation_failed`, `exhausted_retries`), or when a schema-valid output has every leaf `null` and is not one the declaration above accepts (`empty_extraction`). The per-request credits are charged only for `true`. */
                         validated: boolean;
                         metrics: {
                             scrape_ms: number;
@@ -5495,7 +5776,7 @@ export interface operations {
                             /** @description True when markdown exceeded the LLM token budget and was tail-truncated. */
                             truncated: boolean;
                         };
-                        /** @description Additive warning codes, e.g. `content_truncated`, `extract_validation_failed`, `exhausted_retries`, `model_refusal`. */
+                        /** @description Additive warning codes, e.g. `content_truncated`, `extract_validation_failed`, `exhausted_retries`, `model_refusal`, `empty_extraction`. */
                         warnings: string[];
                     };
                 };
@@ -5602,6 +5883,8 @@ export interface operations {
                         credits_single: number;
                         credits_bulk: number;
                         credits_monitor: number;
+                        /** @description Credits drawn under the scrape usage source this billing period, such as `/v1/schema` extractions. `credits_single`, `credits_bulk`, `credits_monitor`, `credits_scrape` and `credits_search` together sum to `credits_used`. */
+                        credits_scrape: number;
                         /** @description Credits consumed by the search endpoint this billing period. Reported as a distinct line item, not folded into other per-source credit counts. */
                         credits_search: number;
                         credits_limit: number;
@@ -5619,7 +5902,7 @@ export interface operations {
                         plan_type: "payg" | "subscription";
                         /** @description Total top-up spend in cents for this billing period. Present only in dual/bytes billing mode. */
                         topup_spent_cents?: number;
-                        /** @description Remaining purchased top-up bytes, already net of any overage consumed against them. Equal to topup_bytes. Present only in dual/bytes billing mode. */
+                        /** @description Remaining top-up bytes: the current-plan estimate of what the USD balance buys plus the one-time starter grant, already net of any overage consumed against them. Equal to topup_bytes. Present only in dual/bytes billing mode. */
                         topup_balance_bytes?: number;
                         /** @description Days elapsed since period_start. */
                         period_days_elapsed: number;
@@ -5629,13 +5912,13 @@ export interface operations {
                         bytes_bulk: number;
                         bytes_scrape: number;
                         bytes_monitor: number;
-                        /** @description The spendable byte budget for this period, summed over the account's value lots: the allowance granted for the current period, plus unspent allowance carried over from earlier periods, plus purchased top-up and starter-grant bytes. The figure falls as those lots are consumed. */
+                        /** @description The spendable byte budget for this period, summed over the account's value lots: the allowance granted for the current period, plus unspent allowance carried over from earlier periods, plus the USD balance's current-plan byte estimate and the starter grant. The figure falls as they are consumed. */
                         bytes_limit: number;
                         /** @description Bytes still available across every active lot, after active refund reservations. */
                         bytes_remaining: number;
-                        /** @description Unspent allowance carried over from earlier billing periods. Value is spent in one order: your plan's included allowance, including any rollover from earlier periods, then purchased top-ups, then the one-time starter grant. */
+                        /** @description Unspent allowance carried over from earlier billing periods. Value is spent in one order: your plan's included allowance, including any rollover from earlier periods, then the USD balance, then the one-time starter grant. */
                         rollover_bytes: number;
-                        /** @description Bytes remaining in purchased top-up and starter-grant lots. Subscription allowance is excluded. */
+                        /** @description The USD balance's current-plan byte estimate plus the starter grant. Subscription allowance is excluded. */
                         topup_bytes: number;
                         /** @description Total API requests in the current billing period. */
                         request_count: number;
@@ -5681,6 +5964,8 @@ export interface operations {
                             credits_single: number;
                             credits_bulk: number;
                             credits_monitor: number;
+                            /** @description Credits drawn under the scrape usage source on this day, such as `/v1/schema` extractions. */
+                            credits_scrape: number;
                             /** @description Credits consumed by the search endpoint on this day. */
                             credits_search: number;
                             credits_total: number;
@@ -5771,12 +6056,12 @@ export interface operations {
                 /** @description End date (YYYY-MM-DD), inclusive. Default today. */
                 to?: string;
                 /** @description Filter to a single endpoint kind. */
-                endpoint?: "scrape" | "fetch" | "screenshots" | "recordings";
+                endpoint?: "scrape" | "fetch" | "screenshots" | "recordings" | "search" | "webhook";
                 /** @description Filter by job outcome. */
                 status?: "pending" | "processing" | "completed" | "failed";
-                /** @description Case-insensitive substring match on the request URL. */
+                /** @description Case-insensitive substring match on the request URL — the search query on search rows and the target URL on webhook rows. */
                 url?: string;
-                /** @description Filter by API key (prefixed ID, e.g. `ak_xxx`). The key must belong to the requesting account; cross-account keys return an empty feed. Resolves the account's playground key too. */
+                /** @description Filter by API key (prefixed ID, e.g. `ak_xxx`). The key must belong to the requesting account; cross-account keys return an empty feed. Resolves the account's playground key too. Webhook delivery attempts are not issued by an API key, so this filter excludes them. */
                 api_key?: string;
                 /** @description Opaque pagination cursor from a prior response's `next_cursor`. */
                 cursor?: string;
@@ -5797,35 +6082,40 @@ export interface operations {
                 content: {
                     "application/json": {
                         data: {
-                            /** @description Prefixed request id (sc_/ss_/rec_). */
+                            /** @description Prefixed request id (sc_/ss_/rec_/sr_/wh_). */
                             id: string;
-                            /** @enum {string} */
-                            endpoint: "scrape" | "fetch" | "screenshots" | "recordings";
-                            /** @description HTTP method. Not persisted; capture endpoints are POST (so this is always "POST"). /v1/fetch also accepts GET, but the stored row cannot distinguish it. */
+                            /**
+                             * @description The request kind. `webhook` rows are webhook delivery attempts ByteKit sent to your endpoint, not requests you made.
+                             * @enum {string}
+                             */
+                            endpoint: "scrape" | "fetch" | "screenshots" | "recordings" | "search" | "webhook";
+                            /** @description HTTP method. Not persisted; capture and search endpoints are POST, and webhook deliveries are sent as POST (so this is always "POST"). /v1/fetch also accepts GET, but the stored row cannot distinguish it. */
                             method: string;
+                            /** @description The request URL. On a search row this is the search query (empty once the retention window has redacted it); on a webhook row it is the delivery target URL. */
                             url: string;
                             final_url?: string | null;
                             /**
-                             * @description Job outcome.
+                             * @description Job outcome. On a webhook row: `completed` = delivered, `processing` = a failed attempt that will be retried, `failed` = retries exhausted, `pending` = not yet delivered or failed (an attempt may be in flight).
                              * @enum {string}
                              */
                             status: "pending" | "processing" | "completed" | "failed";
-                            /** @description Upstream target HTTP status; scrape/fetch only. */
+                            /** @description Upstream target HTTP status on scrape/fetch rows; the HTTP status your endpoint answered on webhook rows. null on every other row. */
                             status_code?: number | null;
                             /** @description Raw upstream bytes the request carried (the billing base before the multiplier). null while pending/failed. */
                             raw_bytes?: number | null;
-                            /** @description The bytes this request was BILLED — the same amount its own response reported in `X-Billable-Bytes`. For a scrape or fetch request this is the settled decomposition replayed as it was recorded at completion, so it already carries every factor that applied: the endpoint factor (`scrape` 1.0, `scrape_md` 1.5, `fetch` 1.0, `fetch_md` 1.5, a monitor run 1.0), the cache-hit ×0.5, and the clean-markdown ×3. Screenshots and recordings are `raw_bytes` × the fixed 1.5 Phase-1 render factor whatever capture options they carried — capture billing composes no discount factor, so that product is exact. It is NOT `raw_bytes` × `billing_multiplier`: that field reports a CREDIT count, a different quantity from the byte factors above, and on a recordings row their product is not bytes at all. One residual: a scrape or fetch row completed before the decomposition was recorded is reconstructed from its endpoint and cache-hit factors, which leaves a markdown `/v1/fetch` request of that vintage reported at 1.0 rather than 1.5 — nothing on such a row distinguishes it. That population ages out of this feed's retention window and is not backfilled. null while pending/failed (the row has no byte basis yet). */
+                            /** @description The bytes this request was BILLED — the same amount its own response reported in `X-Billable-Bytes`. For a scrape or fetch request this is the settled decomposition replayed as it was recorded at completion, so it already carries every factor that applied: the endpoint factor (`scrape` 1.0, `scrape_md` 1.5, `fetch` 1.0, `fetch_md` 1.5, a monitor run 1.0), the cache-hit ×0.5, and the clean-markdown ×3. Screenshots and recordings are `raw_bytes` × the fixed 1.5 Phase-1 render factor whatever capture options they carried — capture billing composes no discount factor, so that product is exact. This is the settled amount itself, never a product reconstructed from another field: `billing_multiplier` below is DERIVED from it (that field is this value over `raw_bytes`), so the dependency runs this way and not the other. One residual: a scrape or fetch row completed before the decomposition was recorded is reconstructed from its endpoint and cache-hit factors, which leaves a markdown `/v1/fetch` request of that vintage reported at 1.0 rather than 1.5 — nothing on such a row distinguishes it. That population ages out of this feed's retention window and is not backfilled. null while pending/failed (the row has no byte basis yet). */
                             billable_bytes?: number | null;
-                            /** @description BASE billing multiplier persisted for this request — the settled `credits_charged` factor. It is NOT what `billable_bytes` above is derived from: that field reports settled BYTES, and multiplying `raw_bytes` by this credit count does not give the amount billed. Its scale is not uniform and is not a rate you can carry from one row to another: each endpoint persists its own credit unit, and the single and bulk paths of the same endpoint may persist different factors for identical options. Read this as the factor this one row settled at, and see https://bytekit.com/docs/billing/credits for what each endpoint charges. This is a LOGS ROW field and is NOT the scrape response envelope field — the envelope carries no flat `billing_multiplier` at all; its billing surface is the `billing` node (see BillingNode). This row reports only the base settled factor, so it can differ from `billing.multiplier` and from the X-Billing-Multiplier response header, both of which report the composed real-endpoint value. null while pending/failed. */
+                            /** @description The bandwidth factor this request settled at, DERIVED from the two fields above as `billable_bytes` / `raw_bytes`, ROUNDED TO 2 DECIMAL PLACES. It carries every factor that applied to the settled amount, composed: the endpoint factor, the cache-hit ×0.5 and the clean-markdown ×3 on a scrape or fetch row, and the flat 1.5 Phase-1 render factor on every screenshot and recording row whatever capture options it carried. Every factor reachable that way is a multiple of 0.25 (0.5, 0.75, 1, 1.5, 2.25, 3, 4.5), so 2 places reports each of them exactly on any basis of 100 bytes or more. The rounding is there because `billable_bytes` is itself rounded, which on an odd basis would otherwise surface here as 1.500001943158721 rather than 1.5. `raw_bytes` × `billing_multiplier`, rounded to the nearest byte, reproduces `billable_bytes` at every basis. CHANGED: this field used to report the row's persisted `credits_charged` — an account CREDIT count on a per-endpoint scale, not a bandwidth factor. On a screenshot that count is charged per capture option (`full_page`, `mobile`), so two captures billed at the same 1.5 factor reported different multipliers. See https://bytekit.com/docs/billing/credits for the credit counts each endpoint charges, which this field no longer reports. This is a LOGS ROW field and is NOT the scrape response envelope field — the envelope carries no flat `billing_multiplier` at all; its billing surface is the `billing` node (see BillingNode). It reports the same composed value as `billing.multiplier` and the X-Billing-Multiplier response header wherever `billable_bytes` is exact, which is every row but one: the residual described above for `billable_bytes`, a markdown `/v1/fetch` request completed before the decomposition was recorded, is reconstructed at 1.0 where settlement charged 1.5, and this field reports that same 1.0. null where the row has no factor to report: while pending/failed; on a search or webhook row (neither has a byte basis); where the basis is zero because Phase 1 was skipped or failed and the request billed nothing; and on a completed screenshot or recording old enough that no Phase-1 basis was ever recorded for it, which reports null rather than claiming a real past charge was nothing. */
                             billing_multiplier?: number | null;
+                            /** @description Request duration in milliseconds; on a webhook row, how long your endpoint took to answer the latest attempt. */
                             duration_ms?: number | null;
-                            /** @description How the request originated (single/bulk/monitor). */
-                            source?: string;
+                            /** @description How the request originated (single/bulk/monitor). null on search and webhook rows. */
+                            source?: string | null;
                             error_code?: string | null;
                             error_message?: string | null;
                             /** @description Prefixed key id (ak_) that issued the request. */
                             api_key_id?: string | null;
-                            /** @description Stored content, image or video URL — null when the row has no stored object. For a `completed` row with a stored object this is a **pre-signed** download URL, minted fresh on every read of this endpoint and valid for **600 seconds (10 minutes)** — the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}` and `image_url` on `GET /v1/bulk/{id}/screenshots`. The underlying objects are private, so an unsigned URL returns 401: download inside that window, or re-poll this endpoint for a fresh signature. Rows that are not `completed`, and completed rows whose object cannot be signed, fall back to the unsigned stored URL, which returns 401 on download. */
+                            /** @description Stored content, image or video URL. For a `completed` row with a non-empty storage key this is a **pre-signed** download URL, minted fresh on every read of this endpoint and valid for **600 seconds (10 minutes)** — the same signing lifetime as `content_url` on `GET /v1/fetch/bulk/{id}` and `image_url` on `GET /v1/bulk/{id}/screenshots`. Download inside that window, or re-poll this endpoint for a fresh signature. For every other row the stored value is returned unchanged — `null` while no object has been stored, and otherwise a private, unsigned storage URL that returns 401 on download. That covers rows that are not `completed`, completed rows with no storage key, and completed rows whose object could not be signed; this endpoint raises no `artifact_unavailable` signal for any of them. */
                             artifact_url?: string | null;
                             /** @description The original request options. */
                             options?: {
@@ -5986,81 +6276,10 @@ export interface operations {
             content: {
                 "application/json": {
                     /**
-                     * @description Bytes to purchase. Allowed tiers — 5, 25, 50, 75, 100 GB (1 GB = 1,000,000,000 bytes).
-                     * @enum {integer}
-                     */
-                    bytes: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
-                    /**
-                     * Format: uri
-                     * @description Redirect target after a completed Checkout.
-                     */
-                    success_url: string;
-                    /**
-                     * Format: uri
-                     * @description Redirect target when the user abandons Checkout.
-                     */
-                    cancel_url: string;
-                };
-            };
-        };
-        responses: {
-            /** @description Hosted Checkout session created. */
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        /** Format: uri */
-                        checkout_url: string;
-                        session_id: string;
-                    };
-                };
-            };
-            /** @description No customer or free plan. */
-            400: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
-            /** @description Validation error (missing/invalid fields). */
-            422: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
-            /** @description Stripe error creating the Checkout session. */
-            502: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["Error"];
-                };
-            };
-        };
-    };
-    createCreditTopup: {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": {
-                    /**
-                     * @description Credits to purchase. Allowed tiers — 1k, 10k, 25k, 50k, 100k.
+                     * @description Amount to deposit, in US cents. Allowed amounts — $10, $25, $50, $100, $500. Charged exactly; the plan rate prices usage, not the deposit.
                      * @enum {integer}
                      */
-                    credits: 1000 | 10000 | 25000 | 50000 | 100000;
+                    amount_cents: 1000 | 2500 | 5000 | 10000 | 50000;
                     /**
                      * Format: uri
                      * @description Redirect target after a completed Checkout.
@@ -6337,7 +6556,10 @@ export interface operations {
                 };
                 content: {
                     "application/json": {
-                        bandwidth: components["schemas"]["BandwidthBalance"];
+                        bandwidth: components["schemas"]["BandwidthBalance"] & {
+                            /** @description Remaining balance of your subscription allowance: bytes still unspent across all allowance lots, the current period's and any rolled over from earlier periods alike, after active refund reservations. This is a remaining balance and falls to zero as the allowance is drawn down. It is not `included_bytes`, which is the plan's configured grant for a period and does not move as it is spent; do not subtract one from the other. `rollover_bytes` is a subset of this figure. */
+                            remaining_allowance_bytes: number;
+                        };
                         credits: components["schemas"]["CreditBalance"];
                         rates: {
                             /** @description Bandwidth top-up price in cents per MB. When the authenticated account is on a plan that does not explicitly configure a top-up price (e.g. free, payg, or a custom plan without an explicit value), the API falls back to the rack rate — the highest `topup_price_per_mb_cents` configured across all plans — so the UI never advertises `$0.00/GB`. */
@@ -6352,10 +6574,17 @@ export interface operations {
                         included_bytes?: number;
                         /** @description Number of automatic top-up transactions (bandwidth and credit) that have been triggered in the current calendar month. Includes both pending and completed transactions. */
                         triggers_this_month?: number;
+                        /** @description The account's USD top-up balance. It never expires and is spent on usage beyond the included allowance, at the rate of the plan in force when the usage happens. */
+                        usd_balance: {
+                            /** @description Balance in whole US cents, rounded down. Can be negative when usage settled after the balance ran out. */
+                            cents: number;
+                            /** @description Part of `cents` held by an open refund and not spendable, in whole US cents, rounded down. */
+                            reserved_cents: number;
+                        };
                         auto_topup: {
                             enabled: boolean;
-                            threshold_bytes: number | null;
-                            amount_bytes: number | null;
+                            threshold_cents: number | null;
+                            amount_cents: number | null;
                             monthly_cap_cents: number | null;
                             monthly_spend_cents: number;
                         };
@@ -6375,15 +6604,12 @@ export interface operations {
             content: {
                 "application/json": {
                     enabled: boolean;
-                    /** @description Min 1 MB (1,000,000 bytes). Required when enabled. */
-                    threshold_bytes?: number;
-                    /**
-                     * @description Allowed tiers — 5, 25, 50, 75, 100 GB (1 GB = 1,000,000,000 bytes). Required when enabled.
-                     * @enum {integer}
-                     */
-                    amount_bytes?: 5000000000 | 25000000000 | 50000000000 | 75000000000 | 100000000000;
-                    /** @description $1-$1000. Required when enabled. */
-                    monthly_cap_cents?: number;
+                    /** @description Top up when the remaining value (plan allowance plus USD balance, priced at the plan's top-up rate) drops below this many US cents. Min $1. Required when enabled. */
+                    threshold_cents?: number;
+                    /** @description US cents added to the USD balance on each auto top-up, $5-$1000. Required when enabled. */
+                    amount_cents?: number;
+                    /** @description $1-$1000, or null for no monthly cap. Required when enabled — send an explicit null to remove the cap; omitting the key is rejected. */
+                    monthly_cap_cents?: number | null;
                 };
             };
         };
@@ -6396,8 +6622,8 @@ export interface operations {
                 content: {
                     "application/json": {
                         enabled: boolean;
-                        threshold_bytes: number | null;
-                        amount_bytes: number | null;
+                        threshold_cents: number | null;
+                        amount_cents: number | null;
                         monthly_cap_cents: number | null;
                     };
                 };