33from typing import List , Optional
44from typing_extensions import Literal
55
6- from .error import Error
6+ from .intake import Intake
77from .._models import BaseModel
8- from .error_count import ErrorCount
8+ from .crawl_controls import CrawlControls
9+ from .page_error_count import PageErrorCount
910
10- __all__ = ["BatchCancelResponse" , "Credits" , "Input" , " Progress" , "Results" , "ResultsFile ""Timing" , "KeyMetadata" ]
11+ __all__ = ["BatchCancelResponse" , "Credits" , "Progress" , "Timing" , "KeyMetadata" ]
1112
1213
1314class Credits (BaseModel ):
14- """Reserved and used credits ."""
15+ """What this batch cost so far ."""
1516
16- charged : int
17- """Credits used by successful pages."""
17+ reserved : int
18+ """Credits debited at submission.
1819
19- estimated : int
20- """Credits reserved when the batch was accepted."""
21-
22-
23- class Input (BaseModel ):
24- """Submission counts."""
25-
26- accepted : int
27- """Pages accepted, or the crawl page limit. Credits are reserved for this count."""
28-
29- duplicates : int
30- """Duplicate URL and `itemId` pairs skipped. Always 0 for crawls."""
31-
32- invalid : int
33- """Pages rejected during validation."""
34-
35- submitted : int
36- """Pages submitted before validation. For a crawl, the page limit."""
20+ The unspent remainder is refunded once the batch settles — read
21+ `credits.refunded` from GET /batch/{batch_id} then.
22+ """
3723
3824
3925class Progress (BaseModel ):
40- """Current processing counts. Use `status` to check completion ."""
26+ """How far the batch got before cancellation ."""
4127
4228 failed : int
43- """Pages that could not be scraped."""
29+ """Pages that could not be scraped before the request landed ."""
4430
4531 pending : int
46- """Accepted pages not yet attempted.
47-
48- Always 0 once the batch completes; a crawl can finish under its page limit when
49- the site has no more reachable pages.
50- """
32+ """Reserved pages that will now be skipped, and refunded when the batch settles."""
5133
5234 succeeded : int
53- """Pages scraped successfully."""
54-
55-
56- class ResultsFile (BaseModel ):
57- bytes : int
58- """Compressed file size in bytes."""
59-
60- items : int
61- """Results in this file."""
62-
63- url : str
64- """Temporary URL for a gzipped NDJSON file."""
65-
66-
67- class Results (BaseModel ):
68- """Download links available when the batch finishes.
69-
70- GET /batch/{batch_id}/results serves the same records as paginated JSON.
71- """
72-
73- expires_at : str
74- """When the download URLs expire."""
75-
76- files : List [ResultsFile ]
77- """Result files. Order is not guaranteed."""
35+ """Pages scraped successfully before the request landed."""
7836
7937
8038class Timing (BaseModel ):
81- completed_at : Optional [str ] = None
82- """When processing finished. Null while active."""
39+ """There is no finish time yet — the batch is still winding down."""
8340
8441 created_at : str
8542 """When the batch was created."""
8643
8744 started_at : Optional [str ] = None
88- """When processing started. Null while queued."""
45+ """When processing started. Null if it was cancelled while still queued."""
8946
9047
9148class KeyMetadata (BaseModel ):
@@ -100,42 +57,43 @@ class KeyMetadata(BaseModel):
10057
10158class BatchCancelResponse (BaseModel ):
10259 id : str
103- """Batch ID used to retrieve or cancel the job ."""
60+ """Batch ID."""
10461
105- credits : Credits
106- """Reserved and used credits."""
62+ crawl : Optional [CrawlControls ] = None
63+ """
64+ The crawl controls as submitted, so the limits requested can be compared against
65+ what the crawl reached.
66+ """
10767
108- error : Optional [ Error ] = None
109- """Why the batch failed ."""
68+ credits : Credits
69+ """What this batch cost so far ."""
11070
111- errors : List [ ErrorCount ]
112- """Page failures grouped by error code ."""
71+ format : Literal [ "markdown" , "html" ]
72+ """What each page is returned as ."""
11373
114- input : Input
115- """Submission counts ."""
74+ input : Intake
75+ """What submission took in, and what it charged for ."""
11676
11777 mode : Literal ["scrape" , "crawl" ]
118- """How pages are selected."""
78+ """How pages were selected."""
79+
80+ page_errors : List [PageErrorCount ]
81+ """Page failures so far, grouped by error code and sorted by count."""
11982
12083 progress : Progress
121- """Current processing counts. Use `status` to check completion ."""
84+ """How far the batch got before cancellation ."""
12285
123- results : Optional [ Results ] = None
124- """Download links available when the batch finishes .
86+ status : Literal [ "cancelling" ]
87+ """Always `cancelling` .
12588
126- GET /batch/{batch_id}/results serves the same records as paginated JSON .
89+ Work already in flight finishes; the batch reaches `cancelled` shortly after .
12790 """
12891
129- status : Literal ["queued" , "running" , "cancelling" , "completed" , "cancelled" , "failed" ]
130- """Current state. `completed`, `cancelled`, and `failed` are final."""
131-
13292 tags : List [str ]
13393 """Tags stored on the batch at submission."""
13494
13595 timing : Timing
136-
137- type : Literal ["markdown" , "html" ]
138- """Output format."""
96+ """There is no finish time yet — the batch is still winding down."""
13997
14098 key_metadata : Optional [KeyMetadata ] = None
14199 """API key usage for this request."""
0 commit comments