blitz-api-py 2.2.0__tar.gz → 4.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 (57) hide show
  1. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/CHANGELOG.md +44 -0
  2. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/PKG-INFO +82 -22
  3. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/README.md +81 -21
  4. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/__init__.py +4 -2
  5. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_base_client.py +2 -2
  6. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_client_async.py +11 -2
  7. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_client_sync.py +11 -2
  8. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_constants.py +5 -2
  9. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_exceptions.py +33 -4
  10. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_async.py +1 -1
  11. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_base.py +8 -3
  12. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_pagination_sync.py +1 -1
  13. blitz_api_py-4.0.0/src/blitz_api/_version.py +1 -0
  14. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/account.py +1 -1
  15. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/changelog.py +6 -9
  16. blitz_api_py-4.0.0/src/blitz_api/resources/_async/company.py +89 -0
  17. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/enrichment.py +19 -0
  18. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/jobs.py +8 -13
  19. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/search.py +23 -52
  20. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/account.py +1 -1
  21. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/changelog.py +6 -9
  22. blitz_api_py-4.0.0/src/blitz_api/resources/_sync/company.py +91 -0
  23. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/enrichment.py +19 -0
  24. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/jobs.py +8 -13
  25. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/search.py +23 -52
  26. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/__init__.py +12 -1
  27. blitz_api_py-4.0.0/src/blitz_api/types/_models.py +98 -0
  28. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/account.py +5 -3
  29. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/changelog.py +4 -13
  30. blitz_api_py-4.0.0/src/blitz_api/types/company.py +49 -0
  31. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/enrichment.py +22 -10
  32. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/enums.py +1 -0
  33. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/filters.py +93 -23
  34. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/search.py +2 -2
  35. blitz_api_py-4.0.0/src/blitz_api/types/shared.py +152 -0
  36. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/utils.py +2 -2
  37. blitz_api_py-2.2.0/src/blitz_api/_version.py +0 -1
  38. blitz_api_py-2.2.0/src/blitz_api/resources/_async/company.py +0 -55
  39. blitz_api_py-2.2.0/src/blitz_api/resources/_sync/company.py +0 -57
  40. blitz_api_py-2.2.0/src/blitz_api/types/_models.py +0 -23
  41. blitz_api_py-2.2.0/src/blitz_api/types/company.py +0 -31
  42. blitz_api_py-2.2.0/src/blitz_api/types/shared.py +0 -120
  43. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/.gitignore +0 -0
  44. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/LICENSE +0 -0
  45. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/pyproject.toml +0 -0
  46. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_client.py +0 -0
  47. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_compat.py +0 -0
  48. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit.py +0 -0
  49. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit_async.py +0 -0
  50. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  51. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/py.typed +0 -0
  52. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/__init__.py +0 -0
  53. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  54. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_async/utils.py +0 -0
  55. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  56. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  57. {blitz_api_py-2.2.0 → blitz_api_py-4.0.0}/src/blitz_api/types/jobs.py +0 -0
@@ -1,5 +1,49 @@
1
1
  # Changelog
2
2
 
3
+ ## [4.0.0](https://github.com/api-blitz/blitz-api-py/compare/v3.0.0...v4.0.0) (2026-09-22)
4
+
5
+
6
+ ### ⚠ BREAKING CHANGES
7
+
8
+ * `search.companies(company=...)` no longer type-checks a dict literal containing `linkedin_url`. The endpoint never honoured it, so drop the key. On `search.people` and `company.tam_by_people` it keeps working, now typed as `PeopleCompanyFilter` (exported from `blitz_api` and `blitz_api.types`).
9
+ * `Company.slogan`, `Company.revenue` and `Company.employee_growth` are removed, as is the `EmployeeGrowth` model and its `blitz_api.types` export -- the API never returned any of them. `Company.specialties` is now `list[str]` defaulting to `[]` rather than `list[str] | None`; code branching on `specialties is None` should check for an empty list instead.
10
+ * `InsufficientCreditsError` is removed. Catch `InsufficientRecordsError` instead.
11
+ * `Education.field_of_study` is removed — the API folded it into `degree` ("Bachelor of Science, Industrial Engineering").
12
+
13
+ ### Features
14
+
15
+ * add the Industry.UNKNOWN bucket and document the range-filter 422 ([5f2d944](https://github.com/api-blitz/blitz-api-py/commit/5f2d944427b631b4b668af0bc99f614161b00425))
16
+ * remove the deprecated InsufficientCreditsError alias ([0c9be23](https://github.com/api-blitz/blitz-api-py/commit/0c9be232268cb68cfa36d7352e1304608bed32cc))
17
+ * split PeopleCompanyFilter out of the shared CompanyFilter ([fc6983e](https://github.com/api-blitz/blitz-api-py/commit/fc6983eef696c058620a799ec4b4f476ed32701d)), closes [#25](https://github.com/api-blitz/blitz-api-py/issues/25)
18
+ * sync SDK to the 2026-09-11 / 2026-09-15 API releases ([81460ed](https://github.com/api-blitz/blitz-api-py/commit/81460edbcff5f985fd3e1498d70b282ce11d7550))
19
+
20
+
21
+ ### Bug Fixes
22
+
23
+ * remove phantom Company fields and the redundant _drop_none layer ([52b5ec5](https://github.com/api-blitz/blitz-api-py/commit/52b5ec5ec7241d2ea7dd6aacf2a3d0bbcc73dec2))
24
+
25
+
26
+ ### Documentation
27
+
28
+ * correct the profile_min_connections default to 0, not 200 ([6ee2893](https://github.com/api-blitz/blitz-api-py/commit/6ee2893c7082b075f9d83ab5dc68943a8126a965)), closes [#26](https://github.com/api-blitz/blitz-api-py/issues/26)
29
+ * correct the README headline example and route to enrichment.person ([7051afb](https://github.com/api-blitz/blitz-api-py/commit/7051afb1fa362621e23ae8ed25f2ae20a842006e)), closes [#30](https://github.com/api-blitz/blitz-api-py/issues/30)
30
+ * correct the stale rate-limit and spec-version facts ([10615d5](https://github.com/api-blitz/blitz-api-py/commit/10615d58b6f6d4905e1f00033032fd5fbf13a350))
31
+ * correct the stale response-schema rule and link the JS mirror PR ([1f1381f](https://github.com/api-blitz/blitz-api-py/commit/1f1381f164c0bc02b46a20ec94cec4c079375f44))
32
+ * guard the optional linkedin_url in the README enrichment example ([cdcfb71](https://github.com/api-blitz/blitz-api-py/commit/cdcfb71171131bf9400e99737b455ef7676c4b70))
33
+ * name the legacy 50 req/s rate limit instead of "more on legacy ones" ([f4974a1](https://github.com/api-blitz/blitz-api-py/commit/f4974a123ad869f3f1e9aa28293dede6ce24648b)), closes [#29](https://github.com/api-blitz/blitz-api-py/issues/29)
34
+ * the /changelog/ trailing slash is not load-bearing ([891d5b7](https://github.com/api-blitz/blitz-api-py/commit/891d5b7e1c04583c14997ff9ad7fc39e3f8d4245)), closes [#28](https://github.com/api-blitz/blitz-api-py/issues/28)
35
+
36
+ ## [3.0.0](https://github.com/api-blitz/blitz-api-py/compare/v2.2.0...v3.0.0) (2026-09-02)
37
+
38
+
39
+ ### ⚠ BREAKING CHANGES
40
+
41
+ * `KeyInfo.remaining_credits` is renamed to `KeyInfo.records_remaining`.
42
+
43
+ ### Features
44
+
45
+ * records vocabulary rename + fair_usage envelope on every response ([698fd6d](https://github.com/api-blitz/blitz-api-py/commit/698fd6dc95bbe6120c55064255820898b708da42))
46
+
3
47
  ## [2.2.0](https://github.com/api-blitz/blitz-api-py/compare/v2.1.0...v2.2.0) (2026-08-13)
4
48
 
5
49
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 2.2.0
3
+ Version: 4.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]] = []
@@ -161,14 +162,33 @@ later are preserved):
161
162
  ```python
162
163
  Person(
163
164
  full_name="Jordan Lee",
164
- headline="VP of Engineering at Acme",
165
+ # Derived from the first position as "<job title> | @<employer>" — not the
166
+ # free-text headline written on the LinkedIn profile.
167
+ headline="VP of Engineering | @Acme",
165
168
  linkedin_url="https://www.linkedin.com/in/example-person",
166
169
  location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
170
+ # Positions from the profile, in profile order — read `job_is_current` for the
171
+ # current role rather than assuming index 0.
167
172
  experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
168
173
  # first_name, last_name, skills, education, certifications, … also present
169
174
  )
170
175
  ```
171
176
 
177
+ **How many positions land in `experiences[]` depends on the endpoint** — and upstream
178
+ currently contradicts itself for `search.people`: the changelog entry of 2026-09-21 says
179
+ it returns only the position that matched your filters, while the API reference still
180
+ says it returns the full position history. Don't rely on either from a search result. If
181
+ you need the person's whole career in profile order, `enrichment.person` returns it
182
+ unambiguously (1 record on success, free on a miss):
183
+
184
+ ```python
185
+ if person.linkedin_url: # optional on Person; the call requires a str
186
+ result = client.enrichment.person(person_linkedin_url=person.linkedin_url)
187
+ if result.found and result.person:
188
+ for exp in result.person.experiences: # every position held, in profile order
189
+ print(exp.job_title, exp.company_name, exp.job_is_current)
190
+ ```
191
+
172
192
  And `enrichment.email(...)` returns:
173
193
 
174
194
  ```python
@@ -200,8 +220,8 @@ All methods are grouped into seven namespaces:
200
220
  | `client.account` | `key_info()` |
201
221
  | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
202
222
  | `client.jobs` | `search()`, `company()` |
203
- | `client.company` | `tam_by_jobs()` |
204
- | `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
223
+ | `client.company` | `tam_by_jobs()`, `tam_by_people()` |
224
+ | `client.enrichment` | `person()`, `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
205
225
  | `client.utils` | `current_date()` |
206
226
  | `client.changelog` | `list()` |
207
227
 
@@ -211,15 +231,15 @@ member or a raw string.
211
231
 
212
232
  ## Pagination
213
233
 
214
- The search and jobs methods return an **auto-paginating page**: iterate it and the SDK
215
- fetches each subsequent page for you. `search.people`/`search.companies` and
216
- `jobs.search`/`jobs.company` are cursor-based; `search.employee_finder` is page-based —
217
- all behave identically here.
234
+ The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
235
+ SDK fetches each subsequent page for you. `search.people`/`search.companies`,
236
+ `jobs.search`/`jobs.company` and `company.tam_by_jobs`/`company.tam_by_people` are
237
+ cursor-based; `search.employee_finder` is page-based — all behave identically here.
218
238
 
219
239
  > **`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(...)`
240
+ > **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
221
241
  > 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
242
+ > employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
223
243
  > `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
224
244
  > `break` out of the loop, or drive pages manually.
225
245
 
@@ -247,6 +267,13 @@ for job in client.jobs.search(
247
267
  ).auto_paging_iter(max_items=200):
248
268
  print(job.company_name, job.title, job.location.city if job.location else None)
249
269
 
270
+ # The TAM builders page the same way — distinct companies, each with its match count.
271
+ for match in client.company.tam_by_people(
272
+ company={"industry": {"include": ["Software Development"]}},
273
+ people={"job_level": ["VP"], "min_per_company": 3},
274
+ ).auto_paging_iter(max_items=200):
275
+ print(match.company.name if match.company else None, match.matched_people)
276
+
250
277
  # Or page manually.
251
278
  page = client.search.people(people={...}, max_results=50)
252
279
  print(page.results, page.cursor)
@@ -256,6 +283,37 @@ nxt = page.get_next_page() # None once exhausted
256
283
  The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
257
284
  exported from `blitz_api`.
258
285
 
286
+ ## Usage & rate limit (`fair_usage`)
287
+
288
+ Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
289
+ the plan, your rate-limit headroom, and a request id to quote to support. It's on every
290
+ response model and on every page, so you can meter a long run without extra `key_info()`
291
+ calls.
292
+
293
+ ```python
294
+ result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
295
+ if result.fair_usage is not None:
296
+ print(result.fair_usage.records_used) # what this call cost
297
+ print(result.fair_usage.records_remaining) # a number, or "unlimited"
298
+ print(result.fair_usage.next_reset_at) # None on an unlimited plan
299
+ print(result.fair_usage.request_id) # quote this to support
300
+ if result.fair_usage.rate_limit is not None: # absent on account.key_info()
301
+ print(result.fair_usage.rate_limit.remaining_this_second)
302
+
303
+ # Pages carry the block of the request that fetched them.
304
+ for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
305
+ print(page.fair_usage.records_used if page.fair_usage else None)
306
+ ```
307
+
308
+ `InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
309
+ resets without a second call:
310
+
311
+ ```python
312
+ except InsufficientRecordsError as err:
313
+ if err.fair_usage is not None:
314
+ print("resets at", err.fair_usage.next_reset_at)
315
+ ```
316
+
259
317
  ## Configuration
260
318
 
261
319
  ```python
@@ -271,11 +329,13 @@ client = BlitzAPI(
271
329
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
272
330
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
273
331
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
274
- endpoint (5 req/s by default; check yours via
275
- `client.account.key_info().max_requests_per_seconds`). A single client instance therefore
276
- stays under the limit on every endpoint, so a burst on one never blocks another. Across
277
- multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
278
- path handles that.
332
+ endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours
333
+ via `client.account.key_info().max_requests_per_seconds`). The default `5.0`
334
+ deliberately sits at half the *lowest* cap — raise it to your key's limit to use the
335
+ full budget. A single
336
+ client instance therefore stays under the limit on every endpoint, so a burst on one
337
+ never blocks another. Across multiple processes — which share an endpoint's budget — you
338
+ may still hit `429`; the retry path handles that.
279
339
 
280
340
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
281
341
  endpoint needs longer than the client default:
@@ -288,15 +348,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
288
348
 
289
349
  ```python
290
350
  from blitz_api import (
291
- BlitzError, AuthenticationError, InsufficientCreditsError,
351
+ BlitzError, AuthenticationError, InsufficientRecordsError,
292
352
  NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
293
353
  APITimeoutError, APIResponseValidationError,
294
354
  )
295
355
 
296
356
  try:
297
357
  client.enrichment.email(person_linkedin_url="...")
298
- except InsufficientCreditsError:
299
- ... # 402 — out of credits
358
+ except InsufficientRecordsError as err:
359
+ ... # 402 — out of records; err.fair_usage.next_reset_at
300
360
  except AuthenticationError:
301
361
  ... # 401 — bad key
302
362
  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]] = []
@@ -130,14 +131,33 @@ later are preserved):
130
131
  ```python
131
132
  Person(
132
133
  full_name="Jordan Lee",
133
- headline="VP of Engineering at Acme",
134
+ # Derived from the first position as "<job title> | @<employer>" — not the
135
+ # free-text headline written on the LinkedIn profile.
136
+ headline="VP of Engineering | @Acme",
134
137
  linkedin_url="https://www.linkedin.com/in/example-person",
135
138
  location=Location(city="San Francisco", state_code="CA", country_code="US", continent="North America"),
139
+ # Positions from the profile, in profile order — read `job_is_current` for the
140
+ # current role rather than assuming index 0.
136
141
  experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
137
142
  # first_name, last_name, skills, education, certifications, … also present
138
143
  )
139
144
  ```
140
145
 
146
+ **How many positions land in `experiences[]` depends on the endpoint** — and upstream
147
+ currently contradicts itself for `search.people`: the changelog entry of 2026-09-21 says
148
+ it returns only the position that matched your filters, while the API reference still
149
+ says it returns the full position history. Don't rely on either from a search result. If
150
+ you need the person's whole career in profile order, `enrichment.person` returns it
151
+ unambiguously (1 record on success, free on a miss):
152
+
153
+ ```python
154
+ if person.linkedin_url: # optional on Person; the call requires a str
155
+ result = client.enrichment.person(person_linkedin_url=person.linkedin_url)
156
+ if result.found and result.person:
157
+ for exp in result.person.experiences: # every position held, in profile order
158
+ print(exp.job_title, exp.company_name, exp.job_is_current)
159
+ ```
160
+
141
161
  And `enrichment.email(...)` returns:
142
162
 
143
163
  ```python
@@ -169,8 +189,8 @@ All methods are grouped into seven namespaces:
169
189
  | `client.account` | `key_info()` |
170
190
  | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
171
191
  | `client.jobs` | `search()`, `company()` |
172
- | `client.company` | `tam_by_jobs()` |
173
- | `client.enrichment` | `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
192
+ | `client.company` | `tam_by_jobs()`, `tam_by_people()` |
193
+ | `client.enrichment` | `person()`, `email()`, `phone()`, `email_to_person()`, `phone_to_person()`, `company()`, `domain_to_linkedin()`, `linkedin_to_domain()`, `company_distribution_by_country()`, `company_distribution_by_department()` |
174
194
  | `client.utils` | `current_date()` |
175
195
  | `client.changelog` | `list()` |
176
196
 
@@ -180,15 +200,15 @@ member or a raw string.
180
200
 
181
201
  ## Pagination
182
202
 
183
- The search and jobs methods return an **auto-paginating page**: iterate it and the SDK
184
- fetches each subsequent page for you. `search.people`/`search.companies` and
185
- `jobs.search`/`jobs.company` are cursor-based; `search.employee_finder` is page-based —
186
- all behave identically here.
203
+ The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
204
+ SDK fetches each subsequent page for you. `search.people`/`search.companies`,
205
+ `jobs.search`/`jobs.company` and `company.tam_by_jobs`/`company.tam_by_people` are
206
+ cursor-based; `search.employee_finder` is page-based — all behave identically here.
187
207
 
188
208
  > **`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(...)`
209
+ > **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
190
210
  > 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
211
+ > employee finder: 10k; jobs: 5k), which can be a lot of records. Bound it with **`max_items`** on
192
212
  > `.collect()` / `.auto_paging_iter()` (a client-side total cap — never sent on the wire),
193
213
  > `break` out of the loop, or drive pages manually.
194
214
 
@@ -216,6 +236,13 @@ for job in client.jobs.search(
216
236
  ).auto_paging_iter(max_items=200):
217
237
  print(job.company_name, job.title, job.location.city if job.location else None)
218
238
 
239
+ # The TAM builders page the same way — distinct companies, each with its match count.
240
+ for match in client.company.tam_by_people(
241
+ company={"industry": {"include": ["Software Development"]}},
242
+ people={"job_level": ["VP"], "min_per_company": 3},
243
+ ).auto_paging_iter(max_items=200):
244
+ print(match.company.name if match.company else None, match.matched_people)
245
+
219
246
  # Or page manually.
220
247
  page = client.search.people(people={...}, max_results=50)
221
248
  print(page.results, page.cursor)
@@ -225,6 +252,37 @@ nxt = page.get_next_page() # None once exhausted
225
252
  The page types (`CursorPage`, `PageNumberPage`, and their `Async*` variants) are
226
253
  exported from `blitz_api`.
227
254
 
255
+ ## Usage & rate limit (`fair_usage`)
256
+
257
+ Every `/v2` response carries a `fair_usage` block: what the call cost, what's left on
258
+ the plan, your rate-limit headroom, and a request id to quote to support. It's on every
259
+ response model and on every page, so you can meter a long run without extra `key_info()`
260
+ calls.
261
+
262
+ ```python
263
+ result = client.enrichment.email(person_linkedin_url="https://www.linkedin.com/in/example")
264
+ if result.fair_usage is not None:
265
+ print(result.fair_usage.records_used) # what this call cost
266
+ print(result.fair_usage.records_remaining) # a number, or "unlimited"
267
+ print(result.fair_usage.next_reset_at) # None on an unlimited plan
268
+ print(result.fair_usage.request_id) # quote this to support
269
+ if result.fair_usage.rate_limit is not None: # absent on account.key_info()
270
+ print(result.fair_usage.rate_limit.remaining_this_second)
271
+
272
+ # Pages carry the block of the request that fetched them.
273
+ for page in client.search.people(people={"job_level": ["VP"]}).iter_pages(max_pages=5):
274
+ print(page.fair_usage.records_used if page.fair_usage else None)
275
+ ```
276
+
277
+ `InsufficientRecordsError` (`402`) carries it too, so you can see when the balance
278
+ resets without a second call:
279
+
280
+ ```python
281
+ except InsufficientRecordsError as err:
282
+ if err.fair_usage is not None:
283
+ print("resets at", err.fair_usage.next_reset_at)
284
+ ```
285
+
228
286
  ## Configuration
229
287
 
230
288
  ```python
@@ -240,11 +298,13 @@ client = BlitzAPI(
240
298
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
241
299
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
242
300
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
243
- endpoint (5 req/s by default; check yours via
244
- `client.account.key_info().max_requests_per_seconds`). A single client instance therefore
245
- stays under the limit on every endpoint, so a burst on one never blocks another. Across
246
- multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
247
- path handles that.
301
+ endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours
302
+ via `client.account.key_info().max_requests_per_seconds`). The default `5.0`
303
+ deliberately sits at half the *lowest* cap — raise it to your key's limit to use the
304
+ full budget. A single
305
+ client instance therefore stays under the limit on every endpoint, so a burst on one
306
+ never blocks another. Across multiple processes — which share an endpoint's budget — you
307
+ may still hit `429`; the retry path handles that.
248
308
 
249
309
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
250
310
  endpoint needs longer than the client default:
@@ -257,15 +317,15 @@ client.search.people(people={"job_level": ["VP"]}, timeout=10.0)
257
317
 
258
318
  ```python
259
319
  from blitz_api import (
260
- BlitzError, AuthenticationError, InsufficientCreditsError,
320
+ BlitzError, AuthenticationError, InsufficientRecordsError,
261
321
  NotFoundError, RateLimitError, APIStatusError, APIConnectionError,
262
322
  APITimeoutError, APIResponseValidationError,
263
323
  )
264
324
 
265
325
  try:
266
326
  client.enrichment.email(person_linkedin_url="...")
267
- except InsufficientCreditsError:
268
- ... # 402 — out of credits
327
+ except InsufficientRecordsError as err:
328
+ ... # 402 — out of records; err.fair_usage.next_reset_at
269
329
  except AuthenticationError:
270
330
  ... # 401 — bad key
271
331
  except APIStatusError as err:
@@ -23,7 +23,7 @@ from ._exceptions import (
23
23
  APITimeoutError,
24
24
  AuthenticationError,
25
25
  BlitzError,
26
- InsufficientCreditsError,
26
+ InsufficientRecordsError,
27
27
  NotFoundError,
28
28
  RateLimitError,
29
29
  ServerError,
@@ -34,6 +34,7 @@ from ._version import __version__
34
34
  from .types import (
35
35
  CompanyFilter,
36
36
  Industry,
37
+ PeopleCompanyFilter,
37
38
  PeopleFilter,
38
39
  )
39
40
 
@@ -54,12 +55,13 @@ __all__ = [
54
55
  "APIResponseValidationError",
55
56
  "APIStatusError",
56
57
  "AuthenticationError",
57
- "InsufficientCreditsError",
58
+ "InsufficientRecordsError",
58
59
  "NotFoundError",
59
60
  "RateLimitError",
60
61
  "ServerError",
61
62
  # commonly-used types (full set under blitz_api.types)
62
63
  "Industry",
63
64
  "CompanyFilter",
65
+ "PeopleCompanyFilter",
64
66
  "PeopleFilter",
65
67
  ]
@@ -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
  }
@@ -93,7 +93,11 @@ class AsyncBlitzAPI(BaseClient):
93
93
  ) -> ResponseT:
94
94
  url = self._build_url(path)
95
95
  headers = self._build_headers()
96
+ # ``to_jsonable`` resolves enums and drops ``None`` at every depth, so resources
97
+ # build their body/params straight from their keyword arguments and never filter.
98
+ # Params need it as much as bodies do: httpx renders ``days=None`` as ``days=``.
96
99
  json_body = to_jsonable(body) if body is not None else None
100
+ query_params = to_jsonable(params) if params is not None else None
97
101
 
98
102
  attempt = 0
99
103
  while True:
@@ -101,11 +105,16 @@ class AsyncBlitzAPI(BaseClient):
101
105
  try:
102
106
  if timeout is None:
103
107
  response = await self._http_client.request(
104
- method, url, headers=headers, json=json_body, params=params
108
+ method, url, headers=headers, json=json_body, params=query_params
105
109
  )
106
110
  else:
107
111
  response = await self._http_client.request(
108
- method, url, headers=headers, json=json_body, params=params, timeout=timeout
112
+ method,
113
+ url,
114
+ headers=headers,
115
+ json=json_body,
116
+ params=query_params,
117
+ timeout=timeout,
109
118
  )
110
119
  except httpx.TimeoutException as exc:
111
120
  if self._should_retry_exception(exc) and attempt < self.max_retries:
@@ -95,7 +95,11 @@ class BlitzAPI(BaseClient):
95
95
  ) -> ResponseT:
96
96
  url = self._build_url(path)
97
97
  headers = self._build_headers()
98
+ # ``to_jsonable`` resolves enums and drops ``None`` at every depth, so resources
99
+ # build their body/params straight from their keyword arguments and never filter.
100
+ # Params need it as much as bodies do: httpx renders ``days=None`` as ``days=``.
98
101
  json_body = to_jsonable(body) if body is not None else None
102
+ query_params = to_jsonable(params) if params is not None else None
99
103
 
100
104
  attempt = 0
101
105
  while True:
@@ -103,11 +107,16 @@ class BlitzAPI(BaseClient):
103
107
  try:
104
108
  if timeout is None:
105
109
  response = self._http_client.request(
106
- method, url, headers=headers, json=json_body, params=params
110
+ method, url, headers=headers, json=json_body, params=query_params
107
111
  )
108
112
  else:
109
113
  response = self._http_client.request(
110
- method, url, headers=headers, json=json_body, params=params, timeout=timeout
114
+ method,
115
+ url,
116
+ headers=headers,
117
+ json=json_body,
118
+ params=query_params,
119
+ timeout=timeout,
111
120
  )
112
121
  except httpx.TimeoutException as exc:
113
122
  if self._should_retry_exception(exc) and attempt < self.max_retries:
@@ -19,8 +19,11 @@ DEFAULT_TIMEOUT = 30.0
19
19
  #: Number of retries (in addition to the first attempt) for transient failures.
20
20
  DEFAULT_MAX_RETRIES = 3
21
21
 
22
- #: Default client-side rate limit. The API allows 5 req/s on every plan; the
23
- #: per-key value is discoverable via ``client.account.key_info()``.
22
+ #: Default client-side rate limit, applied **per endpoint** (one sliding window each).
23
+ #: The API limits each endpoint to 10 req/s independently — 50 on plans created before
24
+ #: 2026-09-30 — so this default deliberately sits at half the *lowest* cap. It therefore
25
+ #: leaves throughput on the table by design: raise it to your key's actual per-endpoint
26
+ #: value, discoverable via ``client.account.key_info().max_requests_per_seconds``.
24
27
  DEFAULT_RATE_LIMIT_RPS = 5.0
25
28
 
26
29
  #: Seconds to wait after a 429 when the response has no ``Retry-After`` header.