curl https://api.avina.io/v1/people/search/$SEARCH_ID/status \
-H "Authorization: Bearer $AVINA_API_KEY"
import os
import requests
response = requests.get(
f"https://api.avina.io/v1/people/search/{search_id}/status",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}"},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search/${searchId}/status`, {
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);
{
"object": "people_search",
"id": "7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13",
"status": "completed",
"stop_reason": "target_reached",
"error": null,
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"interpretation": {
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": [
"Head of Revenue Operations",
"VP Revenue Operations",
"Director of Revenue Operations"
]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Financial Services"]
},
{
"field": "company.employee_count",
"operator": "between",
"value": [200, 1000]
}
]
},
"criteria": [],
"unsupported_criteria": []
},
"assumptions": [],
"progress": {
"candidates": 61,
"accepted": 25,
"rejected": 33,
"unknown": 3,
"not_returned": 0,
"contacts_found": 25
},
"credits_charged": 6.41,
"cancel_requested": false,
"created_at": "2026-11-12T17:10:02Z",
"completed_at": "2026-11-12T17:12:47Z",
"expires_at": null,
"status_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/status",
"results_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/results"
}
{
"error": {
"code": "invalid_api_key",
"message": "The API key is invalid or revoked.",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8"
}
}
Get a people search
Returns a people search’s status, progress and spend.
GET
/
v1
/
people
/
search
/
{search_id}
/
status
curl https://api.avina.io/v1/people/search/$SEARCH_ID/status \
-H "Authorization: Bearer $AVINA_API_KEY"
import os
import requests
response = requests.get(
f"https://api.avina.io/v1/people/search/{search_id}/status",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}"},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search/${searchId}/status`, {
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);
{
"object": "people_search",
"id": "7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13",
"status": "completed",
"stop_reason": "target_reached",
"error": null,
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"interpretation": {
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": [
"Head of Revenue Operations",
"VP Revenue Operations",
"Director of Revenue Operations"
]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Financial Services"]
},
{
"field": "company.employee_count",
"operator": "between",
"value": [200, 1000]
}
]
},
"criteria": [],
"unsupported_criteria": []
},
"assumptions": [],
"progress": {
"candidates": 61,
"accepted": 25,
"rejected": 33,
"unknown": 3,
"not_returned": 0,
"contacts_found": 25
},
"credits_charged": 6.41,
"cancel_requested": false,
"created_at": "2026-11-12T17:10:02Z",
"completed_at": "2026-11-12T17:12:47Z",
"expires_at": null,
"status_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/status",
"results_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/results"
}
{
"error": {
"code": "invalid_api_key",
"message": "The API key is invalid or revoked.",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8"
}
}
Reading it is free.
Poll this endpoint until
Every error uses the same shape. See Errors.
status is completed, failed or cancelled. Start at 2 seconds between polls and back off to 10. See Search lifecycle for what each status and stop_reason means.
Path parameters
string
required
The search’s
id, returned when it was started.Response
200 The search.
string
required
company_search or people_search.string
required
The search’s identifier. Use it to read status and results.
string
required
queued and running are in progress. completed, failed and cancelled are terminal. completed means this run finished, not that every matching record in the world was found.string | null
required
Why a finished search stopped.
null while it is in progress. Can also be null on a failed search; read error.Options: target_reached, sources_exhausted, usage_limit_reached, retrieval_limit_reached, query_needs_clarification, provider_failed, cancelled.string | null
required
A message when
status is failed. Results found before the failure stay readable.string | null
required
The natural-language request, when the search was started with
query.integer
required
The most results this search will return.
object | null
required
How a
query was read. null until the query has been interpreted, and for searches started with filters or criteria.Show properties
Show properties
object
Structured conditions. A record must meet every condition in
all. null is treated the same as leaving filters out. See the filter reference for every field and operator.Show properties
Show properties
object[]
required
The conditions. A record must meet every one. Each item is a field condition (
field, operator, value) or a related condition.Show item properties
Show item properties
string
The field to test, such as
company.industry or person.title.string
How to compare. Which operators a field accepts depends on its type.Options:
in, matches, eq, gt, gte, lt, lte, between, within_last_days.any
The value to compare against. A list for
in, a two-item list for between, a {amount, currency} object for money fields, a number of days for within_last_days.object
A condition on records related to the company. All conditions in
where must be true of the same record, for example one job listing.Show properties
Show properties
string
required
open_jobs: the company has at least one open job that matches. new_hires: someone with a matching title joined the company within the window.object
required
Conditions on the related record.
Show properties
Show properties
object[]
required
Conditions on
title (in), posted_at (within_last_days, for open_jobs) or started_at (within_last_days, for new_hires).object[]
Free-text requirements read from the query.
Show item properties
Show item properties
string[]
Requirements no public source can confirm, quoted from the query. A search cannot run while there are any.
object[]
required
object
required
Counts so far. They only increase.
Show properties
Show properties
integer
required
Candidates checked so far.
integer
required
Candidates that matched every requirement and were added to the results.
integer
required
Candidates that failed at least one requirement.
integer
required
Candidates whose evidence could not confirm every requirement. They are not returned.
integer
required
Candidates that matched every requirement but were not returned because
limit or a spend limit had already been reached.integer
required
Contacts found so far. For company searches with
persona_ids, and people searches with enrichment.number
required
Credits charged for this search so far. 1 credit = $1.00.
boolean
required
true after a cancel request, until the search reaches cancelled.string
required
When the search was started.
string | null
required
When the search reached a terminal status.
string | null
required
When the search and its results stop being readable.
null when no expiry is set.string
required
The URL of this search’s status.
string
required
The URL of this search’s results.
Errors
| Status | Code | When |
|---|---|---|
401 | invalid_api_key | The API key is missing, invalid or revoked. |
404 | not_found | No such object in this workspace. |
429 | rate_limited | Too many requests. Retry after Retry-After seconds. |
500 | internal_error | Something went wrong on our side. Retry with backoff, and with the same Idempotency-Key if you sent one. |
curl https://api.avina.io/v1/people/search/$SEARCH_ID/status \
-H "Authorization: Bearer $AVINA_API_KEY"
import os
import requests
response = requests.get(
f"https://api.avina.io/v1/people/search/{search_id}/status",
headers={"Authorization": f"Bearer {os.environ['AVINA_API_KEY']}"},
)
response.raise_for_status()
print(response.json())
const response = await fetch(`https://api.avina.io/v1/people/search/${searchId}/status`, {
headers: {
Authorization: `Bearer ${process.env.AVINA_API_KEY}`,
},
});
const data = await response.json();
console.log(data);
{
"object": "people_search",
"id": "7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13",
"status": "completed",
"stop_reason": "target_reached",
"error": null,
"query": "Heads of revenue operations at US fintech companies with 200 to 1,000 employees",
"limit": 25,
"interpretation": {
"filters": {
"all": [
{
"field": "person.title",
"operator": "in",
"value": [
"Head of Revenue Operations",
"VP Revenue Operations",
"Director of Revenue Operations"
]
},
{
"field": "company.headquarters.country",
"operator": "in",
"value": ["US"]
},
{
"field": "company.industry",
"operator": "in",
"value": ["Financial Services"]
},
{
"field": "company.employee_count",
"operator": "between",
"value": [200, 1000]
}
]
},
"criteria": [],
"unsupported_criteria": []
},
"assumptions": [],
"progress": {
"candidates": 61,
"accepted": 25,
"rejected": 33,
"unknown": 3,
"not_returned": 0,
"contacts_found": 25
},
"credits_charged": 6.41,
"cancel_requested": false,
"created_at": "2026-11-12T17:10:02Z",
"completed_at": "2026-11-12T17:12:47Z",
"expires_at": null,
"status_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/status",
"results_url": "https://api.avina.io/v1/people/search/7c1d9a52-3e0b-4f6a-9d21-5b8e4a7c0f13/results"
}
{
"error": {
"code": "invalid_api_key",
"message": "The API key is invalid or revoked.",
"request_id": "req_8f2a61c09d4e7b3a5f10c2d8"
}
}