scrapely-client-python 1.0.10__tar.gz → 1.0.12__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/CHANGELOG.md +10 -0
  2. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/PKG-INFO +1 -1
  3. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/pyproject.toml +3 -3
  4. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/pyproject.toml.orig +3 -3
  5. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/__init__.py +4 -0
  6. scrapely_client_python-1.0.12/src/scrapely_client/_credit_unlock.py +64 -0
  7. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_literals.py +16 -0
  8. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_models.py +124 -1
  9. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/run.py +9 -2
  10. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/http_clients/_impit.py +18 -2
  11. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/CONTRIBUTING.md +0 -0
  12. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/LICENSE +0 -0
  13. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/NOTICE +0 -0
  14. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/README.md +0 -0
  15. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_charging.py +0 -0
  16. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_client_registry.py +0 -0
  17. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_consts.py +0 -0
  18. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_docs.py +0 -0
  19. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_logging.py +0 -0
  20. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_pagination.py +0 -0
  21. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/__init__.py +0 -0
  22. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/_resource_client.py +0 -0
  23. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/actor.py +0 -0
  24. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/actor_collection.py +0 -0
  25. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/actor_env_var.py +0 -0
  26. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/actor_env_var_collection.py +0 -0
  27. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/actor_version.py +0 -0
  28. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/actor_version_collection.py +0 -0
  29. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/automation.py +0 -0
  30. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/automation_collection.py +0 -0
  31. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/build.py +0 -0
  32. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/build_collection.py +0 -0
  33. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/dataset.py +0 -0
  34. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/dataset_collection.py +0 -0
  35. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/key_value_store.py +0 -0
  36. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/key_value_store_collection.py +0 -0
  37. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/log.py +0 -0
  38. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/request_queue.py +0 -0
  39. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/request_queue_collection.py +0 -0
  40. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/run_collection.py +0 -0
  41. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/schedule.py +0 -0
  42. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/schedule_collection.py +0 -0
  43. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/store_collection.py +0 -0
  44. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/task.py +0 -0
  45. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/task_collection.py +0 -0
  46. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/user.py +0 -0
  47. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/webhook.py +0 -0
  48. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/webhook_collection.py +0 -0
  49. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/webhook_dispatch.py +0 -0
  50. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_resource_clients/webhook_dispatch_collection.py +0 -0
  51. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_scrapely_client.py +0 -0
  52. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_statistics.py +0 -0
  53. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_status_message_watcher.py +0 -0
  54. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_streamed_log.py +0 -0
  55. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_typeddicts.py +0 -0
  56. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_utils/__init__.py +0 -0
  57. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_utils/crypto.py +0 -0
  58. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_utils/encoding.py +0 -0
  59. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_utils/errors.py +0 -0
  60. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_utils/http.py +0 -0
  61. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_utils/time.py +0 -0
  62. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/_utils/try_import.py +0 -0
  63. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/errors.py +0 -0
  64. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/http_clients/__init__.py +0 -0
  65. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/http_clients/_base.py +0 -0
  66. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/http_compressors/__init__.py +0 -0
  67. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/http_compressors/_base.py +0 -0
  68. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/http_compressors/_brotli.py +0 -0
  69. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/http_compressors/_gzip.py +0 -0
  70. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/http_compressors/_resolve.py +0 -0
  71. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/py.typed +0 -0
  72. {scrapely_client_python-1.0.10 → scrapely_client_python-1.0.12}/src/scrapely_client/types.py +0 -0
@@ -2,6 +2,16 @@
2
2
 
3
3
  All notable changes to this project will be documented in this file.
4
4
 
5
+ ## [1.0.12] - 2026-11-06
6
+
7
+ - Out of credit: the API's 402 for the account balance keeps its type and status and now carries the way out in `error.data` (`ApifyApiError.data`, model `InsufficientCreditErrorData`): a Free account gets `unlock` (Starter, its price and credit, and `checkoutUrl`), a paid account `topUpUrl`, plus the account's newest held run (`heldItems`, `heldUntil`, `runId`). `is_insufficient_credit_error(err)` and `credit_unlock_url(err)` read it.
8
+ - `Run.held` (`RunHeld`): results a run found after the free credit ran out, kept out of its dataset until unlocked. All `RunHeld` / `CreditUnlock` fields are optional, so a partial object never fails `Run.model_validate`. `RunClient.wait_for_finish()` (and so `ActorClient.call()` / `TaskClient.call()`, sync and async) logs one warning with the count and the unlock link when the run has held results.
9
+ - Models regenerated from the updated specification (`scrapely-v2-2026-11-06`), which also picks up the current run retention text of `UpdateLimitsRequest.data_retention_days`.
10
+
11
+ ## [1.0.11] - 2026-11-04
12
+
13
+ - The API now sends its own 502 and 504 answers as 503 with the original status in the `X-Scrapely-Status` header (so the error body reaches you through Cloudflare). A 503 with `X-Scrapely-Status: 504` is treated like a 504: a POST or PATCH without an `Idempotency-Key` is not resent after it, since it may already have been applied. A 503 with `X-Scrapely-Status: 502` is retried like a 502.
14
+
5
15
  ## [1.0.10] - 2026-11-02
6
16
 
7
17
  - Run starts (`ActorClient.start` / `call`, `TaskClient.start` / `call`), `ActorClient.build` and `DatasetClient.push_items` send an `Idempotency-Key` header, so a request resent after a 5xx or a dropped connection starts one run or build and stores the items once.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: scrapely-client-python
3
- Version: 1.0.10
3
+ Version: 1.0.12
4
4
  Summary: Scrapely API client for Python
5
5
  Keywords: scrapely,api,client,automation,crawling,scraping
6
6
  Author: TeraShift GmbH (Scrape.ly)
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "scrapely-client-python"
7
- version = "1.0.10"
7
+ version = "1.0.12"
8
8
  description = "Scrapely API client for Python"
9
9
  license = "Apache-2.0"
10
10
  license-files = [
@@ -262,8 +262,8 @@ disable_timestamp = true
262
262
  keep_model_order = true
263
263
 
264
264
  [tool.scrapely.openapi-spec]
265
- version = "scrapely-v2-2026-10-20"
266
- sha256 = "0913387f7deb9064489d43ec9aa345439ce3cfa96b5f29748f46220a65c9fe5e"
265
+ version = "scrapely-v2-2026-11-06"
266
+ sha256 = "f0fe68f5c2313c531f652394366ab6e372646d697eba4b4960b2f9e463572c17"
267
267
 
268
268
  [tool.uv]
269
269
  exclude-newer = "24 hours"
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "scrapely-client-python"
7
- version = "1.0.10"
7
+ version = "1.0.12"
8
8
  description = "Scrapely API client for Python"
9
9
  authors = [{ name = "TeraShift GmbH (Scrape.ly)" }]
10
10
  license = "Apache-2.0"
@@ -251,8 +251,8 @@ keep_model_order = true
251
251
  # `poe generate-models`. `poe generate-models` refuses to run when the file doesn't match this hash; after reviewing
252
252
  # a change to the specification, record it with `poe accept-openapi-spec` (written by `scripts/openapi_spec.py`).
253
253
  [tool.scrapely.openapi-spec]
254
- version = "scrapely-v2-2026-10-20"
255
- sha256 = "0913387f7deb9064489d43ec9aa345439ce3cfa96b5f29748f46220a65c9fe5e"
254
+ version = "scrapely-v2-2026-11-06"
255
+ sha256 = "f0fe68f5c2313c531f652394366ab6e372646d697eba4b4960b2f9e463572c17"
256
256
 
257
257
  [tool.uv]
258
258
  # Minimal defense against supply-chain atatcks.
@@ -10,6 +10,7 @@ from ._charging import (
10
10
  normalize_items,
11
11
  push_data_charging_context,
12
12
  )
13
+ from ._credit_unlock import credit_unlock_url, held_run_warning, is_insufficient_credit_error
13
14
  from ._scrapely_client import ApifyClient, ApifyClientAsync, ScrapelyClient, ScrapelyClientAsync
14
15
 
15
16
  try:
@@ -27,6 +28,9 @@ __all__ = [
27
28
  'ScrapelyClient',
28
29
  'ScrapelyClientAsync',
29
30
  '__version__',
31
+ 'credit_unlock_url',
32
+ 'held_run_warning',
33
+ 'is_insufficient_credit_error',
30
34
  'normalize_items',
31
35
  'push_data_charging_context',
32
36
  ]
@@ -0,0 +1,64 @@
1
+ # Scrape.ly addition (TeraShift GmbH): "out of credit" data of the API.
2
+ """Read the unlock data of an "out of credit" answer and warn about held results.
3
+
4
+ When the account's free credit runs out, the API answers run starts (and other paid requests) with HTTP 402 and puts
5
+ the way out in `error.data` (`ApifyApiError.data`): `unlock` (the Starter offer and its `checkoutUrl`) for a Free
6
+ account, `topUpUrl` for a paid one, and the account's newest held run (`heldItems`, `heldUntil`, `runId`). A run
7
+ that went on finding results after the credit ran out has `held` (`RunHeld`): the results are kept out of its
8
+ dataset until the account unlocks them.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from typing import TYPE_CHECKING, Any
14
+
15
+ from scrapely_client._logging import logger
16
+
17
+ if TYPE_CHECKING:
18
+ from scrapely_client._models import Run
19
+
20
+ CREDIT_REASONS = frozenset({'insufficient-credit', 'insufficient-funds'})
21
+ PAYMENT_REQUIRED_STATUS = 402
22
+
23
+
24
+ def is_insufficient_credit_error(err: BaseException | Any) -> bool:
25
+ """Whether `err` is the API's HTTP 402 for the account balance (its unlock data is in `err.data`)."""
26
+ data = getattr(err, 'data', None)
27
+ return (
28
+ getattr(err, 'status_code', None) == PAYMENT_REQUIRED_STATUS
29
+ and isinstance(data, dict)
30
+ and data.get('reason') in CREDIT_REASONS
31
+ )
32
+
33
+
34
+ def credit_unlock_url(err: BaseException | Any) -> str | None:
35
+ """Return the link to show the user for a 402 for the balance: the unlock checkout, else the top-up page."""
36
+ if not is_insufficient_credit_error(err):
37
+ return None
38
+ data = getattr(err, 'data', None) or {}
39
+ unlock = data.get('unlock')
40
+ url = unlock.get('checkoutUrl') if isinstance(unlock, dict) else None
41
+ url = url or data.get('topUpUrl')
42
+ return url if isinstance(url, str) and url else None
43
+
44
+
45
+ def held_run_warning(run: Run | None) -> str | None:
46
+ """Return one warning line for a run with held results that can still be unlocked, else None."""
47
+ if run is None:
48
+ return None
49
+ held = run.held
50
+ n = held.items if held is not None else None
51
+ if held is None or not n or n <= 0 or held.status not in ('holding', 'held'):
52
+ return None
53
+ until = f' until {held.held_until.isoformat().replace("+00:00", "Z")}' if held.held_until else ''
54
+ checkout_url = held.unlock.checkout_url if held.unlock is not None else None
55
+ link = f' Unlock them: {checkout_url}' if checkout_url else ''
56
+ noun = 'result is' if n == 1 else 'results are'
57
+ return f'Run {run.id}: your free credit ran out, so {n:,} more {noun} held{until}.{link}'
58
+
59
+
60
+ def warn_if_held(run: Run | None) -> None:
61
+ """Log `held_run_warning(run)` when there is one."""
62
+ warning = held_run_warning(run)
63
+ if warning:
64
+ logger.warning(warning)
@@ -120,6 +120,7 @@ ErrorType = (
120
120
  'cannot-unpublish-paid-actor',
121
121
  'cannot-unpublish-profile',
122
122
  'cannot-update-invoice-field',
123
+ 'charge-limit-exceeded',
123
124
  'concurrent-runs-limit-exceeded',
124
125
  'concurrent-update-detected',
125
126
  'conference-token-not-found',
@@ -177,6 +178,8 @@ ErrorType = (
177
178
  'input-json-not-object',
178
179
  'input-json-too-long',
179
180
  'input-update-collision',
181
+ 'insufficient-balance',
182
+ 'insufficient-funds',
180
183
  'insufficient-permissions',
181
184
  'insufficient-permissions-to-change-field',
182
185
  'insufficient-security-measures',
@@ -295,6 +298,7 @@ ErrorType = (
295
298
  'password-reset-token-expired',
296
299
  'pay-as-you-go-without-monthly-interval',
297
300
  'payment-attempt-status-message-required',
301
+ 'payment-required',
298
302
  'payout-already-paid',
299
303
  'payout-canceled',
300
304
  'payout-invalid-state',
@@ -489,6 +493,18 @@ SourceCodeFileFormat = (
489
493
  )
490
494
 
491
495
 
496
+ Status = (
497
+ Literal[
498
+ 'holding',
499
+ 'held',
500
+ 'released',
501
+ 'expired',
502
+ ]
503
+ | str
504
+ )
505
+ """`holding` (run running), `held`, `released` (now in the dataset) or `expired`."""
506
+
507
+
492
508
  StorageOwnership = (
493
509
  Literal[
494
510
  'ownedByMe',
@@ -19,6 +19,7 @@ from scrapely_client._literals import (
19
19
  HttpMethod,
20
20
  RunOrigin,
21
21
  SourceCodeFileFormat,
22
+ Status,
22
23
  VersionSourceType,
23
24
  WebhookDispatchStatus,
24
25
  WebhookEventType,
@@ -883,6 +884,43 @@ class CreateTaskRequest(BaseModel):
883
884
  seo_description: str | None = None
884
885
 
885
886
 
887
+ @docs_group('Models')
888
+ class CreditUnlock(BaseModel):
889
+ """The plan that unlocks held results, or lets an account whose free credit is used up keep running. Prices come from the platform's plan table."""
890
+
891
+ model_config = ConfigDict(
892
+ extra='allow',
893
+ populate_by_name=True,
894
+ alias_generator=to_camel,
895
+ )
896
+ plan: Annotated[str | None, Field(examples=['starter'])] = None
897
+ """
898
+ Plan id.
899
+ """
900
+ plan_name: Annotated[str | None, Field(examples=['Starter'])] = None
901
+ """
902
+ Plan name.
903
+ """
904
+ price_usd: Annotated[float | None, Field(examples=[19])] = None
905
+ """
906
+ Price of one plan period (4 weeks) in USD.
907
+ """
908
+ credit_usd: Annotated[float | None, Field(examples=[19])] = None
909
+ """
910
+ Credit the plan grants every period, in USD.
911
+ """
912
+ held_items_cost_usd: Annotated[float | None, Field(examples=[0.48])] = None
913
+ """
914
+ What the run's held results cost out of that credit (run `held.unlock` only).
915
+ """
916
+ checkout_url: Annotated[
917
+ str | None, Field(examples=['https://my.scrape.ly/runs/HG7ML7M8z78YcAPEB?unlock=starter'])
918
+ ] = None
919
+ """
920
+ Console link that opens the checkout. It carries no token; the console asks for the user's login.
921
+ """
922
+
923
+
886
924
  @docs_group('Models')
887
925
  class Current(BaseModel):
888
926
  model_config = ConfigDict(
@@ -1359,6 +1397,10 @@ class ErrorDetail(BaseModel):
1359
1397
  """
1360
1398
  Human-readable error message describing what went wrong.
1361
1399
  """
1400
+ data: dict[str, Any] | None = None
1401
+ """
1402
+ Additional data about the error; for an HTTP 402 for the balance see InsufficientCreditErrorData.
1403
+ """
1362
1404
 
1363
1405
 
1364
1406
  @docs_group('Models')
@@ -1493,6 +1535,46 @@ class HeadResponse(BaseModel):
1493
1535
  data: RequestQueueHead
1494
1536
 
1495
1537
 
1538
+ @docs_group('Models')
1539
+ class InsufficientCreditErrorData(BaseModel):
1540
+ """`error.data` of an HTTP 402 for the account balance."""
1541
+
1542
+ model_config = ConfigDict(
1543
+ extra='allow',
1544
+ populate_by_name=True,
1545
+ alias_generator=to_camel,
1546
+ )
1547
+ reason: Annotated[str | None, Field(examples=['insufficient-credit'])] = None
1548
+ """
1549
+ `insufficient-credit` (the run's own charge route keeps `insufficient-funds`).
1550
+ """
1551
+ plan: Annotated[str | None, Field(examples=['free'])] = None
1552
+ """
1553
+ The account's plan id.
1554
+ """
1555
+ unlock: CreditUnlock | None = None
1556
+ """
1557
+ The Starter offer for a Free account; null for a paid account.
1558
+ """
1559
+ top_up_url: str | None = None
1560
+ """
1561
+ A paid account's billing page, to add credit.
1562
+ """
1563
+ held_items: int | None = None
1564
+ """
1565
+ Held results of the account's newest held run.
1566
+ """
1567
+ held_until: AwareDatetime | None = None
1568
+ run_id: str | None = None
1569
+ """
1570
+ That held run.
1571
+ """
1572
+ kyc_url: str | None = None
1573
+ """
1574
+ Set when the account's free credit waits for identity verification.
1575
+ """
1576
+
1577
+
1496
1578
  @docs_group('Models')
1497
1579
  class InvalidItem(BaseModel):
1498
1580
  model_config = ConfigDict(
@@ -2987,6 +3069,47 @@ class Run(BaseModel):
2987
3069
  """
2988
3070
  Indicates which party covers platform usage costs for this run.
2989
3071
  """
3072
+ held: RunHeld | None = None
3073
+ """
3074
+ Results held because the account's free credit ran out (owner only; absent when nothing is held).
3075
+ """
3076
+
3077
+
3078
+ @docs_group('Models')
3079
+ class RunHeld(BaseModel):
3080
+ """Results the run found after the account's free credit ran out. They are kept out of the run's dataset until the account unlocks them or `heldUntil` passes. Only on the owner's run. Every field is optional: a partial object never fails the run."""
3081
+
3082
+ model_config = ConfigDict(
3083
+ extra='allow',
3084
+ populate_by_name=True,
3085
+ alias_generator=to_camel,
3086
+ )
3087
+ status: Status | None = None
3088
+ """
3089
+ `holding` (run running), `held`, `released` (now in the dataset) or `expired`.
3090
+ """
3091
+ items: Annotated[int | None, Field(examples=[1653])] = None
3092
+ """
3093
+ Number of held results.
3094
+ """
3095
+ events: dict[str, int] | None = None
3096
+ """
3097
+ Held charge events by event name.
3098
+ """
3099
+ saved_items: Annotated[int | None, Field(examples=[1347])] = None
3100
+ """
3101
+ Results saved to the dataset before the credit ran out.
3102
+ """
3103
+ held_until: AwareDatetime | None = None
3104
+ """
3105
+ When the held results are deleted unless unlocked.
3106
+ """
3107
+ released_at: AwareDatetime | None = None
3108
+ expired_at: AwareDatetime | None = None
3109
+ unlock: CreditUnlock | None = None
3110
+ """
3111
+ How to unlock them.
3112
+ """
2990
3113
 
2991
3114
 
2992
3115
  @docs_group('Models')
@@ -3763,7 +3886,7 @@ class UpdateLimitsRequest(BaseModel):
3763
3886
  """
3764
3887
  data_retention_days: Annotated[int | None, Field(examples=[90])] = None
3765
3888
  """
3766
- How many days unnamed storages (datasets, key-value stores and request queues without a name) are kept: Free 2 days (48 hours), Starter 31, Scale 60, Business 90. Runs and their logs are kept for the same time as their results; on the Free plan your latest 10 runs are kept with their results until you delete them. This value is set by your plan and cannot be changed through the API.
3889
+ How many days unnamed storages (datasets, key-value stores and request queues without a name) are kept: Free 2 days (48 hours), Starter 31, Scale 60, Business 90. Runs follow their own retention: on the Free plan the latest 10 runs per Actor are kept and older ones are deleted after 7 days; on paid plans runs are deleted after 31 days. This value is set by your plan and cannot be changed through the API.
3767
3890
 
3768
3891
  """
3769
3892
 
@@ -9,6 +9,7 @@ import time
9
9
  from datetime import timedelta
10
10
  from typing import TYPE_CHECKING, Any
11
11
 
12
+ from scrapely_client._credit_unlock import warn_if_held
12
13
  from scrapely_client._docs import docs_group
13
14
  from scrapely_client._logging import create_redirect_logger
14
15
  from scrapely_client._models import Run, RunResponse
@@ -158,7 +159,10 @@ class RunClient(ResourceClient):
158
159
  if response is None:
159
160
  return None
160
161
 
161
- return Run.model_validate(response)
162
+ run = Run.model_validate(response)
163
+ # Results held because the free credit ran out: one line with the count and the unlock link.
164
+ warn_if_held(run)
165
+ return run
162
166
 
163
167
  def metamorph(
164
168
  self,
@@ -565,7 +569,10 @@ class RunClientAsync(ResourceClientAsync):
565
569
  wait_duration=wait_duration,
566
570
  timeout=timeout,
567
571
  )
568
- return Run.model_validate(response) if response is not None else None
572
+ run = Run.model_validate(response) if response is not None else None
573
+ # Results held because the free credit ran out: one line with the count and the unlock link.
574
+ warn_if_held(run)
575
+ return run
569
576
 
570
577
  async def delete(self, *, timeout: Timeout = 'short') -> None:
571
578
  """Delete the run.
@@ -86,6 +86,22 @@ _STORAGE_COLLECTION_PATH_RE = re.compile(r'/(?:datasets|key-value-stores|request
86
86
  # so resending can't apply it twice.
87
87
  _NOT_APPLIED_STATUS_CODES = frozenset({HTTPStatus.BAD_GATEWAY, HTTPStatus.SERVICE_UNAVAILABLE})
88
88
 
89
+ # The API answers its own 502/504 as 503 with the original in this header, so the edge (Cloudflare) keeps the
90
+ # error body. Retry decisions use the original: a 504 (e.g. a Standby container timeout) may have been applied.
91
+ _ORIGINAL_STATUS_HEADER = 'x-scrapely-status'
92
+
93
+
94
+ def _effective_status(response: Any) -> int:
95
+ """The status to act on: the original 502/504 of a 503 that carries X-Scrapely-Status, else the HTTP status."""
96
+ status = response.status_code
97
+ if status != HTTPStatus.SERVICE_UNAVAILABLE:
98
+ return status
99
+ try:
100
+ original = int((response.headers or {}).get(_ORIGINAL_STATUS_HEADER) or 0)
101
+ except (TypeError, ValueError):
102
+ return status
103
+ return original if original in (HTTPStatus.BAD_GATEWAY, HTTPStatus.GATEWAY_TIMEOUT) else status
104
+
89
105
  # Keyed requests: the first request with the key is still being applied, so a resend gets its answer shortly.
90
106
  _KEY_IN_PROGRESS_ERROR_TYPE = 'idempotency-key-in-progress'
91
107
  # Keyed requests: the server can't tell whether the first request was applied, and no resend changes that.
@@ -312,7 +328,7 @@ class ImpitHttpClient(HttpClient):
312
328
  stop_retrying()
313
329
  elif (
314
330
  response.status_code != HTTPStatus.TOO_MANY_REQUESTS
315
- and response.status_code not in _NOT_APPLIED_STATUS_CODES
331
+ and _effective_status(response) not in _NOT_APPLIED_STATUS_CODES
316
332
  and _is_unsafe_to_resend(method, url, headers, params)
317
333
  ):
318
334
  logger.debug(
@@ -605,7 +621,7 @@ class ImpitHttpClientAsync(HttpClientAsync):
605
621
  stop_retrying()
606
622
  elif (
607
623
  response.status_code != HTTPStatus.TOO_MANY_REQUESTS
608
- and response.status_code not in _NOT_APPLIED_STATUS_CODES
624
+ and _effective_status(response) not in _NOT_APPLIED_STATUS_CODES
609
625
  and _is_unsafe_to_resend(method, url, headers, params)
610
626
  ):
611
627
  logger.debug(