blitz-api-py 3.0.0__tar.gz → 4.1.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-3.0.0 → blitz_api_py-4.1.0}/CHANGELOG.md +40 -0
  2. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/PKG-INFO +90 -13
  3. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/README.md +89 -12
  4. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/__init__.py +2 -3
  5. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client_async.py +11 -2
  6. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client_sync.py +11 -2
  7. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_constants.py +5 -2
  8. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_exceptions.py +0 -21
  9. blitz_api_py-4.1.0/src/blitz_api/_version.py +1 -0
  10. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/changelog.py +5 -8
  11. blitz_api_py-4.1.0/src/blitz_api/resources/_async/company.py +93 -0
  12. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/enrichment.py +40 -4
  13. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/jobs.py +8 -13
  14. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/search.py +42 -53
  15. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/changelog.py +5 -8
  16. blitz_api_py-4.1.0/src/blitz_api/resources/_sync/company.py +95 -0
  17. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/enrichment.py +40 -4
  18. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/jobs.py +8 -13
  19. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/search.py +42 -53
  20. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/__init__.py +20 -1
  21. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/_models.py +33 -2
  22. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/changelog.py +4 -13
  23. blitz_api_py-4.1.0/src/blitz_api/types/company.py +49 -0
  24. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/enrichment.py +28 -1
  25. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/enums.py +71 -0
  26. blitz_api_py-4.1.0/src/blitz_api/types/filters.py +438 -0
  27. blitz_api_py-4.1.0/src/blitz_api/types/shared.py +177 -0
  28. blitz_api_py-3.0.0/src/blitz_api/_version.py +0 -1
  29. blitz_api_py-3.0.0/src/blitz_api/resources/_async/company.py +0 -55
  30. blitz_api_py-3.0.0/src/blitz_api/resources/_sync/company.py +0 -57
  31. blitz_api_py-3.0.0/src/blitz_api/types/company.py +0 -31
  32. blitz_api_py-3.0.0/src/blitz_api/types/filters.py +0 -261
  33. blitz_api_py-3.0.0/src/blitz_api/types/shared.py +0 -120
  34. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/.gitignore +0 -0
  35. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/LICENSE +0 -0
  36. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/pyproject.toml +0 -0
  37. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_base_client.py +0 -0
  38. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_client.py +0 -0
  39. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_compat.py +0 -0
  40. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_async.py +0 -0
  41. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_base.py +0 -0
  42. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_pagination_sync.py +0 -0
  43. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit.py +0 -0
  44. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit_async.py +0 -0
  45. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  46. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/py.typed +0 -0
  47. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/__init__.py +0 -0
  48. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  49. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/account.py +0 -0
  50. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_async/utils.py +0 -0
  51. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  52. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/account.py +0 -0
  53. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  54. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/account.py +0 -0
  55. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/jobs.py +0 -0
  56. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/search.py +0 -0
  57. {blitz_api_py-3.0.0 → blitz_api_py-4.1.0}/src/blitz_api/types/utils.py +0 -0
@@ -1,5 +1,45 @@
1
1
  # Changelog
2
2
 
3
+ ## [4.1.0](https://github.com/api-blitz/blitz-api-py/compare/v4.0.0...v4.1.0) (2026-10-15)
4
+
5
+
6
+ ### Features
7
+
8
+ * sync the SDK to the 2026-09-28 → 2026-10-15 API releases ([#33](https://github.com/api-blitz/blitz-api-py/issues/33)) ([260320b](https://github.com/api-blitz/blitz-api-py/commit/260320bdedfeff466702c9d80e24ee21920ef450))
9
+
10
+ ## [4.0.0](https://github.com/api-blitz/blitz-api-py/compare/v3.0.0...v4.0.0) (2026-09-22)
11
+
12
+
13
+ ### ⚠ BREAKING CHANGES
14
+
15
+ * `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`).
16
+ * `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.
17
+ * `InsufficientCreditsError` is removed. Catch `InsufficientRecordsError` instead.
18
+ * `Education.field_of_study` is removed — the API folded it into `degree` ("Bachelor of Science, Industrial Engineering").
19
+
20
+ ### Features
21
+
22
+ * add the Industry.UNKNOWN bucket and document the range-filter 422 ([5f2d944](https://github.com/api-blitz/blitz-api-py/commit/5f2d944427b631b4b668af0bc99f614161b00425))
23
+ * remove the deprecated InsufficientCreditsError alias ([0c9be23](https://github.com/api-blitz/blitz-api-py/commit/0c9be232268cb68cfa36d7352e1304608bed32cc))
24
+ * 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)
25
+ * sync SDK to the 2026-09-11 / 2026-09-15 API releases ([81460ed](https://github.com/api-blitz/blitz-api-py/commit/81460edbcff5f985fd3e1498d70b282ce11d7550))
26
+
27
+
28
+ ### Bug Fixes
29
+
30
+ * remove phantom Company fields and the redundant _drop_none layer ([52b5ec5](https://github.com/api-blitz/blitz-api-py/commit/52b5ec5ec7241d2ea7dd6aacf2a3d0bbcc73dec2))
31
+
32
+
33
+ ### Documentation
34
+
35
+ * 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)
36
+ * 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)
37
+ * correct the stale rate-limit and spec-version facts ([10615d5](https://github.com/api-blitz/blitz-api-py/commit/10615d58b6f6d4905e1f00033032fd5fbf13a350))
38
+ * correct the stale response-schema rule and link the JS mirror PR ([1f1381f](https://github.com/api-blitz/blitz-api-py/commit/1f1381f164c0bc02b46a20ec94cec4c079375f44))
39
+ * guard the optional linkedin_url in the README enrichment example ([cdcfb71](https://github.com/api-blitz/blitz-api-py/commit/cdcfb71171131bf9400e99737b455ef7676c4b70))
40
+ * 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)
41
+ * 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)
42
+
3
43
  ## [3.0.0](https://github.com/api-blitz/blitz-api-py/compare/v2.2.0...v3.0.0) (2026-09-02)
4
44
 
5
45
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 3.0.0
3
+ Version: 4.1.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
@@ -162,14 +162,33 @@ later are preserved):
162
162
  ```python
163
163
  Person(
164
164
  full_name="Jordan Lee",
165
- 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",
166
168
  linkedin_url="https://www.linkedin.com/in/example-person",
167
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.
168
172
  experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
169
173
  # first_name, last_name, skills, education, certifications, … also present
170
174
  )
171
175
  ```
172
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
+
173
192
  And `enrichment.email(...)` returns:
174
193
 
175
194
  ```python
@@ -201,8 +220,8 @@ All methods are grouped into seven namespaces:
201
220
  | `client.account` | `key_info()` |
202
221
  | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
203
222
  | `client.jobs` | `search()`, `company()` |
204
- | `client.company` | `tam_by_jobs()` |
205
- | `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()` |
206
225
  | `client.utils` | `current_date()` |
207
226
  | `client.changelog` | `list()` |
208
227
 
@@ -210,12 +229,61 @@ Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
210
229
  filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
211
230
  member or a raw string.
212
231
 
232
+ ### Hiring signals and mail provider
233
+
234
+ ```python
235
+ from blitz_api import BlitzAPI
236
+ from blitz_api.types import JobLevel, MxProvider
237
+
238
+ client = BlitzAPI()
239
+
240
+ # VPs who started a job in the last 90 days, at companies on Google Workspace, who
241
+ # graduated in 2015 or later. `is_recent_hire` is a key of `people`.
242
+ page = client.search.people(
243
+ company={"mx": {"provider": {"include": [MxProvider.GOOGLE]}}},
244
+ people={
245
+ "job_level": [JobLevel.VP],
246
+ "education": {"end_year": {"min": 2015}},
247
+ "is_recent_hire": True,
248
+ },
249
+ )
250
+
251
+ # Also search jobs a person held before: your job and company filters must hold in the
252
+ # same job, which comes back in `experiences` with `job_is_current` set. Past jobs only:
253
+ client.search.people(people={"include_active_jobs": False, "include_past_jobs": True})
254
+
255
+ # The waterfall takes the same three flags per cascade tier: try recent hires first, then
256
+ # fall back to anyone in the role.
257
+ client.search.waterfall_icp(
258
+ company_linkedin_url="https://www.linkedin.com/company/openai",
259
+ cascade=[
260
+ {"include_title": ["CTO"], "is_recent_hire": True},
261
+ {"include_title": ["CTO"]},
262
+ ],
263
+ )
264
+ ```
265
+
266
+ Where the flags go depends on the route, and the API rejects a flag in the wrong place with a
267
+ `422`:
268
+
269
+ | Route | `is_recent_hire` | `include_active_jobs` / `include_past_jobs` |
270
+ | --- | --- | --- |
271
+ | `search.people` | key of `people` | key of `people` |
272
+ | `company.tam_by_people` | key of `people` | — |
273
+ | `search.waterfall_icp` | key of each `cascade` tier | key of each `cascade` tier |
274
+ | `search.employee_finder` | top-level argument | — |
275
+ | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
276
+
277
+ Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
278
+ *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
279
+ companies with none.
280
+
213
281
  ## Pagination
214
282
 
215
- The search and jobs methods return an **auto-paginating page**: iterate it and the SDK
216
- fetches each subsequent page for you. `search.people`/`search.companies` and
217
- `jobs.search`/`jobs.company` are cursor-based; `search.employee_finder` is page-based —
218
- all behave identically here.
283
+ The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
284
+ SDK fetches each subsequent page for you. `search.people`/`search.companies`,
285
+ `jobs.search`/`jobs.company` and `company.tam_by_jobs`/`company.tam_by_people` are
286
+ cursor-based; `search.employee_finder` is page-based — all behave identically here.
219
287
 
220
288
  > **`max_results` is the page size, not a total.** It's results per page, and the API
221
289
  > **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
@@ -248,6 +316,13 @@ for job in client.jobs.search(
248
316
  ).auto_paging_iter(max_items=200):
249
317
  print(job.company_name, job.title, job.location.city if job.location else None)
250
318
 
319
+ # The TAM builders page the same way — distinct companies, each with its match count.
320
+ for match in client.company.tam_by_people(
321
+ company={"industry": {"include": ["Software Development"]}},
322
+ people={"job_level": ["VP"], "min_per_company": 3},
323
+ ).auto_paging_iter(max_items=200):
324
+ print(match.company.name if match.company else None, match.matched_people)
325
+
251
326
  # Or page manually.
252
327
  page = client.search.people(people={...}, max_results=50)
253
328
  print(page.results, page.cursor)
@@ -303,11 +378,13 @@ client = BlitzAPI(
303
378
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
304
379
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
305
380
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
306
- endpoint (5 req/s by default; check yours via
307
- `client.account.key_info().max_requests_per_seconds`). A single client instance therefore
308
- stays under the limit on every endpoint, so a burst on one never blocks another. Across
309
- multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
310
- path handles that.
381
+ endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours
382
+ via `client.account.key_info().max_requests_per_seconds`). The default `5.0`
383
+ deliberately sits at half the *lowest* cap — raise it to your key's limit to use the
384
+ full budget. A single
385
+ client instance therefore stays under the limit on every endpoint, so a burst on one
386
+ never blocks another. Across multiple processes — which share an endpoint's budget — you
387
+ may still hit `429`; the retry path handles that.
311
388
 
312
389
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
313
390
  endpoint needs longer than the client default:
@@ -131,14 +131,33 @@ later are preserved):
131
131
  ```python
132
132
  Person(
133
133
  full_name="Jordan Lee",
134
- 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",
135
137
  linkedin_url="https://www.linkedin.com/in/example-person",
136
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.
137
141
  experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
138
142
  # first_name, last_name, skills, education, certifications, … also present
139
143
  )
140
144
  ```
141
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
+
142
161
  And `enrichment.email(...)` returns:
143
162
 
144
163
  ```python
@@ -170,8 +189,8 @@ All methods are grouped into seven namespaces:
170
189
  | `client.account` | `key_info()` |
171
190
  | `client.search` | `people()`, `companies()`, `employee_finder()`, `waterfall_icp()` |
172
191
  | `client.jobs` | `search()`, `company()` |
173
- | `client.company` | `tam_by_jobs()` |
174
- | `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()` |
175
194
  | `client.utils` | `current_date()` |
176
195
  | `client.changelog` | `list()` |
177
196
 
@@ -179,12 +198,61 @@ Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
179
198
  filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
180
199
  member or a raw string.
181
200
 
201
+ ### Hiring signals and mail provider
202
+
203
+ ```python
204
+ from blitz_api import BlitzAPI
205
+ from blitz_api.types import JobLevel, MxProvider
206
+
207
+ client = BlitzAPI()
208
+
209
+ # VPs who started a job in the last 90 days, at companies on Google Workspace, who
210
+ # graduated in 2015 or later. `is_recent_hire` is a key of `people`.
211
+ page = client.search.people(
212
+ company={"mx": {"provider": {"include": [MxProvider.GOOGLE]}}},
213
+ people={
214
+ "job_level": [JobLevel.VP],
215
+ "education": {"end_year": {"min": 2015}},
216
+ "is_recent_hire": True,
217
+ },
218
+ )
219
+
220
+ # Also search jobs a person held before: your job and company filters must hold in the
221
+ # same job, which comes back in `experiences` with `job_is_current` set. Past jobs only:
222
+ client.search.people(people={"include_active_jobs": False, "include_past_jobs": True})
223
+
224
+ # The waterfall takes the same three flags per cascade tier: try recent hires first, then
225
+ # fall back to anyone in the role.
226
+ client.search.waterfall_icp(
227
+ company_linkedin_url="https://www.linkedin.com/company/openai",
228
+ cascade=[
229
+ {"include_title": ["CTO"], "is_recent_hire": True},
230
+ {"include_title": ["CTO"]},
231
+ ],
232
+ )
233
+ ```
234
+
235
+ Where the flags go depends on the route, and the API rejects a flag in the wrong place with a
236
+ `422`:
237
+
238
+ | Route | `is_recent_hire` | `include_active_jobs` / `include_past_jobs` |
239
+ | --- | --- | --- |
240
+ | `search.people` | key of `people` | key of `people` |
241
+ | `company.tam_by_people` | key of `people` | — |
242
+ | `search.waterfall_icp` | key of each `cascade` tier | key of each `cascade` tier |
243
+ | `search.employee_finder` | top-level argument | — |
244
+ | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
245
+
246
+ Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
247
+ *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
248
+ companies with none.
249
+
182
250
  ## Pagination
183
251
 
184
- The search and jobs methods return an **auto-paginating page**: iterate it and the SDK
185
- fetches each subsequent page for you. `search.people`/`search.companies` and
186
- `jobs.search`/`jobs.company` are cursor-based; `search.employee_finder` is page-based —
187
- all behave identically here.
252
+ The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
253
+ SDK fetches each subsequent page for you. `search.people`/`search.companies`,
254
+ `jobs.search`/`jobs.company` and `company.tam_by_jobs`/`company.tam_by_people` are
255
+ cursor-based; `search.employee_finder` is page-based — all behave identically here.
188
256
 
189
257
  > **`max_results` is the page size, not a total.** It's results per page, and the API
190
258
  > **bills 1 record per result returned**. A bare `for person in client.search.people(...)`
@@ -217,6 +285,13 @@ for job in client.jobs.search(
217
285
  ).auto_paging_iter(max_items=200):
218
286
  print(job.company_name, job.title, job.location.city if job.location else None)
219
287
 
288
+ # The TAM builders page the same way — distinct companies, each with its match count.
289
+ for match in client.company.tam_by_people(
290
+ company={"industry": {"include": ["Software Development"]}},
291
+ people={"job_level": ["VP"], "min_per_company": 3},
292
+ ).auto_paging_iter(max_items=200):
293
+ print(match.company.name if match.company else None, match.matched_people)
294
+
220
295
  # Or page manually.
221
296
  page = client.search.people(people={...}, max_results=50)
222
297
  print(page.results, page.cursor)
@@ -272,11 +347,13 @@ client = BlitzAPI(
272
347
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
273
348
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
274
349
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
275
- endpoint (5 req/s by default; check yours via
276
- `client.account.key_info().max_requests_per_seconds`). A single client instance therefore
277
- stays under the limit on every endpoint, so a burst on one never blocks another. Across
278
- multiple processes — which share an endpoint's budget — you may still hit `429`; the retry
279
- path handles that.
350
+ endpoint (10 req/s on every plan — 50 on plans created before 2026-09-30; check yours
351
+ via `client.account.key_info().max_requests_per_seconds`). The default `5.0`
352
+ deliberately sits at half the *lowest* cap — raise it to your key's limit to use the
353
+ full budget. A single
354
+ client instance therefore stays under the limit on every endpoint, so a burst on one
355
+ never blocks another. Across multiple processes — which share an endpoint's budget — you
356
+ may still hit `429`; the retry path handles that.
280
357
 
281
358
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
282
359
  endpoint needs longer than the client default:
@@ -23,7 +23,6 @@ from ._exceptions import (
23
23
  APITimeoutError,
24
24
  AuthenticationError,
25
25
  BlitzError,
26
- InsufficientCreditsError, # pyright: ignore[reportDeprecated]
27
26
  InsufficientRecordsError,
28
27
  NotFoundError,
29
28
  RateLimitError,
@@ -35,6 +34,7 @@ from ._version import __version__
35
34
  from .types import (
36
35
  CompanyFilter,
37
36
  Industry,
37
+ PeopleCompanyFilter,
38
38
  PeopleFilter,
39
39
  )
40
40
 
@@ -59,10 +59,9 @@ __all__ = [
59
59
  "NotFoundError",
60
60
  "RateLimitError",
61
61
  "ServerError",
62
- # deprecated alias (removed in 3.0.0)
63
- "InsufficientCreditsError",
64
62
  # commonly-used types (full set under blitz_api.types)
65
63
  "Industry",
66
64
  "CompanyFilter",
65
+ "PeopleCompanyFilter",
67
66
  "PeopleFilter",
68
67
  ]
@@ -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.
@@ -14,9 +14,6 @@
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.
20
17
  """
21
18
 
22
19
  from __future__ import annotations
@@ -29,7 +26,6 @@ from .types._models import FairUsage
29
26
 
30
27
  if TYPE_CHECKING:
31
28
  import httpx
32
- from typing_extensions import deprecated
33
29
 
34
30
 
35
31
  def _parse_fair_usage(body: Any) -> FairUsage | None:
@@ -144,20 +140,3 @@ class RateLimitError(APIStatusError):
144
140
 
145
141
  class ServerError(APIStatusError):
146
142
  """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
@@ -0,0 +1 @@
1
+ __version__ = "4.1.0" # x-release-please-version
@@ -2,7 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from typing import TYPE_CHECKING, Any
5
+ from typing import TYPE_CHECKING
6
6
 
7
7
  from ..._compat import TimeoutParam
8
8
  from ...types.changelog import ChangelogEntry, ChangelogResponse
@@ -10,15 +10,12 @@ from ...types.changelog import ChangelogEntry, ChangelogResponse
10
10
  if TYPE_CHECKING:
11
11
  from ..._client import AsyncBlitzAPI
12
12
 
13
- # Public endpoint: NO ``/v2`` prefix, and the trailing slash is load-bearing.
13
+ # Public endpoint: NO ``/v2`` prefix. The trailing slash is what the spec declares;
14
+ # the API also answers ``/changelog`` (re-verified 2026-09-22 — both 200, no redirect),
15
+ # so it is not load-bearing, but keep it to match the spec.
14
16
  _CHANGELOG = "/changelog/"
15
17
 
16
18
 
17
- def _drop_none(**kwargs: Any) -> dict[str, Any]:
18
- """Build a query-param mapping keeping only the arguments the caller provided."""
19
- return {key: value for key, value in kwargs.items() if value is not None}
20
-
21
-
22
19
  class AsyncChangelogResource:
23
20
  def __init__(self, client: AsyncBlitzAPI) -> None:
24
21
  self._client = client
@@ -41,7 +38,7 @@ class AsyncChangelogResource:
41
38
  **not paginated**: it returns a plain list filtered by the ``days`` / ``limit``
42
39
  query parameters.
43
40
  """
44
- params = _drop_none(days=days, limit=limit)
41
+ params = {"days": days, "limit": limit}
45
42
  result = await self._client._request(
46
43
  "GET",
47
44
  _CHANGELOG,
@@ -0,0 +1,93 @@
1
+ """The Company resource: ``client.company``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING
6
+
7
+ from ..._compat import TimeoutParam
8
+ from ..._pagination_async import AsyncCursorPage
9
+ from ...types.company import TamByJobsMatch, TamByPeopleMatch
10
+ from ...types.filters import (
11
+ JobCompanyFilter,
12
+ PeopleCompanyFilter,
13
+ TamJobFilter,
14
+ TamPeopleFilter,
15
+ )
16
+
17
+ if TYPE_CHECKING:
18
+ from ..._client import AsyncBlitzAPI
19
+
20
+ _TAM_BY_JOBS = "/v2/company/tam-by-jobs"
21
+ _TAM_BY_PEOPLE = "/v2/company/tam-by-people"
22
+
23
+
24
+ class AsyncCompanyResource:
25
+ def __init__(self, client: AsyncBlitzAPI) -> None:
26
+ self._client = client
27
+
28
+ async def tam_by_jobs(
29
+ self,
30
+ *,
31
+ job: TamJobFilter | None = None,
32
+ company: JobCompanyFilter | None = None,
33
+ max_results: int | None = None,
34
+ cursor: str | None = None,
35
+ timeout: TimeoutParam = None,
36
+ ) -> AsyncCursorPage[TamByJobsMatch]:
37
+ """Build a Total Addressable Market of companies from live hiring signals.
38
+
39
+ Combine job-level filters (title, description, seniority, ...) with company
40
+ firmographics, and get back each matching company plus how many of its current
41
+ postings matched (``matched_jobs``). Use ``job["min_per_company"]`` to require a
42
+ minimum number of matching postings per company.
43
+
44
+ Cursor-paginated: auto-paginates over every ``{company, matched_jobs}`` match when
45
+ the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for manual
46
+ control. The API bills **1 record per result returned**; bound spend with
47
+ ``max_items`` on ``.collect()`` / ``.auto_paging_iter()``.
48
+ """
49
+ body = {"job": job, "company": company, "max_results": max_results, "cursor": cursor}
50
+ return await self._client._request(
51
+ "POST",
52
+ _TAM_BY_JOBS,
53
+ body=body,
54
+ cast_to=AsyncCursorPage[TamByJobsMatch],
55
+ timeout=timeout,
56
+ )
57
+
58
+ async def tam_by_people(
59
+ self,
60
+ *,
61
+ company: PeopleCompanyFilter | None = None,
62
+ people: TamPeopleFilter | None = None,
63
+ max_results: int | None = None,
64
+ cursor: str | None = None,
65
+ timeout: TimeoutParam = None,
66
+ ) -> AsyncCursorPage[TamByPeopleMatch]:
67
+ """Build a Total Addressable Market of companies from headcount signals.
68
+
69
+ Takes the same filters as ``search.people`` — company firmographics plus a
70
+ persona — but returns the **distinct companies** employing the matching people
71
+ (deduplicated), each with its ``matched_people`` count. Use
72
+ ``people["min_per_company"]`` to require a minimum number of matching employees
73
+ per company.
74
+
75
+ Set ``people["is_recent_hire"]`` to count only people with a job that started in the
76
+ last 90 days (the job must also match your other job and company filters; a job
77
+ with no start date never matches).
78
+
79
+ Cursor-paginated: auto-paginates over every ``{company, matched_people}`` match
80
+ when the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for
81
+ manual control. When ``min_per_company`` filters heavily a page may come back
82
+ partial — keep paging until the cursor is exhausted. The API bills **1 record per
83
+ result returned**; bound spend with ``max_items`` on ``.collect()`` /
84
+ ``.auto_paging_iter()``.
85
+ """
86
+ body = {"company": company, "people": people, "max_results": max_results, "cursor": cursor}
87
+ return await self._client._request(
88
+ "POST",
89
+ _TAM_BY_PEOPLE,
90
+ body=body,
91
+ cast_to=AsyncCursorPage[TamByPeopleMatch],
92
+ timeout=timeout,
93
+ )