blitz-api-py 4.1.0__tar.gz → 4.3.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.1.0 → blitz_api_py-4.3.0}/CHANGELOG.md +20 -0
  2. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/PKG-INFO +57 -20
  3. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/README.md +55 -18
  4. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/pyproject.toml +1 -1
  5. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_constants.py +5 -4
  6. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_exceptions.py +7 -2
  7. blitz_api_py-4.3.0/src/blitz_api/_version.py +1 -0
  8. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_async/enrichment.py +8 -3
  9. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_async/search.py +29 -3
  10. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_sync/enrichment.py +8 -3
  11. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_sync/search.py +29 -3
  12. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/enrichment.py +7 -1
  13. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/enums.py +1 -0
  14. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/filters.py +25 -16
  15. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/shared.py +12 -8
  16. blitz_api_py-4.1.0/src/blitz_api/_version.py +0 -1
  17. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/.gitignore +0 -0
  18. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/LICENSE +0 -0
  19. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/__init__.py +0 -0
  20. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_base_client.py +0 -0
  21. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_client.py +0 -0
  22. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_client_async.py +0 -0
  23. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_client_sync.py +0 -0
  24. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_compat.py +0 -0
  25. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_pagination_async.py +0 -0
  26. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_pagination_base.py +0 -0
  27. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_pagination_sync.py +0 -0
  28. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_rate_limit.py +0 -0
  29. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_rate_limit_async.py +0 -0
  30. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/_rate_limit_sync.py +0 -0
  31. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/py.typed +0 -0
  32. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/__init__.py +0 -0
  33. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_async/__init__.py +0 -0
  34. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_async/account.py +0 -0
  35. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_async/changelog.py +0 -0
  36. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_async/company.py +0 -0
  37. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_async/jobs.py +0 -0
  38. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_async/utils.py +0 -0
  39. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
  40. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_sync/account.py +0 -0
  41. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_sync/changelog.py +0 -0
  42. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_sync/company.py +0 -0
  43. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
  44. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/resources/_sync/utils.py +0 -0
  45. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/__init__.py +0 -0
  46. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/_models.py +0 -0
  47. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/account.py +0 -0
  48. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/changelog.py +0 -0
  49. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/company.py +0 -0
  50. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/jobs.py +0 -0
  51. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/search.py +0 -0
  52. {blitz_api_py-4.1.0 → blitz_api_py-4.3.0}/src/blitz_api/types/utils.py +0 -0
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## [4.3.0](https://github.com/api-blitz/blitz-api-py/compare/v4.2.0...v4.3.0) (2026-11-18)
4
+
5
+
6
+ ### Features
7
+
8
+ * add employee_finder job filters and job_duration_months ([#40](https://github.com/api-blitz/blitz-api-py/issues/40)) ([447565c](https://github.com/api-blitz/blitz-api-py/commit/447565cff93d394037814e7a0b223e257735d4f9))
9
+
10
+
11
+ ### Bug Fixes
12
+
13
+ * add the Artificial Intelligence industry to the generated enums ([#39](https://github.com/api-blitz/blitz-api-py/issues/39)) ([4d41d29](https://github.com/api-blitz/blitz-api-py/commit/4d41d2923e3d219beca2c05cf9849d7c840da658))
14
+
15
+ ## [4.2.0](https://github.com/api-blitz/blitz-api-py/compare/v4.1.0...v4.2.0) (2026-10-27)
16
+
17
+
18
+ ### Features
19
+
20
+ * sync with the 2026-10-20 API release ([00fb319](https://github.com/api-blitz/blitz-api-py/commit/00fb31984488fa64561dd23e136963dd0eaea7e1))
21
+ * sync with the 2026-10-20 API release ([aba0662](https://github.com/api-blitz/blitz-api-py/commit/aba066208f802d07b1a9fc1a44fd1e023c835e2c))
22
+
3
23
  ## [4.1.0](https://github.com/api-blitz/blitz-api-py/compare/v4.0.0...v4.1.0) (2026-10-15)
4
24
 
5
25
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: blitz-api-py
3
- Version: 4.1.0
3
+ Version: 4.3.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,30 @@ 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.
172
- experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
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
+ # `job_duration_months` counts the months in the position.
173
+ experiences=[
174
+ Experience(
175
+ job_title="VP of Engineering",
176
+ company_name="Acme",
177
+ job_is_current=True,
178
+ job_duration_months=19,
179
+ )
180
+ ],
173
181
  # first_name, last_name, skills, education, certifications, … also present
174
182
  )
175
183
  ```
176
184
 
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):
185
+ **How many positions land in `experiences[]` depends on the endpoint.** `search.people`,
186
+ `search.employee_finder` and `search.waterfall_icp` return one row per person, with only
187
+ the position that matched. If you need the person's whole career in profile order,
188
+ `enrichment.person` returns it (1 record on success, free on a miss):
183
189
 
184
190
  ```python
185
191
  if person.linkedin_url: # optional on Person; the call requires a str
@@ -274,6 +280,30 @@ Where the flags go depends on the route, and the API rejects a flag in the wrong
274
280
  | `search.employee_finder` | top-level argument | — |
275
281
  | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
276
282
 
283
+ `search.employee_finder` also takes `job_title` and `job_description`, each a dict with
284
+ `include` and `exclude` lists of phrases. They are matched against the person's current job
285
+ at the company, the same job as `job_level`, `job_function` and `is_recent_hire`. Wrap a
286
+ `job_title` phrase in `[brackets]` to match the whole title exactly; `job_description` has
287
+ no exact match. Each list takes up to 50 phrases (`job_description["exclude"]`: 20).
288
+
289
+ ```python
290
+ # Sales leaders at one company whose job description mentions Salesforce, interns left out.
291
+ employees = client.search.employee_finder(
292
+ company_linkedin_url="https://www.linkedin.com/company/openai",
293
+ job_title={"include": ["[Head of Sales]", "Account Executive"], "exclude": ["Intern"]},
294
+ job_description={"include": ["Salesforce"]},
295
+ )
296
+ for person in employees.auto_paging_iter(max_items=100):
297
+ job = person.experiences[0] if person.experiences else None
298
+ if job:
299
+ print(person.full_name, job.job_title, job.job_duration_months)
300
+ ```
301
+
302
+ Every `experiences[]` entry carries `job_duration_months`: the number of months in the
303
+ position, up to the current month for a current position and up to `job_end_date` for a past
304
+ one (the start and end months both count). It is `None` when `job_start_date` is missing, or
305
+ when a past position has no `job_end_date`.
306
+
277
307
  Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
278
308
  *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
279
309
  companies with none.
@@ -378,13 +408,14 @@ client = BlitzAPI(
378
408
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
379
409
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
380
410
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
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
411
+ endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale,
412
+ custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per
413
+ account, so every API key of the account shares it; check yours via
414
+ `client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial
415
+ limit — raise it to your key's limit to use the full budget. A single
385
416
  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.
417
+ never blocks another. Across multiple processes (or several keys of one account) — which
418
+ share an endpoint's budget — you may still hit `429`; the retry path handles that.
388
419
 
389
420
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
390
421
  endpoint needs longer than the client default:
@@ -407,7 +438,7 @@ try:
407
438
  except InsufficientRecordsError as err:
408
439
  ... # 402 — out of records; err.fair_usage.next_reset_at
409
440
  except AuthenticationError:
410
- ... # 401 — bad key
441
+ ... # 401 — missing/invalid key, or no access to this endpoint
411
442
  except APIStatusError as err:
412
443
  print(err.status_code, err.message, err.body)
413
444
  except APIResponseValidationError:
@@ -417,10 +448,16 @@ except BlitzError:
417
448
  ```
418
449
 
419
450
  `429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
420
- `401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
451
+ `401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried,
421
452
  but a **read timeout is not** — the server may already have processed (and billed) the
422
453
  request, so it surfaces as `APITimeoutError` rather than risking a double charge.
423
454
 
455
+ An invalid request body (including an unknown field at any depth) raises `APIStatusError`
456
+ with `status_code == 422`: `err.message` sums up the first three problems, and
457
+ `err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the
458
+ full field path and what to fix. A locked account gets `423`
459
+ (`{"blocked": true, "message": ...}`), also raised as `APIStatusError`.
460
+
424
461
  ## Forward compatibility
425
462
 
426
463
  Response models subclass a base configured with `extra="allow"`, so a field the API adds
@@ -131,24 +131,30 @@ 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.
141
- experiences=[Experience(job_title="VP of Engineering", company_name="Acme", job_is_current=True)],
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
+ # `job_duration_months` counts the months in the position.
142
+ experiences=[
143
+ Experience(
144
+ job_title="VP of Engineering",
145
+ company_name="Acme",
146
+ job_is_current=True,
147
+ job_duration_months=19,
148
+ )
149
+ ],
142
150
  # first_name, last_name, skills, education, certifications, … also present
143
151
  )
144
152
  ```
145
153
 
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):
154
+ **How many positions land in `experiences[]` depends on the endpoint.** `search.people`,
155
+ `search.employee_finder` and `search.waterfall_icp` return one row per person, with only
156
+ the position that matched. If you need the person's whole career in profile order,
157
+ `enrichment.person` returns it (1 record on success, free on a miss):
152
158
 
153
159
  ```python
154
160
  if person.linkedin_url: # optional on Person; the call requires a str
@@ -243,6 +249,30 @@ Where the flags go depends on the route, and the API rejects a flag in the wrong
243
249
  | `search.employee_finder` | top-level argument | — |
244
250
  | `enrichment.company_distribution_by_country` / `_by_department` | top-level argument | — |
245
251
 
252
+ `search.employee_finder` also takes `job_title` and `job_description`, each a dict with
253
+ `include` and `exclude` lists of phrases. They are matched against the person's current job
254
+ at the company, the same job as `job_level`, `job_function` and `is_recent_hire`. Wrap a
255
+ `job_title` phrase in `[brackets]` to match the whole title exactly; `job_description` has
256
+ no exact match. Each list takes up to 50 phrases (`job_description["exclude"]`: 20).
257
+
258
+ ```python
259
+ # Sales leaders at one company whose job description mentions Salesforce, interns left out.
260
+ employees = client.search.employee_finder(
261
+ company_linkedin_url="https://www.linkedin.com/company/openai",
262
+ job_title={"include": ["[Head of Sales]", "Account Executive"], "exclude": ["Intern"]},
263
+ job_description={"include": ["Salesforce"]},
264
+ )
265
+ for person in employees.auto_paging_iter(max_items=100):
266
+ job = person.experiences[0] if person.experiences else None
267
+ if job:
268
+ print(person.full_name, job.job_title, job.job_duration_months)
269
+ ```
270
+
271
+ Every `experiences[]` entry carries `job_duration_months`: the number of months in the
272
+ position, up to the current month for a current position and up to `job_end_date` for a past
273
+ one (the start and end months both count). It is `None` when `job_start_date` is missing, or
274
+ when a past position has no `job_end_date`.
275
+
246
276
  Setting both `include_*_jobs` flags to `False` is a `422`. `MxProvider.ANY` stands for
247
277
  *every* provider: in `include` it keeps companies with mail data, in `exclude` it keeps
248
278
  companies with none.
@@ -347,13 +377,14 @@ client = BlitzAPI(
347
377
  The client-side rate limiter is a sliding window — at most `rate_limit_rps` requests
348
378
  in any rolling second — applied **per endpoint**: each endpoint (e.g. `.email` vs
349
379
  `.phone`) is throttled independently, mirroring the API's own limit, which is also per
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
380
+ endpoint and set by your plan (5 req/s on the free trial, 10 on Start, 25 on Scale,
381
+ custom on Build Your Infra; 50 on plans created before 2026-09-30). The API counts it per
382
+ account, so every API key of the account shares it; check yours via
383
+ `client.account.key_info().max_requests_per_seconds`. The default `5.0` is the free-trial
384
+ limit — raise it to your key's limit to use the full budget. A single
354
385
  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.
386
+ never blocks another. Across multiple processes (or several keys of one account) — which
387
+ share an endpoint's budget — you may still hit `429`; the retry path handles that.
357
388
 
358
389
  Every method also accepts a per-call `timeout` (seconds or an `httpx.Timeout`) when one
359
390
  endpoint needs longer than the client default:
@@ -376,7 +407,7 @@ try:
376
407
  except InsufficientRecordsError as err:
377
408
  ... # 402 — out of records; err.fair_usage.next_reset_at
378
409
  except AuthenticationError:
379
- ... # 401 — bad key
410
+ ... # 401 — missing/invalid key, or no access to this endpoint
380
411
  except APIStatusError as err:
381
412
  print(err.status_code, err.message, err.body)
382
413
  except APIResponseValidationError:
@@ -386,10 +417,16 @@ except BlitzError:
386
417
  ```
387
418
 
388
419
  `429` and `5xx` are retried automatically (with backoff) up to `max_retries`;
389
- `401`/`402`/`404` raise immediately. Connect timeouts and connection errors are retried,
420
+ `401`/`402`/`404`/`422`/`423` raise immediately. Connect timeouts and connection errors are retried,
390
421
  but a **read timeout is not** — the server may already have processed (and billed) the
391
422
  request, so it surfaces as `APITimeoutError` rather than risking a double charge.
392
423
 
424
+ An invalid request body (including an unknown field at any depth) raises `APIStatusError`
425
+ with `status_code == 422`: `err.message` sums up the first three problems, and
426
+ `err.body["errors"]` lists up to 20 of them, each as `{"field": ..., "message": ...}` with the
427
+ full field path and what to fix. A locked account gets `423`
428
+ (`{"blocked": true, "message": ...}`), also raised as `APIStatusError`.
429
+
393
430
  ## Forward compatibility
394
431
 
395
432
  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.3.0" # x-release-please-version
@@ -173,10 +173,15 @@ class AsyncEnrichmentResource:
173
173
  ) -> CompanyDistributionByDepartmentResponse:
174
174
  """Get a company's employee count broken down by department.
175
175
 
176
- 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``.
177
180
 
178
- ``is_recent_hire=True`` counts only people whose current job at the company started
179
- in the last 90 days (a job with no start date is not counted).
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).
180
185
  """
181
186
  return await self._client._request(
182
187
  "POST",
@@ -12,6 +12,7 @@ from ...types.filters import (
12
12
  ContinentValue,
13
13
  JobFunctionValue,
14
14
  JobLevelValue,
15
+ KeywordFilter,
15
16
  PeopleCompanyFilter,
16
17
  PeopleFilter,
17
18
  SalesRegionValue,
@@ -84,6 +85,8 @@ class AsyncSearchResource:
84
85
  sales_region: list[SalesRegionValue] | None = None,
85
86
  job_level: list[JobLevelValue] | None = None,
86
87
  job_function: list[JobFunctionValue] | None = None,
88
+ job_title: KeywordFilter | None = None,
89
+ job_description: KeywordFilter | None = None,
87
90
  min_connections_count: int | None = None,
88
91
  is_recent_hire: bool | None = None,
89
92
  max_results: int | None = None,
@@ -92,9 +95,25 @@ class AsyncSearchResource:
92
95
  ) -> AsyncPageNumberPage[Person]:
93
96
  """Search employees at a single company, with page-based pagination.
94
97
 
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
+ ``job_level``, ``job_function``, ``job_title``, ``job_description`` and
99
+ ``is_recent_hire`` must all hold in the same job: the person's **current** job at
100
+ the company.
101
+
102
+ ``job_title`` and ``job_description`` each take ``include`` / ``exclude`` lists of
103
+ phrases. A title matches when it has every word of at least one ``include`` phrase;
104
+ wrap a phrase in brackets (``"[Head of Sales]"``) to match the whole title exactly,
105
+ ignoring case and accents. A description matches when every word of a phrase appears
106
+ in it, in any order (only its first 10,000 characters are searched); brackets give
107
+ no exact match there. ``exclude`` drops a job that matches any phrase, and
108
+ ``job_description["exclude"]`` never drops a job with no description.
109
+
110
+ ``is_recent_hire=True`` keeps only people whose job started in the last 90 days (a
111
+ job with no start date never matches).
112
+
113
+ Each list is capped at 50 entries, except ``job_description["exclude"]`` (20); a
114
+ longer one is a ``422``. ``country_code``
115
+ defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
116
+ filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
98
117
 
99
118
  Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
100
119
  for manual control.
@@ -106,6 +125,8 @@ class AsyncSearchResource:
106
125
  "sales_region": sales_region,
107
126
  "job_level": job_level,
108
127
  "job_function": job_function,
128
+ "job_title": job_title,
129
+ "job_description": job_description,
109
130
  "min_connections_count": min_connections_count,
110
131
  "is_recent_hire": is_recent_hire,
111
132
  "max_results": max_results,
@@ -138,6 +159,11 @@ class AsyncSearchResource:
138
159
  ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
139
160
  held *before* at the company; the company and that tier's title filters must then hold
140
161
  in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
162
+
163
+ Each tier's ``location`` takes the same object as ``people.location`` on
164
+ ``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match
165
+ every field you set, and leaving it out searches the whole world. Here each list takes
166
+ at most 10 values (a longer one is a ``422``).
141
167
  """
142
168
  body = {
143
169
  "company_linkedin_url": company_linkedin_url,
@@ -175,10 +175,15 @@ class EnrichmentResource:
175
175
  ) -> CompanyDistributionByDepartmentResponse:
176
176
  """Get a company's employee count broken down by department.
177
177
 
178
- 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``.
179
182
 
180
- ``is_recent_hire=True`` counts only people whose current job at the company started
181
- in the last 90 days (a job with no start date is not counted).
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).
182
187
  """
183
188
  return self._client._request(
184
189
  "POST",
@@ -14,6 +14,7 @@ from ...types.filters import (
14
14
  ContinentValue,
15
15
  JobFunctionValue,
16
16
  JobLevelValue,
17
+ KeywordFilter,
17
18
  PeopleCompanyFilter,
18
19
  PeopleFilter,
19
20
  SalesRegionValue,
@@ -86,6 +87,8 @@ class SearchResource:
86
87
  sales_region: list[SalesRegionValue] | None = None,
87
88
  job_level: list[JobLevelValue] | None = None,
88
89
  job_function: list[JobFunctionValue] | None = None,
90
+ job_title: KeywordFilter | None = None,
91
+ job_description: KeywordFilter | None = None,
89
92
  min_connections_count: int | None = None,
90
93
  is_recent_hire: bool | None = None,
91
94
  max_results: int | None = None,
@@ -94,9 +97,25 @@ class SearchResource:
94
97
  ) -> PageNumberPage[Person]:
95
98
  """Search employees at a single company, with page-based pagination.
96
99
 
97
- ``is_recent_hire=True`` keeps only people whose **current** job at the company
98
- started in the last 90 days (that job must also match ``job_level`` and
99
- ``job_function``; a job with no start date never matches).
100
+ ``job_level``, ``job_function``, ``job_title``, ``job_description`` and
101
+ ``is_recent_hire`` must all hold in the same job: the person's **current** job at
102
+ the company.
103
+
104
+ ``job_title`` and ``job_description`` each take ``include`` / ``exclude`` lists of
105
+ phrases. A title matches when it has every word of at least one ``include`` phrase;
106
+ wrap a phrase in brackets (``"[Head of Sales]"``) to match the whole title exactly,
107
+ ignoring case and accents. A description matches when every word of a phrase appears
108
+ in it, in any order (only its first 10,000 characters are searched); brackets give
109
+ no exact match there. ``exclude`` drops a job that matches any phrase, and
110
+ ``job_description["exclude"]`` never drops a job with no description.
111
+
112
+ ``is_recent_hire=True`` keeps only people whose job started in the last 90 days (a
113
+ job with no start date never matches).
114
+
115
+ Each list is capped at 50 entries, except ``job_description["exclude"]`` (20); a
116
+ longer one is a ``422``. ``country_code``
117
+ defaults to ``["WORLD"]`` server-side: a list holding ``"WORLD"`` drops the country
118
+ filter. ``min_connections_count`` runs 0-500 (``0`` = no lower bound).
100
119
 
101
120
  Auto-paginates over every matching employee; use ``.iter_pages()`` or ``page=``
102
121
  for manual control.
@@ -108,6 +127,8 @@ class SearchResource:
108
127
  "sales_region": sales_region,
109
128
  "job_level": job_level,
110
129
  "job_function": job_function,
130
+ "job_title": job_title,
131
+ "job_description": job_description,
111
132
  "min_connections_count": min_connections_count,
112
133
  "is_recent_hire": is_recent_hire,
113
134
  "max_results": max_results,
@@ -140,6 +161,11 @@ class SearchResource:
140
161
  ``include_past_jobs``. With ``include_past_jobs`` a tier finds people by a job they
141
162
  held *before* at the company; the company and that tier's title filters must then hold
142
163
  in the **same** job, which is returned in ``experiences`` with ``job_is_current`` set.
164
+
165
+ Each tier's ``location`` takes the same object as ``people.location`` on
166
+ ``search.people`` (:class:`~blitz_api.types.PeopleLocationFilter`): a person must match
167
+ every field you set, and leaving it out searches the whole world. Here each list takes
168
+ at most 10 values (a longer one is a ``422``).
143
169
  """
144
170
  body = {
145
171
  "company_linkedin_url": company_linkedin_url,
@@ -142,7 +142,9 @@ class CompanyDistributionByCountryResponse(BlitzResponse):
142
142
  class CompanyDistributionByDepartmentItem(BlitzModel):
143
143
  """Employee count for a single department (Blitz job function).
144
144
 
145
- Employees with no classified department are counted under ``"Other"``.
145
+ ``count`` counts current jobs at the company, not people, once per current job: a person
146
+ with two current jobs there counts twice in ``total_employees`` (once in each job's
147
+ department). Jobs with no classified department are counted under ``"Other"``.
146
148
  ``percentage_ratio`` is the bucket's share of ``total_employees`` (0-100, to 2
147
149
  decimals).
148
150
  """
@@ -157,6 +159,10 @@ class CompanyDistributionByDepartmentResponse(BlitzResponse):
157
159
 
158
160
  Served by ``POST /v2/enrichment/company-distribution-by-department``.
159
161
 
162
+ ``total_employees`` counts current jobs at the company, not people (a person with two
163
+ current jobs there counts twice), so it can exceed the one from
164
+ ``enrichment.company_distribution_by_country``.
165
+
160
166
  ``found`` is ``False`` (and the call costs no records) when the company is unknown or
161
167
  has no current employees.
162
168
  """
@@ -54,6 +54,7 @@ class Industry(str, Enum):
54
54
  ARCHITECTURAL_AND_STRUCTURAL_METAL_MANUFACTURING = 'Architectural and Structural Metal Manufacturing'
55
55
  ARCHITECTURE_AND_PLANNING = 'Architecture and Planning'
56
56
  ARMED_FORCES = 'Armed Forces'
57
+ ARTIFICIAL_INTELLIGENCE = 'Artificial Intelligence'
57
58
  ARTIFICIAL_RUBBER_AND_SYNTHETIC_FIBER_MANUFACTURING = 'Artificial Rubber and Synthetic Fiber Manufacturing'
58
59
  ARTISTS_AND_WRITERS = 'Artists and Writers'
59
60
  ARTS_AND_CRAFTS = 'Arts and Crafts'
@@ -6,8 +6,9 @@ fields accept either an enum member (autocompleted, e.g. ``Industry.BANKING``) o
6
6
  a raw string, so power users are never blocked.
7
7
 
8
8
  All keys are optional unless noted; omit a filter to leave it unset. The search
9
- endpoints cap every filter list at **50 entries** — a longer list is rejected with a
10
- ``422``, so split a bigger inclusion/exclusion set across several requests.
9
+ endpoints cap every filter list at **50 entries** (10 in a waterfall tier's ``location``,
10
+ see :class:`CascadeTier`) — a longer list is rejected with a ``422``, so split a bigger
11
+ inclusion/exclusion set across several requests.
11
12
  """
12
13
 
13
14
  from __future__ import annotations
@@ -143,7 +144,7 @@ class CompanyFilter(TypedDict, total=False):
143
144
  ``company.tam_by_people``.
144
145
 
145
146
  ``linkedin_url`` is deliberately **not** here: only the people-side endpoints honour
146
- it, and ``search.companies`` accepts-then-ignores it. See :class:`PeopleCompanyFilter`.
147
+ it, and ``search.companies`` rejects it with a ``422``. See :class:`PeopleCompanyFilter`.
147
148
  """
148
149
 
149
150
  name: KeywordFilter
@@ -176,11 +177,9 @@ class PeopleCompanyFilter(CompanyFilter, total=False):
176
177
  Extending, rather than leaving ``linkedin_url`` on the shared filter, keeps it off
177
178
  ``search.companies``: the live spec declares it on the ``company`` object of
178
179
  ``/v2/search/people`` and ``/v2/company/tam-by-people`` but **not**
179
- ``/v2/search/companies``, and request schemas are open (no ``additionalProperties:
180
- false``), so that endpoint accepts the key and silently returns results for your other
181
- criteria. That is the same accepted-but-ignored failure mode that got ``linkedin_url``
182
- removed from :class:`PeopleFilter`, and the same split as :class:`TamPeopleFilter` over
183
- :class:`PeopleFilter`.
180
+ ``/v2/search/companies``, which rejects the key with a ``422`` naming the field (since
181
+ 2026-09-28; it used to be accepted and ignored). Same split as :class:`TamPeopleFilter`
182
+ over :class:`PeopleFilter`.
184
183
 
185
184
  The assignability caveat on :class:`TamJobFilter` applies verbatim: this only rejects a
186
185
  ``search.companies`` call site that passes a *dict literal* carrying ``linkedin_url``.
@@ -202,9 +201,12 @@ class PeopleJobTitleFilter(TypedDict, total=False):
202
201
 
203
202
 
204
203
  class PeopleLocationFilter(TypedDict, total=False):
205
- """Location filter for the people side of a people search."""
204
+ """Location filter for the people side of a people search, and for each waterfall tier
205
+ (:class:`CascadeTier`). A person must match every field you set.
206
+ """
206
207
 
207
208
  city: KeywordFilter
209
+ # Codes such as ``"FR"`` or ``"GB"`` (2-3 letters, any case).
208
210
  country_code: list[str]
209
211
  continent: list[ContinentValue]
210
212
  sales_region: list[SalesRegionValue]
@@ -227,9 +229,8 @@ class PeopleFilter(TypedDict, total=False):
227
229
  """People search criteria for ``search.people``.
228
230
 
229
231
  ``linkedin_url`` is deliberately absent: ``/v2/search/people`` stopped honouring it
230
- on 2026-09-11 (the request still succeeds, but the filter is *ignored*, so you get
231
- results for your other criteria instead of the people you asked for). Match specific
232
- people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`),
232
+ on 2026-09-11, and since 2026-09-28 rejects it with a ``422`` naming the field. Match
233
+ specific people by LinkedIn URL with ``company.tam_by_people`` (:class:`TamPeopleFilter`),
233
234
  which still accepts it.
234
235
 
235
236
  This is the persona criteria ``search.people`` and ``company.tam_by_people`` share;
@@ -246,6 +247,7 @@ class PeopleFilter(TypedDict, total=False):
246
247
  job_title: PeopleJobTitleFilter
247
248
  job_function: list[JobFunctionValue]
248
249
  job_level: list[JobLevelValue]
250
+ # Smallest LinkedIn connection count (0-500, ``0`` = no lower bound); above 500 is a ``422``.
249
251
  min_connections: int
250
252
  location: PeopleLocationFilter
251
253
  # ``| KeywordFilter`` is deliberate: this field was a ``KeywordFilter`` before it gained
@@ -286,9 +288,16 @@ class SearchPeopleFilter(PeopleFilter, total=False):
286
288
  class CascadeTier(TypedDict):
287
289
  """One tier of a waterfall ICP cascade, tried in order until results are found.
288
290
 
289
- Only ``include_title`` is required; the server defaults ``location`` to worldwide
290
- and ``include_headline_search`` to ``False`` when omitted. The ``cascade`` list is
291
- capped at **10 tiers**, and each tier at 50 title phrases.
291
+ Only ``include_title`` is required; the server defaults ``include_headline_search`` to
292
+ ``False`` when omitted. The ``cascade`` list is capped at **10 tiers**, and each tier at
293
+ 50 title phrases.
294
+
295
+ ``location`` takes the same object as ``people.location`` on ``search.people``
296
+ (:class:`PeopleLocationFilter`): a person must match every field you set, and leaving it
297
+ out searches the whole world. Each list in it takes at most **10 values**; a longer list
298
+ is a ``422``. A plain list of country codes (``["US", "CA"]``) is the legacy form, still
299
+ accepted: it is read as ``country_code``, with the same 10-code cap, and a list holding
300
+ ``"WORLD"`` turns the location filter off.
292
301
 
293
302
  ``is_recent_hire``, ``include_active_jobs`` and ``include_past_jobs`` are per-tier keys,
294
303
  not arguments of ``search.waterfall_icp``: each tier can scope its own search, so a
@@ -296,7 +305,7 @@ class CascadeTier(TypedDict):
296
305
  """
297
306
 
298
307
  include_title: list[str]
299
- location: NotRequired[list[str]]
308
+ location: NotRequired[PeopleLocationFilter | list[str]]
300
309
  include_headline_search: NotRequired[bool]
301
310
  exclude_title: NotRequired[list[str]]
302
311
  # Only people whose job at the company started in the last 90 days. It covers the jobs
@@ -58,6 +58,11 @@ class Experience(BlitzModel):
58
58
  job_start_date: str | None = None
59
59
  job_end_date: str | None = None
60
60
  job_is_current: bool | None = None
61
+ #: Months the person has held the position: up to the current month for a current
62
+ #: position, up to ``job_end_date`` for a past one. The start and end months both count,
63
+ #: so a position that started this month gives ``1``. ``None`` when ``job_start_date``
64
+ #: is missing, or when a past position has no ``job_end_date``.
65
+ job_duration_months: int | None = None
61
66
  #: How the role is contracted, e.g. ``"Full-time"``, ``"Contract"``, ``"Internship"``.
62
67
  job_contract_type: str | None = None
63
68
  #: Where the work is performed, e.g. ``"Remote"``, ``"Hybrid"``, ``"On-site"``.
@@ -95,8 +100,8 @@ class Person(BlitzModel):
95
100
  full_name: str | None = None
96
101
  nickname: str | None = None
97
102
  civility_title: str | None = None
98
- #: Built from the person's first position as ``"<job title> | @<employer>"``, not
99
- #: the free-text headline written on the LinkedIn profile.
103
+ #: Built from the first entry of ``experiences`` (the matched position on the searches)
104
+ #: as ``"<job title> | @<employer>"``, not the free-text headline on the LinkedIn profile.
100
105
  headline: str | None = None
101
106
  about_me: str | None = None
102
107
  location: Location | None = None
@@ -104,12 +109,11 @@ class Person(BlitzModel):
104
109
  connections_count: int | None = None
105
110
  #: Always ``None`` since 2026-09-15; the API keeps the key so clients don't break.
106
111
  profile_picture_url: str | None = None
107
- #: Positions from the person's profile, in profile order. **How many** positions land
108
- #: here depends on the endpoint, and upstream currently contradicts itself for
109
- #: ``search.people``: the changelog entry of 2026-09-21 says it returns only the
110
- #: position that matched your filters, while the docs still say the whole career.
111
- #: ``enrichment.person`` returns the whole career either way. Read ``job_is_current``
112
- #: rather than assuming index 0 is the current role.
112
+ #: Positions from the person's profile. ``search.people``, ``search.employee_finder`` and
113
+ #: ``search.waterfall_icp`` return exactly one: the position that matched, which can be a
114
+ #: past one with ``include_past_jobs`` (read ``job_is_current``). ``enrichment.person``,
115
+ #: ``enrichment.email_to_person`` and ``enrichment.phone_to_person`` return the whole
116
+ #: career, in profile order.
113
117
  experiences: BlitzList[Experience] = []
114
118
  education: BlitzList[Education] = []
115
119
  skills: BlitzList[str] = []
@@ -1 +0,0 @@
1
- __version__ = "4.1.0" # x-release-please-version
File without changes
File without changes