feat(batch): accept lightweight submissions and queue pending work (#2683)

Stainless-Generated-From: 0b0a550f5865353a417dcc96713281f46d01979d

Author: stlc-bot

src/context/dev/resources/batch.py

@@ -96,7 +96,7 @@ def list(
         q: str | Omit = omit,
         search_type: Literal["exact", "prefix"] | Omit = omit,
         should_include_unified: bool | Omit = omit,
-        status: Literal["queued", "running", "cancelling", "completed", "cancelled", "failed"] | Omit = omit,
+        status: Literal["pending", "queued", "running", "cancelling", "completed", "cancelled", "failed"] | Omit = omit,
         tags: Union[str, SequenceNotStr[str]] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -305,8 +305,15 @@ def submit(
         """
         Scrape up to 100,000 URLs, or crawl a site, asynchronously using the same
         formats and scrape parameters as POST /web/scrape. Choose Markdown, HTML,
-        screenshots, images, bytes, parsed fields, products, highlights, and JSON. Poll
-        the batch ID or receive a webhook when it finishes.
+        screenshots, images, bytes, parsed fields, products, highlights, and JSON.
+        Submission persists the input and returns immediately with status pending.
+        Organizations with fewer than 10 available credits and no overage are rejected
+        with 402 up front. Each organization can submit up to 1,000 batches per minute,
+        independently of its polling budget. Batches wait pending when execution
+        capacity is full. Validation, sitemap discovery, the full credit quote, and
+        shard scheduling happen afterward. Poll the batch ID or receive a webhook when
+        it finishes. Deferred rejections appear as status failed with a failure code and
+        message.
 
         Args:
           input: Choose a URL list or a site crawl.
@@ -419,7 +426,7 @@ async def list(
         q: str | Omit = omit,
         search_type: Literal["exact", "prefix"] | Omit = omit,
         should_include_unified: bool | Omit = omit,
-        status: Literal["queued", "running", "cancelling", "completed", "cancelled", "failed"] | Omit = omit,
+        status: Literal["pending", "queued", "running", "cancelling", "completed", "cancelled", "failed"] | Omit = omit,
         tags: Union[str, SequenceNotStr[str]] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -628,8 +635,15 @@ async def submit(
         """
         Scrape up to 100,000 URLs, or crawl a site, asynchronously using the same
         formats and scrape parameters as POST /web/scrape. Choose Markdown, HTML,
-        screenshots, images, bytes, parsed fields, products, highlights, and JSON. Poll
-        the batch ID or receive a webhook when it finishes.
+        screenshots, images, bytes, parsed fields, products, highlights, and JSON.
+        Submission persists the input and returns immediately with status pending.
+        Organizations with fewer than 10 available credits and no overage are rejected
+        with 402 up front. Each organization can submit up to 1,000 batches per minute,
+        independently of its polling budget. Batches wait pending when execution
+        capacity is full. Validation, sitemap discovery, the full credit quote, and
+        shard scheduling happen afterward. Poll the batch ID or receive a webhook when
+        it finishes. Deferred rejections appear as status failed with a failure code and
+        message.
 
         Args:
           input: Choose a URL list or a site crawl.

src/context/dev/types/batch_list_params.py

@@ -33,7 +33,7 @@ class BatchListParams(TypedDict, total=False):
     should_include_unified: Annotated[bool, PropertyInfo(alias="shouldIncludeUnified")]
     """Include batches submitted with Scrape Anything formats. Defaults to false."""
 
-    status: Literal["queued", "running", "cancelling", "completed", "cancelled", "failed"]
+    status: Literal["pending", "queued", "running", "cancelling", "completed", "cancelled", "failed"]
     """Filter by status."""
 
     tags: Union[str, SequenceNotStr[str]]

src/context/dev/types/batch_list_response.py

@@ -37,7 +37,10 @@ class DataCredits(BaseModel):
     """Credits returned for unsuccessful pages when the batch settles."""
 
     reserved: int
-    """Credits held when the batch was accepted."""
+    """Credits held by background preparation before scraping starts.
+
+    Zero while pending.
+    """
 
 
 class DataFormats(BaseModel):
@@ -167,8 +170,13 @@ class Data(BaseModel):
     Files are deleted 180 days after the batch finishes.
     """
 
-    status: Literal["queued", "running", "cancelling", "completed", "cancelled", "failed"]
-    """Current state. `completed`, `cancelled`, and `failed` are final."""
+    status: Literal["pending", "queued", "running", "cancelling", "completed", "cancelled", "failed"]
+    """Current state.
+
+    `pending` means waiting for execution capacity or background validation.
+    Capacity-limited batches remain pending until a slot opens. `completed`,
+    `cancelled`, and `failed` are final.
+    """
 
     tags: List[str]
     """Tags stored on the batch at submission."""

src/context/dev/types/batch_retrieve_response.py

@@ -37,7 +37,10 @@ class Credits(BaseModel):
     """Credits returned for unsuccessful pages when the batch settles."""
 
     reserved: int
-    """Credits held when the batch was accepted."""
+    """Credits held by background preparation before scraping starts.
+
+    Zero while pending.
+    """
 
 
 class Formats(BaseModel):
@@ -192,8 +195,13 @@ class BatchRetrieveResponse(BaseModel):
     Files are deleted 180 days after the batch finishes.
     """
 
-    status: Literal["queued", "running", "cancelling", "completed", "cancelled", "failed"]
-    """Current state. `completed`, `cancelled`, and `failed` are final."""
+    status: Literal["pending", "queued", "running", "cancelling", "completed", "cancelled", "failed"]
+    """Current state.
+
+    `pending` means waiting for execution capacity or background validation.
+    Capacity-limited batches remain pending until a slot opens. `completed`,
+    `cancelled`, and `failed` are final.
+    """
 
     tags: List[str]
     """Tags stored on the batch at submission."""

src/context/dev/types/batch_submit_response.py

@@ -26,10 +26,10 @@ class CacheMetadata(BaseModel):
 
 
 class Credits(BaseModel):
-    """What accepting this batch cost."""
+    """Credits are reserved after background validation, before scraping starts."""
 
     reserved: int
-    """Credits held at submission."""
+    """Credits reserved by background preparation. Zero while pending."""
 
 
 class Formats(BaseModel):
@@ -98,7 +98,7 @@ class BatchSubmitResponse(BaseModel):
     """When the batch was created."""
 
     credits: Credits
-    """What accepting this batch cost."""
+    """Credits are reserved after background validation, before scraping starts."""
 
     formats: Formats
     """Outputs requested for each page. Matches input.data.formats on submission."""
@@ -118,8 +118,13 @@ class BatchSubmitResponse(BaseModel):
     Include it when contacting support.
     """
 
-    status: Literal["queued"]
-    """Always `queued`. An accepted batch has not started yet."""
+    status: Literal["pending", "queued", "running", "cancelling", "completed", "cancelled", "failed"]
+    """Current state.
+
+    `pending` means waiting for execution capacity or background validation.
+    Capacity-limited batches remain pending until a slot opens. `completed`,
+    `cancelled`, and `failed` are final.
+    """
 
     tags: List[str]
     """Tags stored on the batch."""

tests/api_resources/test_batch.py

@@ -81,7 +81,7 @@ def test_method_list_with_all_params(self, client: ContextDev) -> None:
             q="batch_1a2b",
             search_type="exact",
             should_include_unified=True,
-            status="queued",
+            status="pending",
             tags="docs,competitor",
         )
         assert_matches_type(BatchListResponse, batch, path=["response"])
@@ -495,7 +495,7 @@ async def test_method_list_with_all_params(self, async_client: AsyncContextDev)
             q="batch_1a2b",
             search_type="exact",
             should_include_unified=True,
-            status="queued",
+            status="pending",
             tags="docs,competitor",
         )
         assert_matches_type(BatchListResponse, batch, path=["response"])