blitz-api-py 2.2.0__tar.gz → 3.0.0__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 (53) hide show
  1. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/CHANGELOG.md +11 -0
  2. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/PKG-INFO +42 -10
  3. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/README.md +41 -9
  4. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/__init__.py +5 -2
  5. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_base_client.py +2 -2
  6. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_exceptions.py +54 -4
  7. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_async.py +1 -1
  8. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_base.py +8 -3
  9. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_pagination_sync.py +1 -1
  10. blitz_api_py-3.0.0/src/blitz_api/_version.py +1 -0
  11. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/account.py +1 -1
  12. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/changelog.py +1 -1
  13. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/company.py +1 -1
  14. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/account.py +1 -1
  15. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/changelog.py +1 -1
  16. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/company.py +1 -1
  17. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/__init__.py +4 -0
  18. blitz_api_py-3.0.0/src/blitz_api/types/_models.py +74 -0
  19. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/account.py +5 -3
  20. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/enrichment.py +10 -10
  21. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/search.py +2 -2
  22. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/utils.py +2 -2
  23. blitz_api_py-2.2.0/src/blitz_api/_version.py +0 -1
  24. blitz_api_py-2.2.0/src/blitz_api/types/_models.py +0 -23
  25. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/.gitignore +0 -0
  26. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/LICENSE +0 -0
  27. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/pyproject.toml +0 -0
  28. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_client.py +0 -0
  29. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_client_async.py +0 -0
  30. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_client_sync.py +0 -0
  31. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_compat.py +0 -0
  32. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_constants.py +0 -0
  33. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit.py +0 -0
  34. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit_async.py +0 -0
  35. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  36. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/py.typed +0 -0
  37. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/__init__.py +0 -0
  38. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  39. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/enrichment.py +0 -0
  40. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/jobs.py +0 -0
  41. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/search.py +0 -0
  42. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_async/utils.py +0 -0
  43. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  44. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/enrichment.py +0 -0
  45. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
  46. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/search.py +0 -0
  47. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  48. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/changelog.py +0 -0
  49. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/company.py +0 -0
  50. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/enums.py +0 -0
  51. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/filters.py +0 -0
  52. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/jobs.py +0 -0
  53. {blitz_api_py-2.2.0 → blitz_api_py-3.0.0}/src/blitz_api/types/shared.py +0 -0
@@ -1,5 +1,16 @@
1
1
  # Changelog
2
2
 
3
+ ## [3.0.0](https://github.com/api-blitz/blitz-api-py/compare/v2.2.0...v3.0.0) (2026-09-02)
4
+
5
+
6
+ ### ⚠ BREAKING CHANGES
7
+
8
+ * `KeyInfo.remaining_credits` is renamed to `KeyInfo.records_remaining`.
9
+
10
+ ### Features
11
+
12
+ * records vocabulary rename + fair_usage envelope on every response ([698fd6d](https://github.com/api-blitz/blitz-api-py/commit/698fd6dc95bbe6120c55064255820898b708da42))
13
+
3
14
  ## [2.2.0](https://github.com/api-blitz/blitz-api-py/compare/v2.1.0...v2.2.0) (2026-08-13)
4
15
 
5
16
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 2.2.0
3
+ Version: 3.0.0
4
4
  Summary: Typed Python SDK for the Blitz API — B2B data, search, and enrichment.
5
5
  Project-URL: Homepage, https://blitz-api.ai
6
6
  Project-URL: Documentation, https://docs.blitz-api.ai
@@ -53,7 +53,7 @@ and enrichment.
53
53
 
54
54
  > **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
55
55
  > loop streams every match up to the server-side limit (people: 50k results), which can be
56
- > a lot of credits. Bound spend with **`max_items`** (a client-side total cap on
56
+ > a lot of records. Bound spend with **`max_items`** (a client-side total cap on
57
57
  > `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
58
58
  > [Pagination](#pagination).
59
59
 
@@ -65,6 +65,7 @@ and enrichment.
65
65
  - [Authentication](#authentication)
66
66
  - [Endpoints](#endpoints)
67
67
  - [Pagination](#pagination)
68
+ - [Usage & rate limit (`fair_usage`)](#usage--rate-limit-fair_usage)
68
69
  - [Configuration](#configuration)
69
70
  - [Error handling](#error-handling)
70
71
  - [Forward compatibility](#forward-compatibility)
@@ -89,7 +90,7 @@ from blitz_api.types import Industry, JobLevel
89
90
  with BlitzAPI() as client:
90
91
  # Health-check the key before a batch job.
91
92
  info = client.account.key_info()
92
- print(info.valid, info.remaining_credits, info.max_requests_per_seconds)
93
+ print(info.valid, info.records_remaining, info.max_requests_per_seconds)
93
94
 
94
95
  # LinkedIn profile URL -> verified work email.
95
96
  email = client.enrichment.email(
@@ -127,7 +128,7 @@ asyncio.run(main())
127
128
  ## Example: find, enrich, collect
128
129
 
129
130
  A complete flow — find people, enrich each one's verified work email, collect the
130
- contacts. `max_items` caps the total fetched so the run can't surprise you with credits.
131
+ contacts. `max_items` caps the total fetched so the run can't surprise you with records.
131
132
 
132
133
  ```python
133
134
  from blitz_api import BlitzAPI
@@ -140,7 +141,7 @@ leads = client.search.people(
140
141
  company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
141
142
  people={"job_level": [JobLevel.VP]},
142
143
  max_results=25,
143
- ).collect(max_items=25) # client-side total cap — bounds credit spend
144
+ ).collect(max_items=25) # client-side total cap — bounds record spend
144
145
 
145
146
  # 2. Enrich each lead's verified work email from their LinkedIn profile URL.
146
147
  contacts: list[dict[str, str | None]] = []
@@ -217,9 +218,9 @@ fetches each subsequent page for you. `search.people`/`search.companies` and
217
218
  all behave identically here.
218
219
 
219
220
  > **`max_results` is the page size, not a total.** It's results per page, and the API
220
- > **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
221
+ > **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
221
222
  > loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
222
- > employee finder: 10k; jobs: 5k), which can be a lot of credits. Bound it with **`max_items`** on
223
+ > employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
223
224
  > `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
224
225
  > `break` out of the loop, or drive pages manually.
225
226
 
@@ -256,6 +257,37 @@ nxt = page.get_next_page() # None once exhausted
256
257
  The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
257
258
  exported from `blitz_api`.
258
259
 
260
+ ## Usage & rate limit (`fair_usage`)
261
+
262
+ Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
263
+ the plan, your rate-limit headroom, and a request id to quote to support. It's on every
264
+ response model and on every page, so you can meter a long run without extra `key_info()`
265
+ calls.
266
+
267
+ ```python
268
+ result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
269
+ if result.fair_usage is not None:
270
+ print(result.fair_usage.records_used) # what this call cost
271
+ print(result.fair_usage.records_remaining) # a number, or "unlimited"
272
+ print(result.fair_usage.next_reset_at) # None on an unlimited plan
273
+ print(result.fair_usage.request_id) # quote this to support
274
+ if result.fair_usage.rate_limit is not None: # absent on account.key_info()
275
+ print(result.fair_usage.rate_limit.remaining_this_second)
276
+
277
+ # Pages carry the block of the request that fetched them.
278
+ for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
279
+ print(page.fair_usage.records_used if page.fair_usage else None)
280
+ ```
281
+
282
+ `InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
283
+ resets without a second call:
284
+
285
+ ```python
286
+ except InsufficientRecordsError as err:
287
+ if err.fair_usage is not None:
288
+ print("resets at", err.fair_usage.next_reset_at)
289
+ ```
290
+
259
291
  ## Configuration
260
292
 
261
293
  ```python
@@ -288,15 +320,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
288
320
 
289
321
  ```python
290
322
  from blitz_api import (
291
- BlitzError, AuthenticationError, InsufficientCreditsError,
323
+ BlitzError, AuthenticationError, InsufficientRecordsError,
292
324
  NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
293
325
  APITimeoutError, APIResponseValidationError,
294
326
  )
295
327
 
296
328
  try:
297
329
  client.enrichment.email(person_linkedin_url="...")
298
- except InsufficientCreditsError:
299
- ... # 402 — out of credits
330
+ except InsufficientRecordsError as err:
331
+ ... # 402 — out of records; err.fair_usage.next_reset_at
300
332
  except AuthenticationError:
301
333
  ... # 401 — bad key
302
334
  except APIStatusError as err:
@@ -22,7 +22,7 @@ and enrichment.
22
22
 
23
23
  > **Billing.** Blitz bills **per result**. A bare `for person in client.search.people(...)`
24
24
  > loop streams every match up to the server-side limit (people: 50k results), which can be
25
- > a lot of credits. Bound spend with **`max_items`** (a client-side total cap on
25
+ > a lot of records. Bound spend with **`max_items`** (a client-side total cap on
26
26
  > `.collect()` / `.auto_paging_iter()`, never sent on the wire) — details in
27
27
  > [Pagination](#pagination).
28
28
 
@@ -34,6 +34,7 @@ and enrichment.
34
34
  - [Authentication](#authentication)
35
35
  - [Endpoints](#endpoints)
36
36
  - [Pagination](#pagination)
37
+ - [Usage & rate limit (`fair_usage`)](#usage--rate-limit-fair_usage)
37
38
  - [Configuration](#configuration)
38
39
  - [Error handling](#error-handling)
39
40
  - [Forward compatibility](#forward-compatibility)
@@ -58,7 +59,7 @@ from blitz_api.types import Industry, JobLevel
58
59
  with BlitzAPI() as client:
59
60
  # Health-check the key before a batch job.
60
61
  info = client.account.key_info()
61
- print(info.valid, info.remaining_credits, info.max_requests_per_seconds)
62
+ print(info.valid, info.records_remaining, info.max_requests_per_seconds)
62
63
 
63
64
  # LinkedIn profile URL -> verified work email.
64
65
  email = client.enrichment.email(
@@ -96,7 +97,7 @@ asyncio.run(main())
96
97
  ## Example: find, enrich, collect
97
98
 
98
99
  A complete flow — find people, enrich each one's verified work email, collect the
99
- contacts. `max_items` caps the total fetched so the run can't surprise you with credits.
100
+ contacts. `max_items` caps the total fetched so the run can't surprise you with records.
100
101
 
101
102
  ```python
102
103
  from blitz_api import BlitzAPI
@@ -109,7 +110,7 @@ leads = client.search.people(
109
110
  company={"industry": {"include": [Industry.SOFTWARE_DEVELOPMENT]}},
110
111
  people={"job_level": [JobLevel.VP]},
111
112
  max_results=25,
112
- ).collect(max_items=25) # client-side total cap — bounds credit spend
113
+ ).collect(max_items=25) # client-side total cap — bounds record spend
113
114
 
114
115
  # 2. Enrich each lead's verified work email from their LinkedIn profile URL.
115
116
  contacts: list[dict[str, str | None]] = []
@@ -186,9 +187,9 @@ fetches each subsequent page for you. `search.people`/`search.companies` and
186
187
  all behave identically here.
187
188
 
188
189
  > **`max_results` is the page size, not a total.** It's results per page, and the API
189
- > **bills 1 credit per result returned**. A bare `for person in client.search.people(...)`
190
+ > **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
190
191
  > loop streams *every* match up to the server-side limit (people: 50k results / 1k pages;
191
- > employee finder: 10k; jobs: 5k), which can be a lot of credits. Bound it with **`max_items`** on
192
+ > employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
192
193
  > `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
193
194
  > `break` out of the loop, or drive pages manually.
194
195
 
@@ -225,6 +226,37 @@ nxt = page.get_next_page() # None once exhausted
225
226
  The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
226
227
  exported from `blitz_api`.
227
228
 
229
+ ## Usage & rate limit (`fair_usage`)
230
+
231
+ Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
232
+ the plan, your rate-limit headroom, and a request id to quote to support. It's on every
233
+ response model and on every page, so you can meter a long run without extra `key_info()`
234
+ calls.
235
+
236
+ ```python
237
+ result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
238
+ if result.fair_usage is not None:
239
+ print(result.fair_usage.records_used) # what this call cost
240
+ print(result.fair_usage.records_remaining) # a number, or "unlimited"
241
+ print(result.fair_usage.next_reset_at) # None on an unlimited plan
242
+ print(result.fair_usage.request_id) # quote this to support
243
+ if result.fair_usage.rate_limit is not None: # absent on account.key_info()
244
+ print(result.fair_usage.rate_limit.remaining_this_second)
245
+
246
+ # Pages carry the block of the request that fetched them.
247
+ for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
248
+ print(page.fair_usage.records_used if page.fair_usage else None)
249
+ ```
250
+
251
+ `InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
252
+ resets without a second call:
253
+
254
+ ```python
255
+ except InsufficientRecordsError as err:
256
+ if err.fair_usage is not None:
257
+ print("resets at", err.fair_usage.next_reset_at)
258
+ ```
259
+
228
260
  ## Configuration
229
261
 
230
262
  ```python
@@ -257,15 +289,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
257
289
 
258
290
  ```python
259
291
  from blitz_api import (
260
- BlitzError, AuthenticationError, InsufficientCreditsError,
292
+ BlitzError, AuthenticationError, InsufficientRecordsError,
261
293
  NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
262
294
  APITimeoutError, APIResponseValidationError,
263
295
  )
264
296
 
265
297
  try:
266
298
  client.enrichment.email(person_linkedin_url="...")
267
- except InsufficientCreditsError:
268
- ... # 402 — out of credits
299
+ except InsufficientRecordsError as err:
300
+ ... # 402 — out of records; err.fair_usage.next_reset_at
269
301
  except AuthenticationError:
270
302
  ... # 401 — bad key
271
303
  except APIStatusError as err:
@@ -23,7 +23,8 @@ from ._exceptions import (
23
23
  APITimeoutError,
24
24
  AuthenticationError,
25
25
  BlitzError,
26
- InsufficientCreditsError,
26
+ InsufficientCreditsError, # pyright: ignore[reportDeprecated]
27
+ InsufficientRecordsError,
27
28
  NotFoundError,
28
29
  RateLimitError,
29
30
  ServerError,
@@ -54,10 +55,12 @@ __all__ = [
54
55
  "APIResponseValidationError",
55
56
  "APIStatusError",
56
57
  "AuthenticationError",
57
- "InsufficientCreditsError",
58
+ "InsufficientRecordsError",
58
59
  "NotFoundError",
59
60
  "RateLimitError",
60
61
  "ServerError",
62
+ # deprecated alias (removed in 3.0.0)
63
+ "InsufficientCreditsError",
61
64
  # commonly-used types (full set under blitz_api.types)
62
65
  "Industry",
63
66
  "CompanyFilter",
@@ -24,7 +24,7 @@ from ._exceptions import (
24
24
  APIStatusError,
25
25
  AuthenticationError,
26
26
  BlitzError,
27
- InsufficientCreditsError,
27
+ InsufficientRecordsError,
28
28
  NotFoundError,
29
29
  RateLimitError,
30
30
  ServerError,
@@ -39,7 +39,7 @@ ResponseT = TypeVar("ResponseT", bound=BaseModel)
39
39
  # falls back to a generic APIStatusError (or ServerError for any 5xx).
40
40
  _STATUS_EXCEPTIONS: dict[int, type[APIStatusError]] = {
41
41
  401: AuthenticationError,
42
- 402: InsufficientCreditsError,
42
+ 402: InsufficientRecordsError,
43
43
  404: NotFoundError,
44
44
  429: RateLimitError,
45
45
  }
@@ -8,20 +8,46 @@
8
8
  ├── APIResponseValidationError # a 2xx body was not valid JSON / not the expected shape
9
9
  └── APIStatusError # a non-2xx HTTP response was received
10
10
  ├── AuthenticationError # 401
11
- ├── InsufficientCreditsError # 402
11
+ ├── InsufficientRecordsError # 402
12
12
  ├── NotFoundError # 404
13
13
  ├── RateLimitError # 429 (after retries are exhausted)
14
14
  └── ServerError # 5xx (after retries are exhausted)
15
15
 
16
16
  Catch :class:`BlitzError` to handle anything this SDK raises.
17
+
18
+ ``InsufficientCreditsError`` remains available as a deprecated alias of
19
+ :class:`InsufficientRecordsError`; it is scheduled for removal in 3.0.0.
17
20
  """
18
21
 
19
22
  from __future__ import annotations
20
23
 
21
- from typing import TYPE_CHECKING, Any
24
+ from typing import TYPE_CHECKING, Any, cast
25
+
26
+ from pydantic import ValidationError
27
+
28
+ from .types._models import FairUsage
22
29
 
23
30
  if TYPE_CHECKING:
24
31
  import httpx
32
+ from typing_extensions import deprecated
33
+
34
+
35
+ def _parse_fair_usage(body: Any) -> FairUsage | None:
36
+ """Pull the ``fair_usage`` block out of an error body, if the API sent one.
37
+
38
+ The API attaches it to ``402`` responses, so a caller who runs out of records can
39
+ read ``next_reset_at`` off the exception. Never raises: a malformed block just
40
+ yields ``None`` rather than masking the original API error.
41
+ """
42
+ if not isinstance(body, dict):
43
+ return None
44
+ raw = cast("dict[str, Any]", body).get("fair_usage")
45
+ if not isinstance(raw, dict):
46
+ return None
47
+ try:
48
+ return FairUsage.model_validate(raw)
49
+ except ValidationError:
50
+ return None
25
51
 
26
52
 
27
53
  class BlitzError(Exception):
@@ -75,6 +101,8 @@ class APIStatusError(BlitzError):
75
101
  body: The parsed JSON body, or the raw text if it was not JSON.
76
102
  message: A human-readable message extracted from the body when present.
77
103
  request_id: The value of the ``x-request-id`` response header, if any.
104
+ fair_usage: The :class:`~blitz_api.types.FairUsage` block from the body, when
105
+ the API sent one (it does on ``402``); ``None`` otherwise.
78
106
  response: The underlying :class:`httpx.Response`.
79
107
  """
80
108
 
@@ -91,14 +119,19 @@ class APIStatusError(BlitzError):
91
119
  self.status_code = response.status_code
92
120
  self.body = body
93
121
  self.request_id = response.headers.get("x-request-id")
122
+ self.fair_usage = _parse_fair_usage(body)
94
123
 
95
124
 
96
125
  class AuthenticationError(APIStatusError):
97
126
  """401 — the API key is missing or invalid."""
98
127
 
99
128
 
100
- class InsufficientCreditsError(APIStatusError):
101
- """402 — the key is valid but the account is out of credits."""
129
+ class InsufficientRecordsError(APIStatusError):
130
+ """402 — the key is valid but the account is out of records.
131
+
132
+ The API attaches the usage block to this response, so :attr:`~APIStatusError.fair_usage`
133
+ tells you when the balance resets (``fair_usage.next_reset_at``).
134
+ """
102
135
 
103
136
 
104
137
  class NotFoundError(APIStatusError):
@@ -111,3 +144,20 @@ class RateLimitError(APIStatusError):
111
144
 
112
145
  class ServerError(APIStatusError):
113
146
  """5xx — the API failed (raised only after retries are exhausted)."""
147
+
148
+
149
+ # --- Deprecated aliases ------------------------------------------------------
150
+
151
+ if TYPE_CHECKING:
152
+
153
+ @deprecated(
154
+ "InsufficientCreditsError is renamed to InsufficientRecordsError and will be "
155
+ "removed in 3.0.0."
156
+ )
157
+ class InsufficientCreditsError(InsufficientRecordsError):
158
+ """Deprecated alias for :class:`InsufficientRecordsError`."""
159
+
160
+ else:
161
+ # A true alias, not a subclass: the client raises ``InsufficientRecordsError``, so a
162
+ # subclass here would stop ``except InsufficientCreditsError`` from catching it.
163
+ InsufficientCreditsError = InsufficientRecordsError
@@ -54,7 +54,7 @@ class AsyncPaginator(BasePage, Generic[ItemT]):
54
54
  """Drain every item across all pages into a list, optionally capped at ``max_items``.
55
55
 
56
56
  Convenience over a manual iteration loop; pair with ``max_items`` so an unbounded result
57
- set can't exhaust memory — or credits, since the API bills per result returned.
57
+ set can't exhaust memory — or records, since the API bills per result returned.
58
58
  """
59
59
  items: list[ItemT] = []
60
60
  async for item in self._auto_paging_items(max_items):
@@ -13,11 +13,16 @@ from typing import Any
13
13
 
14
14
  from pydantic import PrivateAttr
15
15
 
16
- from .types._models import BlitzModel
16
+ from .types._models import BlitzResponse
17
17
 
18
18
 
19
- class BasePage(BlitzModel):
20
- """Common pagination context. Subclasses add the page fields + iteration."""
19
+ class BasePage(BlitzResponse):
20
+ """Common pagination context. Subclasses add the page fields + iteration.
21
+
22
+ Inherits ``fair_usage`` from :class:`~blitz_api.types._models.BlitzResponse`: each
23
+ page carries the usage block of the request that fetched *it*, so during
24
+ auto-pagination ``page.fair_usage`` reflects that page, not the whole walk.
25
+ """
21
26
 
22
27
  # Bound by the client after a page is parsed, so the page can fetch the next one.
23
28
  _client: Any = PrivateAttr(default=None)
@@ -56,7 +56,7 @@ class Paginator(BasePage, Generic[ItemT]):
56
56
  """Drain every item across all pages into a list, optionally capped at ``max_items``.
57
57
 
58
58
  Convenience over a manual iteration loop; pair with ``max_items`` so an unbounded result
59
- set can't exhaust memory — or credits, since the API bills per result returned.
59
+ set can't exhaust memory — or records, since the API bills per result returned.
60
60
  """
61
61
  items: list[ItemT] = []
62
62
  for item in self._auto_paging_items(max_items):
@@ -0,0 +1 @@
1
+ __version__ = "3.0.0" # x-release-please-version
@@ -18,7 +18,7 @@ class AsyncAccountResource:
18
18
  self._client = client
19
19
 
20
20
  async def key_info(self, *, timeout: TimeoutParam = None) -> KeyInfo:
21
- """Check the API key's validity, credit balance, and rate limit.
21
+ """Check the API key's validity, record balance, and rate limit.
22
22
 
23
23
  A cheap health check to run before a batch job.
24
24
  """
@@ -36,7 +36,7 @@ class AsyncChangelogResource:
36
36
  ``improvement`` | ``fix`` | ``deprecation`` | ``announcement``), a ``title``, and
37
37
  optional ``body``, ``affected_endpoints``, and ``links``.
38
38
 
39
- This endpoint is **public** — it costs no credits and works regardless of API-key
39
+ This endpoint is **public** — it costs no records and works regardless of API-key
40
40
  validity (the SDK still sends the key header, which the endpoint ignores). It is
41
41
  **not paginated**: it returns a plain list filtered by the ``days`` / ``limit``
42
42
  query parameters.
@@ -42,7 +42,7 @@ class AsyncCompanyResource:
42
42
 
43
43
  Cursor-paginated: auto-paginates over every ``{company, matched_jobs}`` match when
44
44
  the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for manual
45
- control. The API bills **1 credit per result returned**; bound spend with
45
+ control. The API bills **1 record per result returned**; bound spend with
46
46
  ``max_items`` on ``.collect()`` / ``.auto_paging_iter()``.
47
47
  """
48
48
  body = _drop_none(job=job, company=company, max_results=max_results, cursor=cursor)
@@ -20,7 +20,7 @@ class AccountResource:
20
20
  self._client = client
21
21
 
22
22
  def key_info(self, *, timeout: TimeoutParam = None) -> KeyInfo:
23
- """Check the API key's validity, credit balance, and rate limit.
23
+ """Check the API key's validity, record balance, and rate limit.
24
24
 
25
25
  A cheap health check to run before a batch job.
26
26
  """
@@ -38,7 +38,7 @@ class ChangelogResource:
38
38
  ``improvement`` | ``fix`` | ``deprecation`` | ``announcement``), a ``title``, and
39
39
  optional ``body``, ``affected_endpoints``, and ``links``.
40
40
 
41
- This endpoint is **public** — it costs no credits and works regardless of API-key
41
+ This endpoint is **public** — it costs no records and works regardless of API-key
42
42
  validity (the SDK still sends the key header, which the endpoint ignores). It is
43
43
  **not paginated**: it returns a plain list filtered by the ``days`` / ``limit``
44
44
  query parameters.
@@ -44,7 +44,7 @@ class CompanyResource:
44
44
 
45
45
  Cursor-paginated: auto-paginates over every ``{company, matched_jobs}`` match when
46
46
  the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for manual
47
- control. The API bills **1 credit per result returned**; bound spend with
47
+ control. The API bills **1 record per result returned**; bound spend with
48
48
  ``max_items`` on ``.collect()`` / ``.auto_paging_iter()``.
49
49
  """
50
50
  body = _drop_none(job=job, company=company, max_results=max_results, cursor=cursor)
@@ -7,6 +7,7 @@ Import response models and request filters from here, e.g.::
7
7
 
8
8
  from __future__ import annotations
9
9
 
10
+ from ._models import FairUsage, FairUsageRateLimit
10
11
  from .account import ActivePlan, KeyInfo
11
12
  from .changelog import ChangelogEntry, ChangelogLink, ChangelogResponse
12
13
  from .company import TamByJobsMatch
@@ -122,6 +123,9 @@ __all__ = [
122
123
  "JobCompanyHQFilter",
123
124
  "JobCompanyFilter",
124
125
  "TamJobFilter",
126
+ # envelope (on every response)
127
+ "FairUsage",
128
+ "FairUsageRateLimit",
125
129
  # account
126
130
  "KeyInfo",
127
131
  "ActivePlan",
@@ -0,0 +1,74 @@
1
+ """Base Pydantic models shared by every Blitz API response type.
2
+
3
+ :class:`BlitzModel` is the forward-compatible base every model inherits.
4
+ :class:`BlitzResponse` adds the ``fair_usage`` envelope that every ``/v2`` endpoint
5
+ returns alongside its payload, so only *top-level* response models (and the
6
+ pagination page classes) carry it — nested entities like ``Person`` do not.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from typing import Literal
12
+
13
+ from pydantic import BaseModel, ConfigDict
14
+
15
+
16
+ class BlitzModel(BaseModel):
17
+ """Base for all response models.
18
+
19
+ Configured to be forward-compatible: unknown fields returned by the API are
20
+ preserved (reachable via :attr:`model_extra`) instead of raising, so a new
21
+ server-side field never breaks deserialization. Known fields stay precisely
22
+ typed.
23
+ """
24
+
25
+ model_config = ConfigDict(
26
+ extra="allow",
27
+ populate_by_name=True,
28
+ # The API exposes fields like ``max_requests_per_seconds``; silence the
29
+ # ``model_`` protected-namespace warnings without affecting behaviour.
30
+ protected_namespaces=(),
31
+ )
32
+
33
+
34
+ class FairUsageRateLimit(BlitzModel):
35
+ """The rate-limit slice of :class:`FairUsage`.
36
+
37
+ Absent on endpoints that are not rate limited (notably ``account.key_info``).
38
+ """
39
+
40
+ # Modelled as ``float`` for the same reason as ``KeyInfo.max_requests_per_seconds``:
41
+ # the spec types it as a plain JSON number.
42
+ requests_per_second: float | None = None
43
+ remaining_this_second: int | None = None
44
+
45
+
46
+ class FairUsage(BlitzModel):
47
+ """Record usage, rate limit, and tracing data for a single request.
48
+
49
+ Returned by every ``/v2`` endpoint on success, and on the ``402``
50
+ insufficient-balance error (:attr:`~blitz_api.APIStatusError.fair_usage`).
51
+ """
52
+
53
+ #: Records this request consumed, after reconciliation against the results
54
+ #: actually returned.
55
+ records_used: int | None = None
56
+ #: Records left on the plan after this request. A number on metered plans; the
57
+ #: literal ``"unlimited"`` on unlimited plans.
58
+ records_remaining: float | Literal["unlimited"] | None = None
59
+ #: When the record balance resets. ``None`` on an unlimited plan.
60
+ next_reset_at: str | None = None
61
+ #: ``None`` on endpoints that are not rate limited.
62
+ rate_limit: FairUsageRateLimit | None = None
63
+ #: Quote this id when contacting support.
64
+ request_id: str | None = None
65
+
66
+
67
+ class BlitzResponse(BlitzModel):
68
+ """Base for top-level response models: the payload plus the ``fair_usage`` block.
69
+
70
+ ``fair_usage`` is ``None`` on the public ``/changelog/`` endpoint (which is not
71
+ metered) and on any response predating the API's 2026-08-31 rollout.
72
+ """
73
+
74
+ fair_usage: FairUsage | None = None
@@ -4,7 +4,7 @@ from __future__ import annotations
4
4
 
5
5
  from typing import Literal
6
6
 
7
- from ._models import BlitzModel
7
+ from ._models import BlitzModel, BlitzResponse
8
8
 
9
9
  __all__ = ["ActivePlan", "KeyInfo"]
10
10
 
@@ -17,13 +17,15 @@ class ActivePlan(BlitzModel):
17
17
  started_at: str | None = None
18
18
 
19
19
 
20
- class KeyInfo(BlitzModel):
20
+ class KeyInfo(BlitzResponse):
21
21
  """The result of ``client.account.key_info()`` — key health and limits."""
22
22
 
23
23
  valid: bool | None = None
24
24
  id: str | None = None
25
25
  # A number on metered plans; the literal "unlimited" on unlimited plans.
26
- remaining_credits: float | Literal["unlimited"] | None = None
26
+ # Renamed by the API on 2026-09-01 to match ``fair_usage.records_remaining``
27
+ # and the ``x-records-remaining`` response header.
28
+ records_remaining: float | Literal["unlimited"] | None = None
27
29
  next_reset_at: str | None = None
28
30
  max_requests_per_seconds: float | Literal["unlimited"] | None = None
29
31
  allowed_apis: list[str] = []
@@ -2,7 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from ._models import BlitzModel
5
+ from ._models import BlitzModel, BlitzResponse
6
6
  from .shared import Company, Person
7
7
 
8
8
  __all__ = [
@@ -31,7 +31,7 @@ class EmailMatch(BlitzModel):
31
31
  email_domain: str | None = None
32
32
 
33
33
 
34
- class EmailEnrichmentResponse(BlitzModel):
34
+ class EmailEnrichmentResponse(BlitzResponse):
35
35
  """Result of ``enrichment.email`` (LinkedIn URL -> verified work email)."""
36
36
 
37
37
  found: bool | None = None
@@ -39,28 +39,28 @@ class EmailEnrichmentResponse(BlitzModel):
39
39
  all_emails: list[EmailMatch] = []
40
40
 
41
41
 
42
- class PhoneEnrichmentResponse(BlitzModel):
42
+ class PhoneEnrichmentResponse(BlitzResponse):
43
43
  """Result of ``enrichment.phone`` (LinkedIn URL -> phone)."""
44
44
 
45
45
  found: bool | None = None
46
46
  phone: str | None = None
47
47
 
48
48
 
49
- class EmailToPersonResponse(BlitzModel):
49
+ class EmailToPersonResponse(BlitzResponse):
50
50
  """Result of ``enrichment.email_to_person`` (email -> full profile)."""
51
51
 
52
52
  found: bool | None = None
53
53
  person: Person | None = None
54
54
 
55
55
 
56
- class PhoneToPersonResponse(BlitzModel):
56
+ class PhoneToPersonResponse(BlitzResponse):
57
57
  """Result of ``enrichment.phone_to_person`` (phone -> full profile)."""
58
58
 
59
59
  found: bool | None = None
60
60
  person: Person | None = None
61
61
 
62
62
 
63
- class CompanyEnrichmentResponse(BlitzModel):
63
+ class CompanyEnrichmentResponse(BlitzResponse):
64
64
  """Result of ``enrichment.company`` (company LinkedIn URL -> company profile)."""
65
65
 
66
66
  found: bool | None = None
@@ -74,7 +74,7 @@ class DomainToLinkedinMatch(BlitzModel):
74
74
  company_name: str | None = None
75
75
 
76
76
 
77
- class DomainToLinkedinResponse(BlitzModel):
77
+ class DomainToLinkedinResponse(BlitzResponse):
78
78
  """Result of ``enrichment.domain_to_linkedin`` (domain -> company LinkedIn URL)."""
79
79
 
80
80
  found: bool | None = None
@@ -84,7 +84,7 @@ class DomainToLinkedinResponse(BlitzModel):
84
84
  other: list[DomainToLinkedinMatch] = []
85
85
 
86
86
 
87
- class LinkedinToDomainResponse(BlitzModel):
87
+ class LinkedinToDomainResponse(BlitzResponse):
88
88
  """Result of ``enrichment.linkedin_to_domain`` (company LinkedIn URL -> email domain)."""
89
89
 
90
90
  found: bool | None = None
@@ -105,7 +105,7 @@ class CompanyDistributionByCountryItem(BlitzModel):
105
105
  percentage_ratio: float | None = None
106
106
 
107
107
 
108
- class CompanyDistributionByCountryResponse(BlitzModel):
108
+ class CompanyDistributionByCountryResponse(BlitzResponse):
109
109
  """Result of ``enrichment.company_distribution_by_country``.
110
110
 
111
111
  Served by ``POST /v2/enrichment/company-distribution-by-country``.
@@ -129,7 +129,7 @@ class CompanyDistributionByDepartmentItem(BlitzModel):
129
129
  percentage_ratio: float | None = None
130
130
 
131
131
 
132
- class CompanyDistributionByDepartmentResponse(BlitzModel):
132
+ class CompanyDistributionByDepartmentResponse(BlitzResponse):
133
133
  """Result of ``enrichment.company_distribution_by_department``.
134
134
 
135
135
  Served by ``POST /v2/enrichment/company-distribution-by-department``.
@@ -9,7 +9,7 @@ result does.
9
9
 
10
10
  from __future__ import annotations
11
11
 
12
- from ._models import BlitzModel
12
+ from ._models import BlitzModel, BlitzResponse
13
13
  from .shared import Person
14
14
 
15
15
  __all__ = [
@@ -30,7 +30,7 @@ class WaterfallIcpMatch(BlitzModel):
30
30
  person: Person | None = None
31
31
 
32
32
 
33
- class WaterfallIcpResponse(BlitzModel):
33
+ class WaterfallIcpResponse(BlitzResponse):
34
34
  """Result of ``search.waterfall_icp``."""
35
35
 
36
36
  company_linkedin_url: str | None = None
@@ -2,14 +2,14 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from ._models import BlitzModel
5
+ from ._models import BlitzResponse
6
6
 
7
7
  __all__ = [
8
8
  "CurrentDateResponse",
9
9
  ]
10
10
 
11
11
 
12
- class CurrentDateResponse(BlitzModel):
12
+ class CurrentDateResponse(BlitzResponse):
13
13
  """Result of ``utils.current_date``."""
14
14
 
15
15
  datetime: str | None = None
@@ -1 +0,0 @@
1
- __version__ = "2.2.0" # x-release-please-version
@@ -1,23 +0,0 @@
1
- """Base Pydantic model for every Blitz API response type."""
2
-
3
- from __future__ import annotations
4
-
5
- from pydantic import BaseModel, ConfigDict
6
-
7
-
8
- class BlitzModel(BaseModel):
9
- """Base for all response models.
10
-
11
- Configured to be forward-compatible: unknown fields returned by the API are
12
- preserved (reachable via :attr:`model_extra`) instead of raising, so a new
13
- server-side field never breaks deserialization. Known fields stay precisely
14
- typed.
15
- """
16
-
17
- model_config = ConfigDict(
18
- extra="allow",
19
- populate_by_name=True,
20
- # The API exposes fields like ``max_requests_per_seconds``; silence the
21
- # ``model_`` protected-namespace warnings without affecting behaviour.
22
- protected_namespaces=(),
23
- )
File without changes
File without changes