Verona API

Base URL
https://api.veronaresearch.com/v1

Create an API key

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"
01

Send a search request

Send a query and target count. Save the returned search_id.

Create a search
curl --request POST "https://api.veronaresearch.com/v1/searches" \  --header "Authorization: Bearer $VERONA_API_KEY" \  --header "Content-Type: application/json" \  --data '{"query":"VP-level growth leaders at AI infrastructure startups","target_count":250}'
02

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"
03

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

Results are available while a search is running and remain stable after completion.

  1. 01
    queued

    Waiting to start.

  2. 02
    running

    In progress. Partial results are available.

  3. 03
    completed or failed

    The search reached a terminal state.

POST/searches

Prevent duplicate searches

Send Idempotency-Key when a create request may be retried.

Request body
{  "query": "VP-level growth leaders at AI infrastructure startups",  "target_count": 250}
202 response
{  "search_id": "search_01JZ2S8YQK7M6B4F9W3H1T5N0P",  "status": "queued",  "query": "VP-level growth leaders at AI infrastructure startups",  "target_count": 250,  "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": 250,  "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

Each result includes name, title, company, location, linkedin_url, rationale, work_history, and education. Ordering can change while running and is stable after completion.

Result preview
{  "search_id": "search_01JZ2S8YQK7M6B4F9W3H1T5N0P",  "status": "running",  "is_complete": false,  "returned_count": 1,  "has_more": true,  "next_cursor": "eyJzY29yZSI6OTYsImlkIjoxfQ",  "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"        }      ]    }  ]}

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.
  • 403The API key cannot access the requested environment or resource.
  • 404The search does not exist for the authenticated account.
  • 409An idempotency key was reused with a different request body.
  • 422The request or pagination cursor is invalid.
  • 429The account has reached its active-search entitlement.
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