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.
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/CHANGELOG.md +15 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/PKG-INFO +73 -19
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/README.md +71 -17
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/pyproject.toml +1 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_constants.py +5 -4
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_exceptions.py +7 -2
- blitz_api_py-4.2.0/src/blitz_api/_version.py +1 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/company.py +4 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/enrichment.py +27 -5
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/search.py +28 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/company.py +4 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/enrichment.py +27 -5
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/search.py +28 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/__init__.py +12 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/_models.py +7 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/enrichment.py +23 -2
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/enums.py +70 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/filters.py +136 -20
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/shared.py +46 -22
- blitz_api_py-4.0.0/src/blitz_api/_version.py +0 -1
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/.gitignore +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/LICENSE +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/__init__.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_base_client.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_client.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_client_async.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_client_sync.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_compat.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_async.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_base.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_pagination_sync.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit_async.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/_rate_limit_sync.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/py.typed +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/__init__.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/__init__.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/account.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/changelog.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/jobs.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_async/utils.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/__init__.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/account.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/changelog.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/jobs.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/resources/_sync/utils.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/account.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/changelog.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/company.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/jobs.py +0 -0
- {blitz_api_py-4.0.0 → blitz_api_py-4.2.0}/src/blitz_api/types/search.py +0 -0
- {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.
|
|
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,
|
|
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
|
|
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
|
-
#
|
|
171
|
-
# current
|
|
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
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
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 (
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
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
|
|
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 —
|
|
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
|
|
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
|
-
#
|
|
140
|
-
# current
|
|
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
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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 (
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
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
|
|
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 —
|
|
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", "
|
|
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
|
|
24
|
-
#:
|
|
25
|
-
#:
|
|
26
|
-
#: value, discoverable via
|
|
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 —
|
|
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,
|
|
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,
|
|
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
|
-
|
|
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,
|
|
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,
|
|
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
|
-
|
|
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
|
)
|