Verona API

Verona is the API for deep people search. Send Verona a natural language description of who you're looking for and receive qualified, enriched profiles. New accounts get one free search. Get in touch with any questions.

Base URL

https://api.veronaresearch.com/v1

Create an API key

Verona is hosted; clients need only a product API key and an HTTP client. Keep the key server-side and send it as a Bearer token with every request.

Create API key

Terminal

export VERONA_API_KEY="vps_live_your_api_key"

Send a search request

Send the user's real query and target count. Save the returned search_id, request body, and stable idempotency key.

Create a search

export IDEMPOTENCY_KEY="replace-with-a-unique-stable-value"curl --request POST "https://api.veronaresearch.com/v1/searches" \  --header "Authorization: Bearer $VERONA_API_KEY" \  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \  --header "Content-Type: application/json" \  --data '{"query":"VP-level growth leaders at AI infrastructure startups","target_count":500}'

Poll for completion

Poll no faster than poll_after_seconds until completed or failed.

Check status

export SEARCH_ID="search_01JZ2S8YQK7M6B4F9W3H1T5N0P"curl "https://api.veronaresearch.com/v1/searches/$SEARCH_ID" \  --header "Authorization: Bearer $VERONA_API_KEY"

Receive qualified profiles

Fetch results. If has_more is true, continue with next_cursor.

Read results

curl "https://api.veronaresearch.com/v1/searches/$SEARCH_ID/results?limit=100" \  --header "Authorization: Bearer $VERONA_API_KEY"

Create, poll, collect

Poll while a search runs. Profile records become available only after the final result set is stable.

01
queued
Waiting to start.
02
running
In progress. Profile records are withheld.
03
completed or failed
The stable final result set is available. Fetch it for either outcome before handling a failure.

POST/searches

Retry safely

Idempotency-Key is optional for the one free trial search and required for every paid search. Send it for both. Reuse a value only when retrying the same request body after an uncertain create outcome.

Request body

{  "query": "VP-level growth leaders at AI infrastructure startups",  "target_count": 500}

202 response

{  "search_id": "search_01JZ2S8YQK7M6B4F9W3H1T5N0P",  "status": "queued",  "query": "VP-level growth leaders at AI infrastructure startups",  "target_count": 500,  "qualified_count": 0,  "created_at": "2026-07-12T14:10:00Z",  "poll_after_seconds": 15,  "links": {    "status": "https://api.veronaresearch.com/v1/searches/search_01JZ2S8YQK7M6B4F9W3H1T5N0P",    "results": "https://api.veronaresearch.com/v1/searches/search_01JZ2S8YQK7M6B4F9W3H1T5N0P/results"  }}

GET/searches/{search_id}

Read progress

Use qualified_count for progress and poll_after_seconds for pacing.

Running response

{  "search_id": "search_01JZ2S8YQK7M6B4F9W3H1T5N0P",  "status": "running",  "query": "VP-level growth leaders at AI infrastructure startups",  "target_count": 500,  "qualified_count": 42,  "created_at": "2026-07-12T14:10:00Z",  "poll_after_seconds": 15,  "links": {    "status": "https://api.veronaresearch.com/v1/searches/search_01JZ2S8YQK7M6B4F9W3H1T5N0P",    "results": "https://api.veronaresearch.com/v1/searches/search_01JZ2S8YQK7M6B4F9W3H1T5N0P/results"  },  "current_round": 2,  "total_subagents": 8,  "successful_subagents": 6,  "goal_met": null,  "stop_reason": null,  "started_at": "2026-07-12T14:10:03Z",  "completed_at": null,  "error": null}

queuedrunningcompletedfailed

GET/searches/{search_id}/results

Results and pagination

Queued and running searches return no profiles. Completed and failed searches return a stable, ordered result set with terminal metadata; each profile is billable and includes name, title, company, location, linkedin_url, rationale, work_history, and education.

Result preview

{  "search_id": "search_01JZ2S8YQK7M6B4F9W3H1T5N0P",  "status": "completed",  "is_complete": true,  "returned_count": 1,  "has_more": true,  "next_cursor": "eyJpIjoxLCJtIjoiZmluYWwiLCJuIjoxLCJyIjoxLCJ2IjoyfQ",  "items": [    {      "name": "Maya Chen",      "title": "VP of Growth",      "company": "NeuralScale",      "location": "San Francisco, California, United States",      "linkedin_url": "https://www.linkedin.com/in/maya-chen",      "rationale": "Leads growth at an AI infrastructure startup and meets the requested seniority.",      "work_history": [        {          "title": "VP of Growth",          "company": "NeuralScale",          "company_domain": "neuralscale.example",          "start_date": "2023-04-01",          "end_date": null,          "is_current": true,          "location": "San Francisco, California",          "description": "Leads growth across product, lifecycle, and developer acquisition."        },        {          "title": "Director of Growth",          "company": "CloudForge",          "company_domain": "cloudforge.example",          "start_date": "2020-06-01",          "end_date": "2023-03-01",          "is_current": false,          "location": "San Francisco, California",          "description": "Built the developer acquisition engine from seed through Series B."        }      ],      "education": [        {          "school": "Stanford University",          "degree": "MBA",          "field_of_study": null,          "start_date": "2018-09-01",          "end_date": "2020-06-01"        }      ]    }  ]}

Pagination

limit accepts 1 to 200 and defaults to 100. Pass next_cursor unchanged while has_more is true. returned_count is the size of the current page, not a total.

curl "https://api.veronaresearch.com/v1/searches/$SEARCH_ID/results?limit=200&cursor=$NEXT_CURSOR" \  --header "Authorization: Bearer $VERONA_API_KEY"

Endpoints and errors

POST

/searchesCreate a search

Create a search and receive search_id.

GET

/searches/{search_id}Check status

Read status and poll_after_seconds.

GET

/searches/{search_id}/resultsRead results

Read paginated results.

Error responses

Errors include code, message, and request_id.

401Missing, invalid, or revoked API key.
402The account has insufficient available prepaid credits for the search.
403The target exceeds the free-trial or account entitlement.
404The search does not exist or belongs to a different API-key account.
409An idempotency key was reused with a different request body.
422The body, paid-search idempotency key, or pagination cursor is invalid.
429The account has reached its active-search entitlement; honor Retry-After.

Error response

{  "error": {    "code": "unauthorized",    "message": "A valid Verona product API key is required",    "request_id": "req_01JZ2S8YQK7M6B4F9W3H1T5N0P",    "details": null  }}

OpenAPI contract

The contract defines all paths, fields, and validation.

OpenAPI JSON

curl --fail \  --header "Authorization: Bearer $VERONA_API_KEY" \  https://api.veronaresearch.com/v1/openapi.json