blitz-api-py 4.0.0__tar.gz → 4.2.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 (52) hide show
  1. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/CHANGELOG.md +15 -0
  2. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/PKG-INFO +73 -19
  3. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/README.md +71 -17
  4. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/pyproject.toml +1 -1
  5. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_constants.py +5 -4
  6. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_exceptions.py +7 -2
  7. blitz_api_py-4.2.0/src/blitz_api/_version.py +1 -0
  8. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/company.py +4 -0
  9. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/enrichment.py +27 -5
  10. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/search.py +28 -1
  11. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/company.py +4 -0
  12. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/enrichment.py +27 -5
  13. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/search.py +28 -1
  14. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/__init__.py +12 -0
  15. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/_models.py +7 -0
  16. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/enrichment.py +23 -2
  17. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/enums.py +70 -0
  18. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/filters.py +136 -20
  19. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/shared.py +46 -22
  20. blitz_api_py-4.0.0/src/blitz_api/_version.py +0 -1
  21. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/.gitignore +0 -0
  22. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/LICENSE +0 -0
  23. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/__init__.py +0 -0
  24. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_base_client.py +0 -0
  25. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_client.py +0 -0
  26. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_client_async.py +0 -0
  27. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_client_sync.py +0 -0
  28. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_compat.py +0 -0
  29. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_async.py +0 -0
  30. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_base.py +0 -0
  31. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_sync.py +0 -0
  32. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit.py +0 -0
  33. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit_async.py +0 -0
  34. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  35. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/py.typed +0 -0
  36. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/__init__.py +0 -0
  37. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  38. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/account.py +0 -0
  39. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/changelog.py +0 -0
  40. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/jobs.py +0 -0
  41. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/utils.py +0 -0
  42. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  43. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/account.py +0 -0
  44. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/changelog.py +0 -0
  45. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
  46. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  47. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/account.py +0 -0
  48. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/changelog.py +0 -0
  49. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/company.py +0 -0
  50. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/jobs.py +0 -0
  51. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/search.py +0 -0
  52. {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/utils.py +0 -0
@@ -1,5 +1,20 @@
1
1
  # Changelog
2
2
 
3
+ ## [4.2.0](https://github.com/api-blitz/blitz-api-py/compare/v4.1.0...v4.2.0) (2026-10-27)
4
+
5
+
6
+ ### Features
7
+
8
+ * sync with the 2026-10-20 API release ([00fb319](https://github.com/api-blitz/blitz-api-py/commit/00fb31984488fa64561dd23e136963dd0eaea7e1))
9
+ * sync with the 2026-10-20 API release ([aba0662](https://github.com/api-blitz/blitz-api-py/commit/aba066208f802d07b1a9fc1a44fd1e023c835e2c))
10
+
11
+ ## [4.1.0](https://github.com/api-blitz/blitz-api-py/compare/v4.0.0...v4.1.0) (2026-10-15)
12
+
13
+
14
+ ### Features
15
+
16
+ * 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))
17
+
3
18
  ## [4.0.0](https://github.com/api-blitz/blitz-api-py/compare/v3.0.0...v4.0.0) (2026-09-22)
4
19
 
5
20
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 4.0.0
3
+ Version: 4.2.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
@@ -10,7 +10,7 @@ Project-URL: Changelog, https://github.com/api-blitz/blitz-api-py/blob/main/CHAN
10
10
  Author-email: Blitz API <founders@blitz-api.ai>
11
11
  License-Expression: MIT
12
12
  License-File: LICENSE
13
- Keywords: b2b,blitz,blitz-api,enrichment,gtm,linkedin,sales,sdk
13
+ Keywords: b2b,blitz,blitz-api,enrichment,gtm,sales,sdk
14
14
  Classifier: Development Status :: 4 - Beta
15
15
  Classifier: Intended Audience :: Developers
16
16
  Classifier: License :: OSI Approved :: MIT License
@@ -162,24 +162,22 @@ later are preserved):
162
162
  ```python
163
163
  Person(
164
164
  full_name="Jordan Lee",
165
- # Derived from the first position as "<job title> | @<employer>" — not the
165
+ # Derived from the matched position as "<job title> | @<employer>" — not the
166
166
  # free-text headline written on the LinkedIn profile.
167
167
  headline="VP of Engineering | @Acme",
168
168
  linkedin_url="https://www.linkedin.com/in/example-person",
169
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.
170
+ # Only the position that matched your filters — `job_is_current` says whether it
171
+ # is current (past jobs are searched only with `include_past_jobs`).
172
172
  experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
173
173
  # first_name, last_name, skills, education, certifications, … also present
174
174
  )
175
175
  ```
176
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):
177
+ **How many positions land in `experiences[]` depends on the endpoint.** `search.people`,
178
+ `search.employee_finder` and `search.waterfall_icp` return one row per person, with only
179
+ the position that matched. If you need the person's whole career in profile order,
180
+ `enrichment.person` returns it (1 record on success, free on a miss):
183
181
 
184
182
  ```python
185
183
  if person.linkedin_url: # optional on Person; the call requires a str
@@ -229,6 +227,55 @@ Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
229
227
  filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
230
228
  member or a raw string.
231
229
 
230
+ ### Hiring signals and mail provider
231
+
232
+ ```python
233
+ from blitz_api import BlitzAPI
234
+ from blitz_api.types import JobLevel, MxProvider
235
+
236
+ client = BlitzAPI()
237
+
238
+ # VPs who started a job in the last 90 days, at companies on Google Workspace, who
239
+ # graduated in 2015 or later. `is_recent_hire` is a key of `people`.
240
+ page = client.search.people(
241
+ company={"mx": {"provider": {"include": [MxProvider.GOOGLE]}}},
242
+ people={
243
+ "job_level": [JobLevel.VP],
244
+ "education": {"end_year": {"min": 2015}},
245
+ "is_recent_hire": True,
246
+ },
247
+ )
248
+
249
+ # Also search jobs a person held before: your job and company filters must hold in the
250
+ # same job, which comes back in `experiences` with `job_is_current` set. Past jobs only:
251
+ client.search.people(people={"include_active_jobs": False, "include_past_jobs": True})
252
+
253
+ # The waterfall takes the same three flags per cascade tier: try recent hires first, then
254
+ # fall back to anyone in the role.
255
+ client.search.waterfall_icp(
256
+ company_linkedin_url="https://www.linkedin.com/company/openai",
257
+ cascade=[
258
+ {"include_title": ["CTO"], "is_recent_hire": True},
259
+ {"include_title": ["CTO"]},
260
+ ],
261
+ )
262
+ ```
263
+
264
+ Where the flags go depends on the route, and the API rejects a flag in the wrong place with a
265
+ `422`:
266
+
267
+ | Route | `is_recent_hire` | `include_active_jobs` / `include_past_jobs` |
268
+ | --- | --- | --- |
269
+ | `search.people` | key of `people` | key of `people` |
270
+ | `company.tam_by_people` | key of `people` | — |
271
+ | `search.waterfall_icp` | key of each `cascade` tier | key of each `cascade` tier |
272
+ | `search.employee_finder` | top-level argument | — |
273
+ | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
274
+
275
+ Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
276
+ *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
277
+ companies with none.
278
+
232
279
  ## Pagination
233
280
 
234
281
  The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
@@ -329,13 +376,14 @@ client = BlitzAPI(
329
376
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
330
377
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
331
378
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
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
379
+ endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale,
380
+ custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per
381
+ account, so every API key of the account shares it; check yours via
382
+ `client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial
383
+ limit — raise it to your key's limit to use the full budget. A single
336
384
  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.
385
+ never blocks another. Across multiple processes (or several keys of one account) — which
386
+ share an endpoint's budget — you may still hit `429`; the retry path handles that.
339
387
 
340
388
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
341
389
  endpoint needs longer than the client default:
@@ -358,7 +406,7 @@ try:
358
406
  except InsufficientRecordsError as err:
359
407
  ... # 402 — out of records; err.fair_usage.next_reset_at
360
408
  except AuthenticationError:
361
- ... # 401 — bad key
409
+ ... # 401 — missing/invalid key, or no access to this endpoint
362
410
  except APIStatusError as err:
363
411
  print(err.status_code, err.message, err.body)
364
412
  except APIResponseValidationError:
@@ -368,10 +416,16 @@ except BlitzError:
368
416
  ```
369
417
 
370
418
  `429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
371
- `401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
419
+ `401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried,
372
420
  but a **read timeout is not** — the server may already have processed (and billed) the
373
421
  request, so it surfaces as `APITimeoutError` rather than risking a double charge.
374
422
 
423
+ An invalid request body (including an unknown field at any depth) raises `APIStatusError`
424
+ with `status_code == 422`: `err.message` sums up the first three problems, and
425
+ `err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the
426
+ full field path and what to fix. A locked account gets `423`
427
+ (`{"blocked": true, "message": ...}`), also raised as `APIStatusError`.
428
+
375
429
  ## Forward compatibility
376
430
 
377
431
  Response models subclass a base configured with `extra="allow"`, so a field the API adds
@@ -131,24 +131,22 @@ later are preserved):
131
131
  ```python
132
132
  Person(
133
133
  full_name="Jordan Lee",
134
- # Derived from the first position as "<job title> | @<employer>" — not the
134
+ # Derived from the matched position as "<job title> | @<employer>" — not the
135
135
  # free-text headline written on the LinkedIn profile.
136
136
  headline="VP of Engineering | @Acme",
137
137
  linkedin_url="https://www.linkedin.com/in/example-person",
138
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.
139
+ # Only the position that matched your filters — `job_is_current` says whether it
140
+ # is current (past jobs are searched only with `include_past_jobs`).
141
141
  experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
142
142
  # first_name, last_name, skills, education, certifications, … also present
143
143
  )
144
144
  ```
145
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):
146
+ **How many positions land in `experiences[]` depends on the endpoint.** `search.people`,
147
+ `search.employee_finder` and `search.waterfall_icp` return one row per person, with only
148
+ the position that matched. If you need the person's whole career in profile order,
149
+ `enrichment.person` returns it (1 record on success, free on a miss):
152
150
 
153
151
  ```python
154
152
  if person.linkedin_url: # optional on Person; the call requires a str
@@ -198,6 +196,55 @@ Every method returns a typed Pydantic model (see `blitz_api.types`). Enum-backed
198
196
  filter fields (e.g. `Industry`, `JobLevel`, `Continent`) accept either an enum
199
197
  member or a raw string.
200
198
 
199
+ ### Hiring signals and mail provider
200
+
201
+ ```python
202
+ from blitz_api import BlitzAPI
203
+ from blitz_api.types import JobLevel, MxProvider
204
+
205
+ client = BlitzAPI()
206
+
207
+ # VPs who started a job in the last 90 days, at companies on Google Workspace, who
208
+ # graduated in 2015 or later. `is_recent_hire` is a key of `people`.
209
+ page = client.search.people(
210
+ company={"mx": {"provider": {"include": [MxProvider.GOOGLE]}}},
211
+ people={
212
+ "job_level": [JobLevel.VP],
213
+ "education": {"end_year": {"min": 2015}},
214
+ "is_recent_hire": True,
215
+ },
216
+ )
217
+
218
+ # Also search jobs a person held before: your job and company filters must hold in the
219
+ # same job, which comes back in `experiences` with `job_is_current` set. Past jobs only:
220
+ client.search.people(people={"include_active_jobs": False, "include_past_jobs": True})
221
+
222
+ # The waterfall takes the same three flags per cascade tier: try recent hires first, then
223
+ # fall back to anyone in the role.
224
+ client.search.waterfall_icp(
225
+ company_linkedin_url="https://www.linkedin.com/company/openai",
226
+ cascade=[
227
+ {"include_title": ["CTO"], "is_recent_hire": True},
228
+ {"include_title": ["CTO"]},
229
+ ],
230
+ )
231
+ ```
232
+
233
+ Where the flags go depends on the route, and the API rejects a flag in the wrong place with a
234
+ `422`:
235
+
236
+ | Route | `is_recent_hire` | `include_active_jobs` / `include_past_jobs` |
237
+ | --- | --- | --- |
238
+ | `search.people` | key of `people` | key of `people` |
239
+ | `company.tam_by_people` | key of `people` | — |
240
+ | `search.waterfall_icp` | key of each `cascade` tier | key of each `cascade` tier |
241
+ | `search.employee_finder` | top-level argument | — |
242
+ | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
243
+
244
+ Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
245
+ *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
246
+ companies with none.
247
+
201
248
  ## Pagination
202
249
 
203
250
  The search, jobs and TAM methods return an **auto-paginating page**: iterate it and the
@@ -298,13 +345,14 @@ client = BlitzAPI(
298
345
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
299
346
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
300
347
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
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
348
+ endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale,
349
+ custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per
350
+ account, so every API key of the account shares it; check yours via
351
+ `client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial
352
+ limit — raise it to your key's limit to use the full budget. A single
305
353
  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.
354
+ never blocks another. Across multiple processes (or several keys of one account) — which
355
+ share an endpoint's budget — you may still hit `429`; the retry path handles that.
308
356
 
309
357
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
310
358
  endpoint needs longer than the client default:
@@ -327,7 +375,7 @@ try:
327
375
  except InsufficientRecordsError as err:
328
376
  ... # 402 — out of records; err.fair_usage.next_reset_at
329
377
  except AuthenticationError:
330
- ... # 401 — bad key
378
+ ... # 401 — missing/invalid key, or no access to this endpoint
331
379
  except APIStatusError as err:
332
380
  print(err.status_code, err.message, err.body)
333
381
  except APIResponseValidationError:
@@ -337,10 +385,16 @@ except BlitzError:
337
385
  ```
338
386
 
339
387
  `429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
340
- `401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
388
+ `401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried,
341
389
  but a **read timeout is not** — the server may already have processed (and billed) the
342
390
  request, so it surfaces as `APITimeoutError` rather than risking a double charge.
343
391
 
392
+ An invalid request body (including an unknown field at any depth) raises `APIStatusError`
393
+ with `status_code == 422`: `err.message` sums up the first three problems, and
394
+ `err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the
395
+ full field path and what to fix. A locked account gets `423`
396
+ (`{"blocked": true, "message": ...}`), also raised as `APIStatusError`.
397
+
344
398
  ## Forward compatibility
345
399
 
346
400
  Response models subclass a base configured with `extra="allow"`, so a field the API adds
@@ -11,7 +11,7 @@ requires-python = ">=3.10"
11
11
  license = "MIT"
12
12
  license-files = ["LICENSE"]
13
13
  authors = [{ name = "Blitz API", email = "founders@blitz-api.ai" }]
14
- keywords = ["blitz", "blitz-api", "b2b", "enrichment", "linkedin", "sales", "gtm", "sdk"]
14
+ keywords = ["blitz", "blitz-api", "b2b", "enrichment", "sales", "gtm", "sdk"]
15
15
  classifiers = [
16
16
  "Development Status :: 4 - Beta",
17
17
  "Intended Audience :: Developers",
@@ -20,10 +20,11 @@ DEFAULT_TIMEOUT = 30.0
20
20
  DEFAULT_MAX_RETRIES = 3
21
21
 
22
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``.
23
+ #: The API limits each endpoint independently, per account, at a rate set by the plan: 5 req/s
24
+ #: on the free trial, 10 on Start, 25 on Scale, custom on Build Your Infra (50 on plans created
25
+ #: before 2026-09-30). This default is the free-trial limit, so it leaves throughput on the
26
+ #: table on paid plans: raise it to your key's actual per-endpoint value, discoverable via
27
+ #: ``client.account.key_info().max_requests_per_seconds``.
27
28
  DEFAULT_RATE_LIMIT_RPS = 5.0
28
29
 
29
30
  #: Seconds to wait after a 429 when the response has no ``Retry-After`` header.
@@ -119,7 +119,11 @@ class APIStatusError(BlitzError):
119
119
 
120
120
 
121
121
  class AuthenticationError(APIStatusError):
122
- """401 — the API key is missing or invalid."""
122
+ """401 — the API key is missing or invalid, or valid but without access to this endpoint
123
+ (``"You do not have access to this route"``).
124
+
125
+ A locked account gets a ``423`` instead, raised as a plain :class:`APIStatusError`.
126
+ """
123
127
 
124
128
 
125
129
  class InsufficientRecordsError(APIStatusError):
@@ -131,7 +135,8 @@ class InsufficientRecordsError(APIStatusError):
131
135
 
132
136
 
133
137
  class NotFoundError(APIStatusError):
134
- """404 — the API key or resource does not exist."""
138
+ """404 — unknown path, or ``account.key_info`` found no billing account
139
+ (``"Customer not found"``). An unknown key is a ``401``."""
135
140
 
136
141
 
137
142
  class RateLimitError(APIStatusError):
@@ -0,0 +1 @@
1
+ __version__ = "4.2.0" # x-release-please-version
@@ -72,6 +72,10 @@ class AsyncCompanyResource:
72
72
  ``people["min_per_company"]`` to require a minimum number of matching employees
73
73
  per company.
74
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
+
75
79
  Cursor-paginated: auto-paginates over every ``{company, matched_people}`` match
76
80
  when the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for
77
81
  manual control. When ``min_per_company`` filters heavily a page may come back
@@ -139,32 +139,54 @@ class AsyncEnrichmentResource:
139
139
  )
140
140
 
141
141
  async def company_distribution_by_country(
142
- self, *, company_linkedin_url: str, timeout: TimeoutParam = None
142
+ self,
143
+ *,
144
+ company_linkedin_url: str,
145
+ is_recent_hire: bool | None = None,
146
+ timeout: TimeoutParam = None,
143
147
  ) -> CompanyDistributionByCountryResponse:
144
148
  """Get a company's employee count broken down by country.
145
149
 
150
+ Counts **people**, not jobs: since 2026-10-14 a person with a second job at the
151
+ company is no longer counted twice in ``count`` / ``total_employees``.
152
+
146
153
  Countries are reported as ISO 3166-1 alpha-2 codes (e.g. ``US``, ``GB``);
147
154
  employees whose country can't be determined are bucketed under ``"unknown"``.
155
+
156
+ ``is_recent_hire=True`` counts only people whose current job at the company started
157
+ in the last 90 days (a job with no start date is not counted).
148
158
  """
149
159
  return await self._client._request(
150
160
  "POST",
151
161
  _DISTRIBUTION_BY_COUNTRY,
152
- body={"company_linkedin_url": company_linkedin_url},
162
+ body={"company_linkedin_url": company_linkedin_url, "is_recent_hire": is_recent_hire},
153
163
  cast_to=CompanyDistributionByCountryResponse,
154
164
  timeout=timeout,
155
165
  )
156
166
 
157
167
  async def company_distribution_by_department(
158
- self, *, company_linkedin_url: str, timeout: TimeoutParam = None
168
+ self,
169
+ *,
170
+ company_linkedin_url: str,
171
+ is_recent_hire: bool | None = None,
172
+ timeout: TimeoutParam = None,
159
173
  ) -> CompanyDistributionByDepartmentResponse:
160
174
  """Get a company's employee count broken down by department.
161
175
 
162
- Employees with no classified department are counted under ``"Other"``.
176
+ Counts current **jobs** at the company, not people, once per current job: a person with
177
+ two current jobs there counts twice in ``total_employees`` (once in each job's
178
+ department), so ``total_employees`` can exceed the one from
179
+ ``company_distribution_by_country``.
180
+
181
+ Jobs with no classified department are counted under ``"Other"``.
182
+
183
+ ``is_recent_hire=True`` counts only the current jobs at the company that started in the
184
+ last 90 days (a job with no start date is not counted).
163
185
  """
164
186
  return await self._client._request(
165
187
  "POST",
166
188
  _DISTRIBUTION_BY_DEPARTMENT,
167
- body={"company_linkedin_url": company_linkedin_url},
189
+ body={"company_linkedin_url": company_linkedin_url, "is_recent_hire": is_recent_hire},
168
190
  cast_to=CompanyDistributionByDepartmentResponse,
169
191
  timeout=timeout,
170
192
  )
@@ -15,6 +15,7 @@ from ...types.filters import (
15
15
  PeopleCompanyFilter,
16
16
  PeopleFilter,
17
17
  SalesRegionValue,
18
+ SearchPeopleFilter,
18
19
  )
19
20
  from ...types.search import WaterfallIcpResponse
20
21
  from ...types.shared import Company, Person
@@ -36,13 +37,18 @@ class AsyncSearchResource:
36
37
  self,
37
38
  *,
38
39
  company: PeopleCompanyFilter | None = None,
39
- people: PeopleFilter | None = None,
40
+ people: SearchPeopleFilter | PeopleFilter | None = None,
40
41
  max_results: int | None = None,
41
42
  cursor: str | None = None,
42
43
  timeout: TimeoutParam = None,
43
44
  ) -> AsyncCursorPage[Person]:
44
45
  """Search people across many companies, combining company and persona filters.
45
46
 
47
+ Which of a person's jobs are searched is set in ``people``: ``is_recent_hire``
48
+ (job started in the last 90 days), ``include_active_jobs`` and ``include_past_jobs``
49
+ (see :class:`~blitz_api.types.SearchPeopleFilter`). Your job and company filters must hold
50
+ in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
51
+
46
52
  Auto-paginates over every matching person when the result is iterated; use
47
53
  ``.iter_pages()`` or the ``cursor=`` arg for manual control.
48
54
  """
@@ -79,12 +85,21 @@ class AsyncSearchResource:
79
85
  job_level: list[JobLevelValue] | None = None,
80
86
  job_function: list[JobFunctionValue] | None = None,
81
87
  min_connections_count: int | None = None,
88
+ is_recent_hire: bool | None = None,
82
89
  max_results: int | None = None,
83
90
  page: int | None = None,
84
91
  timeout: TimeoutParam = None,
85
92
  ) -> AsyncPageNumberPage[Person]:
86
93
  """Search employees at a single company, with page-based pagination.
87
94
 
95
+ ``is_recent_hire=True`` keeps only people whose **current** job at the company
96
+ started in the last 90 days (that job must also match ``job_level`` and
97
+ ``job_function``; a job with no start date never matches).
98
+
99
+ Each list is capped at 50 entries (a longer one is a ``422``). ``country_code``
100
+ defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
101
+ filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
102
+
88
103
  Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
89
104
  for manual control.
90
105
  """
@@ -96,6 +111,7 @@ class AsyncSearchResource:
96
111
  "job_level": job_level,
97
112
  "job_function": job_function,
98
113
  "min_connections_count": min_connections_count,
114
+ "is_recent_hire": is_recent_hire,
99
115
  "max_results": max_results,
100
116
  "page": page,
101
117
  }
@@ -120,6 +136,17 @@ class AsyncSearchResource:
120
136
 
121
137
  ``profile_min_connections`` sets the minimum LinkedIn connections for a match
122
138
  (server defaults to ``0`` — i.e. **no** floor — when omitted).
139
+
140
+ Recent-hire and past-job scoping is per tier, set on each :class:`CascadeTier`:
141
+ ``is_recent_hire`` (job started in the last 90 days), ``include_active_jobs`` and
142
+ ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
143
+ held *before* at the company; the company and that tier's title filters must then hold
144
+ in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
145
+
146
+ Each tier's ``location`` takes the same object as ``people.location`` on
147
+ ``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match
148
+ every field you set, and leaving it out searches the whole world. Here each list takes
149
+ at most 10 values (a longer one is a ``422``).
123
150
  """
124
151
  body = {
125
152
  "company_linkedin_url": company_linkedin_url,
@@ -74,6 +74,10 @@ class CompanyResource:
74
74
  ``people["min_per_company"]`` to require a minimum number of matching employees
75
75
  per company.
76
76
 
77
+ Set ``people["is_recent_hire"]`` to count only people with a job that started in the
78
+ last 90 days (the job must also match your other job and company filters; a job
79
+ with no start date never matches).
80
+
77
81
  Cursor-paginated: auto-paginates over every ``{company, matched_people}`` match
78
82
  when the result is iterated; use ``.iter_pages()`` or the ``cursor=`` arg for
79
83
  manual control. When ``min_per_company`` filters heavily a page may come back
@@ -141,32 +141,54 @@ class EnrichmentResource:
141
141
  )
142
142
 
143
143
  def company_distribution_by_country(
144
- self, *, company_linkedin_url: str, timeout: TimeoutParam = None
144
+ self,
145
+ *,
146
+ company_linkedin_url: str,
147
+ is_recent_hire: bool | None = None,
148
+ timeout: TimeoutParam = None,
145
149
  ) -> CompanyDistributionByCountryResponse:
146
150
  """Get a company's employee count broken down by country.
147
151
 
152
+ Counts **people**, not jobs: since 2026-10-14 a person with a second job at the
153
+ company is no longer counted twice in ``count`` / ``total_employees``.
154
+
148
155
  Countries are reported as ISO 3166-1 alpha-2 codes (e.g. ``US``, ``GB``);
149
156
  employees whose country can't be determined are bucketed under ``"unknown"``.
157
+
158
+ ``is_recent_hire=True`` counts only people whose current job at the company started
159
+ in the last 90 days (a job with no start date is not counted).
150
160
  """
151
161
  return self._client._request(
152
162
  "POST",
153
163
  _DISTRIBUTION_BY_COUNTRY,
154
- body={"company_linkedin_url": company_linkedin_url},
164
+ body={"company_linkedin_url": company_linkedin_url, "is_recent_hire": is_recent_hire},
155
165
  cast_to=CompanyDistributionByCountryResponse,
156
166
  timeout=timeout,
157
167
  )
158
168
 
159
169
  def company_distribution_by_department(
160
- self, *, company_linkedin_url: str, timeout: TimeoutParam = None
170
+ self,
171
+ *,
172
+ company_linkedin_url: str,
173
+ is_recent_hire: bool | None = None,
174
+ timeout: TimeoutParam = None,
161
175
  ) -> CompanyDistributionByDepartmentResponse:
162
176
  """Get a company's employee count broken down by department.
163
177
 
164
- Employees with no classified department are counted under ``"Other"``.
178
+ Counts current **jobs** at the company, not people, once per current job: a person with
179
+ two current jobs there counts twice in ``total_employees`` (once in each job's
180
+ department), so ``total_employees`` can exceed the one from
181
+ ``company_distribution_by_country``.
182
+
183
+ Jobs with no classified department are counted under ``"Other"``.
184
+
185
+ ``is_recent_hire=True`` counts only the current jobs at the company that started in the
186
+ last 90 days (a job with no start date is not counted).
165
187
  """
166
188
  return self._client._request(
167
189
  "POST",
168
190
  _DISTRIBUTION_BY_DEPARTMENT,
169
- body={"company_linkedin_url": company_linkedin_url},
191
+ body={"company_linkedin_url": company_linkedin_url, "is_recent_hire": is_recent_hire},
170
192
  cast_to=CompanyDistributionByDepartmentResponse,
171
193
  timeout=timeout,
172
194
  )