feat(api): api update

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 36
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-c7625b4a7beb9e7d9827f3b836e6539cbc5f26b6754891d4352716e38cdecd73.yml
-openapi_spec_hash: cbee9cf164cc6704a6febb4d9737e83e
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/context-dev/context.dev-09b6020939995033719a53b988fb00bdb20c42d87070975a8d6b469fa18128fb.yml
+openapi_spec_hash: ba3e471937a679e2c45c0b9a115fca5c
 config_hash: 7ec4851ee8d93177947e95df5ae897b5

src/context/dev/resources/monitors.py

@@ -267,6 +267,12 @@ def list(
           search_type: `prefix` for as-you-type prefix matching (default), `exact` for full-token
               matching.
 
+          status: Monitor lifecycle status. `failed` means the most recent run failed (see the
+              monitor's `last_error`); failed monitors keep running on schedule and flip back
+              to `active` on the next successful run. Monitors are auto-`paused` after
+              repeated consecutive failures or insufficient-credit skips; resume by PATCHing
+              status to `active`.
+
           tag: Filter to items that have this tag.
 
           tags: Comma-separated list of tags to filter by (matches monitors having any of them).
@@ -399,7 +405,7 @@ def list_account_runs(
         *,
         cursor: str | Omit = omit,
         limit: int | Omit = omit,
-        status: Literal["queued", "running", "completed", "failed"] | Omit = omit,
+        status: Literal["queued", "running", "completed", "failed", "skipped"] | 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.
         extra_headers: Headers | None = None,
@@ -411,6 +417,9 @@ def list_account_runs(
         Returns an account-wide feed of monitor runs across all monitors.
 
         Args:
+          status: Lifecycle status of a run. `skipped` runs never executed — see `skip_reason`
+              (insufficient credits, monitor paused, or superseded by a concurrent run).
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -497,18 +506,22 @@ def list_runs(
         *,
         cursor: str | Omit = omit,
         limit: int | Omit = omit,
-        status: Literal["queued", "running", "completed", "failed"] | Omit = omit,
+        status: Literal["queued", "running", "completed", "failed", "skipped"] | 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.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> MonitorListRunsResponse:
-        """
-        List monitor runs
+        """List monitor runs
 
         Args:
+          status: Lifecycle status of a run.
+
+        `skipped` runs never executed — see `skip_reason`
+              (insufficient credits, monitor paused, or superseded by a concurrent run).
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -831,6 +844,12 @@ async def list(
           search_type: `prefix` for as-you-type prefix matching (default), `exact` for full-token
               matching.
 
+          status: Monitor lifecycle status. `failed` means the most recent run failed (see the
+              monitor's `last_error`); failed monitors keep running on schedule and flip back
+              to `active` on the next successful run. Monitors are auto-`paused` after
+              repeated consecutive failures or insufficient-credit skips; resume by PATCHing
+              status to `active`.
+
           tag: Filter to items that have this tag.
 
           tags: Comma-separated list of tags to filter by (matches monitors having any of them).
@@ -963,7 +982,7 @@ async def list_account_runs(
         *,
         cursor: str | Omit = omit,
         limit: int | Omit = omit,
-        status: Literal["queued", "running", "completed", "failed"] | Omit = omit,
+        status: Literal["queued", "running", "completed", "failed", "skipped"] | 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.
         extra_headers: Headers | None = None,
@@ -975,6 +994,9 @@ async def list_account_runs(
         Returns an account-wide feed of monitor runs across all monitors.
 
         Args:
+          status: Lifecycle status of a run. `skipped` runs never executed — see `skip_reason`
+              (insufficient credits, monitor paused, or superseded by a concurrent run).
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -1061,18 +1083,22 @@ async def list_runs(
         *,
         cursor: str | Omit = omit,
         limit: int | Omit = omit,
-        status: Literal["queued", "running", "completed", "failed"] | Omit = omit,
+        status: Literal["queued", "running", "completed", "failed", "skipped"] | 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.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
     ) -> MonitorListRunsResponse:
-        """
-        List monitor runs
+        """List monitor runs
 
         Args:
+          status: Lifecycle status of a run.
+
+        `skipped` runs never executed — see `skip_reason`
+              (insufficient credits, monitor paused, or superseded by a concurrent run).
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request

src/context/dev/types/monitor_create_params.py

@@ -105,7 +105,10 @@ class TargetMonitorsPageTarget(TypedDict, total=False):
 
 
 class TargetMonitorsSitemapTarget(TypedDict, total=False):
-    """Watch a sitemap for URL additions and removals."""
+    """Watch a sitemap for URL additions and removals.
+
+    Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. A new URL set must be observed on two consecutive runs before a change is reported, suppressing one-run crawl flaps.
+    """
 
     type: Required[Literal["sitemap"]]
 
@@ -119,6 +122,7 @@ class TargetMonitorsSitemapTarget(TypedDict, total=False):
     """URL path patterns to include."""
 
     max_urls: int
+    """Maximum number of sitemap URLs to track (capped at 10,000)."""
 
 
 class TargetMonitorsExtractTarget(TypedDict, total=False):

src/context/dev/types/monitor_create_response.py

@@ -19,6 +19,7 @@
     "TargetMonitorsPageTarget",
     "TargetMonitorsSitemapTarget",
     "TargetMonitorsExtractTarget",
+    "LastError",
     "Webhook",
 ]
 
@@ -79,7 +80,10 @@ class TargetMonitorsPageTarget(BaseModel):
 
 
 class TargetMonitorsSitemapTarget(BaseModel):
-    """Watch a sitemap for URL additions and removals."""
+    """Watch a sitemap for URL additions and removals.
+
+    Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. A new URL set must be observed on two consecutive runs before a change is reported, suppressing one-run crawl flaps.
+    """
 
     type: Literal["sitemap"]
 
@@ -93,6 +97,7 @@ class TargetMonitorsSitemapTarget(BaseModel):
     """URL path patterns to include."""
 
     max_urls: Optional[int] = None
+    """Maximum number of sitemap URLs to track (capped at 10,000)."""
 
 
 class TargetMonitorsExtractTarget(BaseModel):
@@ -127,6 +132,14 @@ class TargetMonitorsExtractTarget(BaseModel):
 ]
 
 
+class LastError(BaseModel):
+    """Error from the most recent failed run; null when the last run succeeded."""
+
+    code: str
+
+    message: str
+
+
 class Webhook(BaseModel):
     url: str
     """Webhook URL called when a change is detected."""
@@ -171,6 +184,13 @@ class MonitorCreateResponse(BaseModel):
     """
 
     status: Literal["active", "paused", "failed"]
+    """Monitor lifecycle status.
+
+    `failed` means the most recent run failed (see the monitor's `last_error`);
+    failed monitors keep running on schedule and flip back to `active` on the next
+    successful run. Monitors are auto-`paused` after repeated consecutive failures
+    or insufficient-credit skips; resume by PATCHing status to `active`.
+    """
 
     target: Target
     """Discriminated union describing what the monitor watches."""
@@ -179,8 +199,14 @@ class MonitorCreateResponse(BaseModel):
 
     last_change_at: Optional[datetime] = None
 
+    last_error: Optional[LastError] = None
+    """Error from the most recent failed run; null when the last run succeeded."""
+
     last_run_at: Optional[datetime] = None
 
+    next_run_at: Optional[datetime] = None
+    """When the next scheduled run is due."""
+
     tags: Optional[List[str]] = None
     """User-defined tags for grouping and filtering monitors and their changes."""
 

src/context/dev/types/monitor_list_account_runs_params.py

@@ -12,4 +12,9 @@ class MonitorListAccountRunsParams(TypedDict, total=False):
 
     limit: int
 
-    status: Literal["queued", "running", "completed", "failed"]
+    status: Literal["queued", "running", "completed", "failed", "skipped"]
+    """Lifecycle status of a run.
+
+    `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor
+    paused, or superseded by a concurrent run).
+    """

src/context/dev/types/monitor_list_account_runs_response.py

@@ -28,12 +28,20 @@ class Data(BaseModel):
 
     change_detection_type: Literal["exact", "semantic"]
 
+    credits_charged: int
+    """Credits charged for this run (0 for skipped/failed runs)."""
+
     monitor_id: str
 
     run_type: Literal["baseline", "scheduled"]
     """The first run after monitor creation is a baseline run."""
 
-    status: Literal["queued", "running", "completed", "failed"]
+    status: Literal["queued", "running", "completed", "failed", "skipped"]
+    """Lifecycle status of a run.
+
+    `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor
+    paused, or superseded by a concurrent run).
+    """
 
     target_type: Literal["page", "sitemap", "extract"]
 
@@ -43,6 +51,9 @@ class Data(BaseModel):
 
     error: Optional[DataError] = None
 
+    skip_reason: Optional[Literal["insufficient_credits", "monitor_paused", "superseded"]] = None
+    """Why a skipped run never executed; null unless status is `skipped`."""
+
     started_at: Optional[datetime] = None
 
 

src/context/dev/types/monitor_list_params.py

@@ -33,6 +33,13 @@ class MonitorListParams(TypedDict, total=False):
     """
 
     status: Literal["active", "paused", "failed"]
+    """Monitor lifecycle status.
+
+    `failed` means the most recent run failed (see the monitor's `last_error`);
+    failed monitors keep running on schedule and flip back to `active` on the next
+    successful run. Monitors are auto-`paused` after repeated consecutive failures
+    or insufficient-credit skips; resume by PATCHing status to `active`.
+    """
 
     tag: str
     """Filter to items that have this tag."""

src/context/dev/types/monitor_list_response.py

@@ -20,6 +20,7 @@
     "DataTargetMonitorsPageTarget",
     "DataTargetMonitorsSitemapTarget",
     "DataTargetMonitorsExtractTarget",
+    "DataLastError",
     "DataWebhook",
 ]
 
@@ -80,7 +81,10 @@ class DataTargetMonitorsPageTarget(BaseModel):
 
 
 class DataTargetMonitorsSitemapTarget(BaseModel):
-    """Watch a sitemap for URL additions and removals."""
+    """Watch a sitemap for URL additions and removals.
+
+    Crawled URLs are normalized (lowercased host, no trailing slash/fragment) and scoped to the monitored site and its subdomains before comparison. A new URL set must be observed on two consecutive runs before a change is reported, suppressing one-run crawl flaps.
+    """
 
     type: Literal["sitemap"]
 
@@ -94,6 +98,7 @@ class DataTargetMonitorsSitemapTarget(BaseModel):
     """URL path patterns to include."""
 
     max_urls: Optional[int] = None
+    """Maximum number of sitemap URLs to track (capped at 10,000)."""
 
 
 class DataTargetMonitorsExtractTarget(BaseModel):
@@ -128,6 +133,14 @@ class DataTargetMonitorsExtractTarget(BaseModel):
 ]
 
 
+class DataLastError(BaseModel):
+    """Error from the most recent failed run; null when the last run succeeded."""
+
+    code: str
+
+    message: str
+
+
 class DataWebhook(BaseModel):
     url: str
     """Webhook URL called when a change is detected."""
@@ -172,6 +185,13 @@ class Data(BaseModel):
     """
 
     status: Literal["active", "paused", "failed"]
+    """Monitor lifecycle status.
+
+    `failed` means the most recent run failed (see the monitor's `last_error`);
+    failed monitors keep running on schedule and flip back to `active` on the next
+    successful run. Monitors are auto-`paused` after repeated consecutive failures
+    or insufficient-credit skips; resume by PATCHing status to `active`.
+    """
 
     target: DataTarget
     """Discriminated union describing what the monitor watches."""
@@ -180,8 +200,14 @@ class Data(BaseModel):
 
     last_change_at: Optional[datetime] = None
 
+    last_error: Optional[DataLastError] = None
+    """Error from the most recent failed run; null when the last run succeeded."""
+
     last_run_at: Optional[datetime] = None
 
+    next_run_at: Optional[datetime] = None
+    """When the next scheduled run is due."""
+
     tags: Optional[List[str]] = None
     """User-defined tags for grouping and filtering monitors and their changes."""
 

src/context/dev/types/monitor_list_runs_params.py

@@ -12,4 +12,9 @@ class MonitorListRunsParams(TypedDict, total=False):
 
     limit: int
 
-    status: Literal["queued", "running", "completed", "failed"]
+    status: Literal["queued", "running", "completed", "failed", "skipped"]
+    """Lifecycle status of a run.
+
+    `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor
+    paused, or superseded by a concurrent run).
+    """

src/context/dev/types/monitor_list_runs_response.py

@@ -28,12 +28,20 @@ class Data(BaseModel):
 
     change_detection_type: Literal["exact", "semantic"]
 
+    credits_charged: int
+    """Credits charged for this run (0 for skipped/failed runs)."""
+
     monitor_id: str
 
     run_type: Literal["baseline", "scheduled"]
     """The first run after monitor creation is a baseline run."""
 
-    status: Literal["queued", "running", "completed", "failed"]
+    status: Literal["queued", "running", "completed", "failed", "skipped"]
+    """Lifecycle status of a run.
+
+    `skipped` runs never executed — see `skip_reason` (insufficient credits, monitor
+    paused, or superseded by a concurrent run).
+    """
 
     target_type: Literal["page", "sitemap", "extract"]
 
@@ -43,6 +51,9 @@ class Data(BaseModel):
 
     error: Optional[DataError] = None
 
+    skip_reason: Optional[Literal["insufficient_credits", "monitor_paused", "superseded"]] = None
+    """Why a skipped run never executed; null unless status is `skipped`."""
+
     started_at: Optional[datetime] = None