| name | nyne-search |
| description | Search for people using natural language queries with the Nyne Search API. Find professionals by role, company, location, industry, or any combination. Supports custom filters, AI relevance scoring, contact enrichment (emails + phones), pagination, and three search tiers (light, medium, premium). Async with polling.
|
Nyne Search Skill
Search for people using natural language queries. Find professionals by role, company, location, industry, or any combination. Returns matching profiles with contact info, work history, education, and optional AI relevance scoring.
Important: This API is async. You POST to submit, get a request_id, then poll GET until status: "completed". Light searches complete in 3-40 seconds; premium searches take 30-300 seconds.
Agent Instructions
When presenting search results to the user, show all returned data for each person. Walk through:
- Result count — total_stored, total_estimate, has_more, credits_charged
- Each person — displayname, headline, bio, location, gender, estimated_age, total_experience_years, is_decision_maker
- Contact info — best_business_email, best_personal_email, altemails, fullphone (if show_emails/show_phone_numbers were enabled)
- Social profiles — LinkedIn URL, username, connections, followers
- Work history — all organizations with title, dates, company details (industries, num_employees, funding, technologies)
- Education — schools with degree, major, dates; note is_top_universities flag
- Interests — work interests and certifications
- Patents — title, date, reference, URL (if present)
- Languages — spoken languages
- Score — AI relevance score 0-1 (if profile_scoring was enabled)
- Insights — AI-generated match reasoning (if insights were enabled)
If has_more is true, tell the user there are more results available and offer to paginate using the next_cursor.
If a field is missing from the response, it means no data was found — skip it silently.
Setup
Required environment variables:
NYNE_API_KEY — your Nyne API keyNYNE_API_SECRET — your Nyne API secret
Get credentials at https://api.nyne.ai.
export NYNE_API_KEY="your-api-key"
export NYNE_API_SECRET="your-api-secret"
Verify they're set:
echo "Key: ${NYNE_API_KEY:0:8}... Secret: ${NYNE_API_SECRET:0:6}..."
Important: JSON Handling
The API response can contain control characters in JSON string values that break jq. All examples use a nyne_parse helper that cleans and re-encodes JSON via python3. Define it once per session:
nyne_parse() {
python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}
Quick Start
Search for people by natural language query and poll until complete:
nyne_parse() {
python3 -c "
import sys, json, re
raw = sys.stdin.read()
clean = re.sub(r'[\x00-\x1f]+', ' ', raw)
data = json.loads(clean)
json.dump(data, sys.stdout)
"
}
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"query": "Software engineers at Google in San Francisco", "limit": 10, "type": "premium", "show_emails": true}' | nyne_parse > /tmp/nyne_search.json
STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)
if [ "$STATUS" = "completed" ]; then
echo "Search completed immediately."
jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
else
REQUEST_ID=$(jq -r '.data.request_id' /tmp/nyne_search.json)
echo "Request submitted: $REQUEST_ID (status: $STATUS)"
SECONDS_WAITED=0
while [ $SECONDS_WAITED -lt 600 ]; do
curl -s "https://api.nyne.ai/person/search?request_id=$REQUEST_ID" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_search.json
STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)
echo
[ = ];
jq /tmp/nyne_search.json
jq /tmp/nyne_search.json
[ = ];
jq . /tmp/nyne_search.json
5
SECONDS_WAITED=$((SECONDS_WAITED + ))
[ -ge 600 ];
Submit Search (POST)
Endpoint: POST https://api.nyne.ai/person/search
Headers:
Content-Type: application/json
X-API-Key: $NYNE_API_KEY
X-API-Secret: $NYNE_API_SECRET
Query Parameters
| Parameter | Type | Default | Description |
|---|
query | string | required | Natural language search query (max 1000 chars). Examples: "Software engineers at Microsoft in Seattle", "Marketing directors at Fortune 500" |
type | string | "premium" | Search quality tier: "light" (fast, 3-40s), "medium" (balanced), "premium" (best quality, 30-300s) |
limit | integer | 10 | Results per request (max 100) |
offset | integer | 0 | Starting position, 0-indexed (max 999). offset + limit must be ≤ 1000 |
show_emails | boolean | false | Include email addresses in results (+2 credits). Significantly increases latency — search will take longer to complete as emails are enriched per result |
show_phone_numbers | boolean | false | Include phone numbers in results (+14 credits). Significantly increases latency — search will take longer to complete as phone numbers are enriched per result |
require_emails | boolean | false | Only return profiles that have email addresses (+1 credit) |
require_phone_numbers | boolean | false | Only return profiles that have phone numbers (+1 credit) |
require_phones_or_emails | boolean | false | Only return profiles with either phone or email (+1 credit) |
insights | boolean | false | AI-generated insights per result explaining match relevance (+1 credit per result). Not available for light type |
profile_scoring | boolean | false | Include AI relevance score (0-1) per result (+1 credit) |
high_freshness | boolean |
Custom Filters
Pass as a custom_filters object to narrow results beyond the natural language query.
Array fields (pass as arrays of strings):
| Filter | Description |
|---|
locations | Geographic locations (e.g., ["San Francisco", "New York"]) |
languages | Languages spoken (e.g., ["English", "Spanish"]) |
titles | Job titles (e.g., ["CTO", "VP Engineering"]) |
industries | Industry sectors (e.g., ["Technology", "Healthcare"]) |
companies | Company names, current or past (e.g., ["Google", "Meta"]) |
universities | Universities attended (e.g., ["Stanford", "MIT"]) |
keywords | Profile keywords (e.g., ["machine learning", "AI"]) |
degrees | Education degrees (e.g., ["bachelor", "master", "phd"]) |
specialization_categories | Academic specialization categories |
Numeric range fields (pass as integers):
| Filter | Description |
|---|
min_linkedin_followers / max_linkedin_followers | LinkedIn follower count range |
min_total_experience_years / max_total_experience_years | Total work experience range |
min_current_experience_years / max_current_experience_years | Current role tenure range |
min_estimated_age / max_estimated_age | Estimated age range |
Exact match fields:
| Filter | Type | Description |
|---|
first_name | string | Exact first name match |
middle_name | string | Exact middle name match |
last_name | string | Exact last name match |
gender | string | "male" or "female" |
studied_at_top_universities | boolean | Attended a top-ranked university |
Examples
Basic search:
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"query": "Software engineers at Google in San Francisco", "limit": 10}' | nyne_parse > /tmp/nyne_search.json
jq '{status: .data.status, request_id: .data.request_id}' /tmp/nyne_search.json
With emails and phone numbers:
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"query": "Marketing directors at tech startups in Austin", "limit": 25, "show_emails": true, "show_phone_numbers": true}' | nyne_parse > /tmp/nyne_search.json
With custom filters:
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{
"query": "Engineering leaders in fintech",
"limit": 20,
"type": "premium",
"show_emails": true,
"custom_filters": {
"locations": ["New York", "San Francisco"],
"titles": ["CTO", "VP Engineering", "Head of Engineering"],
"min_total_experience_years": 10,
"industries": ["Financial Services", "Technology"]
}
}' | nyne_parse > /tmp/nyne_search.json
Light search (fast, 1 credit):
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"query": "Data scientists at Amazon", "type": "light", "limit": 10}' | nyne_parse > /tmp/nyne_search.json
With AI scoring and insights:
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"query": "AI researchers in healthcare", "type": "premium", "profile_scoring": true, "insights": true, "limit": 10}' | nyne_parse > /tmp/nyne_search.json
With freshness priority:
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"query": "Product managers who recently changed jobs", "type": "premium", "high_freshness": true, "show_emails": true}' | nyne_parse > /tmp/nyne_search.json
Require contact info:
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"query": "Sales directors at SaaS companies", "require_emails": true, "show_emails": true, "limit": 50}' | nyne_parse > /tmp/nyne_search.json
Submit response:
{
"success": true,
"data": {
"request_id": "abc12345_1737123456_1234",
"status": "completed",
"results": [...],
"offset": 0,
"limit": 10,
"total_stored": 47,
"total_estimate": 2500,
"has_more": true,
"next_cursor": "eyJvIjoxMCwiciI6ImFiYzEyMzQ1XzE3MzcxMjM0NTZfMTIzNCJ9",
"from_cache": false,
"credits_charged": 7
},
"timestamp"
Note: The POST may return status: "completed" immediately (especially for cached or light searches) or status: "processing" requiring polling. Always check the status.
Poll for Results (GET)
Endpoint: GET https://api.nyne.ai/person/search?request_id={id}
Headers: Same X-API-Key and X-API-Secret as above.
Check status once
curl -s "https://api.nyne.ai/person/search?request_id=$REQUEST_ID" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_search.json
jq '{status: .data.status, total_stored: .data.total_stored}' /tmp/nyne_search.json
Full polling loop
SECONDS_WAITED=0
TIMEOUT=600
while [ $SECONDS_WAITED -lt $TIMEOUT ]; do
curl -s "https://api.nyne.ai/person/search?request_id=$REQUEST_ID" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" | nyne_parse > /tmp/nyne_search.json
STATUS=$(jq -r '.data.status' /tmp/nyne_search.json)
echo "[$(date +%H:%M:%S)] Status: $STATUS ($SECONDS_WAITED s)"
case "$STATUS" in
completed)
jq '.data | {total_stored, total_estimate, has_more, credits_charged}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
break
;;
failed)
echo "Search failed:"
jq '.data' /tmp/nyne_search.json
break
;;
*)
sleep 5
SECONDS_WAITED=$((SECONDS_WAITED + 5))
;;
esac
done
if [ "$STATUS" != "completed" ] && [ "$STATUS" != "failed" ]; then
echo "Timed out. Resume polling with request_id: $REQUEST_ID"
fi
Pagination
After the initial search completes, paginate through results for free (cached results, no additional credits).
Cursor-based pagination (recommended)
Use the next_cursor from the previous response:
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"cursor": "eyJvIjoxMCwiciI6ImFiYzEyMzQ1XzE3MzcxMjM0NTZfMTIzNCJ9"}' | nyne_parse > /tmp/nyne_search.json
jq '.data | {total_stored, offset, limit, has_more}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
Offset-based pagination
Use request_id + offset from the original search:
curl -s -X POST "https://api.nyne.ai/person/search" \
-H "Content-Type: application/json" \
-H "X-API-Key: $NYNE_API_KEY" \
-H "X-API-Secret: $NYNE_API_SECRET" \
-d '{"request_id": "abc12345_1737123456_1234", "offset": 25, "limit": 25}' | nyne_parse > /tmp/nyne_search.json
jq '.data | {total_stored, offset, limit, has_more}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
Pagination notes:
- Paginating through cached results is free — no additional credits charged
- Maximum 1000 results per search (
offset + limit ≤ 1000)
has_more indicates whether more results are availablenext_cursor is only present when has_more is true- Results are cached for 30 days
Response Structure
When status is completed:
{
"success": true,
"timestamp": "2026-02-19T...",
"data": {
"request_id": "abc12345_1737123456_1234",
"status": "completed",
"results": [
{
"displayname": "Jane Smith",
"headline": "Senior Software Engineer at Google",
"bio": "...",
"location": "San Francisco, CA",
"gender": "female",
"estimated_age": 35,
"total_experience_years": 12,
"is_decision_maker": 1,
Result Fields
| Field | Type | Description |
|---|
displayname | string | Person's full name |
headline | string | Current job title/headline |
bio | string | Professional biography |
location | string | Geographic location |
gender | string | "male" or "female" |
estimated_age | integer | Estimated age |
total_experience_years | integer | Years of total work experience |
is_decision_maker | integer | Whether person holds decision-making authority (1 = yes) |
is_top_universities | boolean | Whether person attended a top-ranked university |
languages | array | Languages spoken (array of strings) |
interests | object | {work: [...], certification: [...]} — work interests and certifications |
patents | array | Patents held: {title, description, date, reference, url} |
best_business_email | string | Primary business email (requires show_emails: true) |
best_personal_email | string | Primary personal email (requires show_emails: true) |
altemails | array | Alternative email addresses (requires show_emails: true) |
fullphone | array | Phone numbers with type (requires show_phone_numbers: true). Each: {fullphone, type} |
social_profiles |
Social Profiles Object
{
"linkedin": {
"url": "https://www.linkedin.com/in/...",
"username": "...",
"connections": 1243,
"followers": 542,
"photo_url": "..."
}
}
Organization Object
{
"name": "Windfall Bio",
"title": "Vice President of Software Engineering",
"startDate": "2024-08-01",
"endDate": null,
"location": "San Mateo, California, United States",
"company_website": "http://www.windfall.bio",
"company_linkedin_url": "https://www.linkedin.com/company/windfallbio",
"company_domain": "windfall.bio",
"industries": ["Manufacturing"],
"num_employees": 37,
"num_employees_range": "11-50",
"is_startup": true,
"is_b2b":
Organizations include rich company intelligence: funding data, tech stack, employee counts, and B2B/B2C/SaaS flags. Not all fields are present for every organization.
Response Metadata Fields
| Field | Type | Description |
|---|
total_stored | integer | Number of results stored from this search |
total_estimate | integer | Estimated total matching profiles |
has_more | boolean | Whether more results are available for pagination |
next_cursor | string | Opaque pagination token for next page (present when has_more is true) |
from_cache | boolean | Whether results came from cache (30-day TTL) |
credits_charged | integer | Total credits charged for this request |
offset | integer | Current offset in result set |
limit | integer | Results per page |
Useful jq Filters
After polling completes, the clean response is at /tmp/nyne_search.json:
jq '.data | {total_stored, total_estimate, has_more, credits_charged, from_cache}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, headline, location}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, best_business_email, best_personal_email, altemails}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, fullphone}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, linkedin: .social_profiles.linkedin.url}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, orgs: [.organizations[] | {name, title}]}' /tmp/nyne_search.json
jq '[.data.results[] | select(.is_decision_maker == true)] | length' /tmp/nyne_search.json
jq '[.data.results[] | select(.is_decision_maker == true) | {displayname, headline}]' /tmp/nyne_search.json
jq '[.data.results | sort_by(-.score)[] | {displayname, headline, score}]' /tmp/nyne_search.json
jq '.data.results[] | {displayname, total_experience_years} | select(.total_experience_years >= 10)' /tmp/nyne_search.json
jq '.data.results[] | {displayname, schools: .schools_attended}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, work_interests: .interests.work, certifications: .interests.certification}' /tmp/nyne_search.json
jq '.data.results[] | select(.patents | length > 0) | {displayname, patents: [.patents[] | {title, date}]}' /tmp/nyne_search.json
jq '.data.results[] | {displayname, companies: [.organizations[] | {name, funding_total_usd, latest_funding_round, num_employees, is_startup}]}' /tmp/nyne_search.json
jq -r /tmp/nyne_search.json
jq /tmp/nyne_search.json
Error Handling
| HTTP Code | Error | Description |
|---|
| 400 | invalid_parameters | Invalid parameter value or missing query |
| 400 | invalid_custom_filters | Malformed custom_filters object |
| 401 | invalid_credentials | Invalid API key/secret |
| 404 | request_not_found | Invalid request_id for status check (GET only) |
| 429 | rate_limit_exceeded | Too many requests |
| 429 | insufficient_credits | Not enough credits for this search |
| 500 | internal_error | Server error |
Search Tiers & When to Use Each
Fast Search — type: "light" (1 credit per result)
Basic search with fast results in 3-40 seconds. Best for quick lookups when you need a broad list of names and don't need deep profile data. AI features (insights, high_freshness) are NOT available for light type. Profile scoring is available.
{"query": "Software engineers at Google", "type": "light", "limit": 50}
Smart Search — type: "medium"
Balanced tier between speed and quality. Use when you want better matching than light but don't need the full depth of premium. Supports all AI features.
{"query": "Engineering managers in fintech", "type": "medium", "limit": 25}
Pro Search — type: "premium" (5 credits per result)
Comprehensive search taking 30-300 seconds. Best quality results with deepest profile matching. Required for maximum-quality insights and high_freshness results. Use when result quality matters more than speed.
{"query": "AI researchers at top universities", "type": "premium", "limit": 10, "insights": true, "profile_scoring": true}
AI-Powered Analysis Features
These features add intelligence on top of search results. Insights and High Freshness are NOT available for light type searches — use medium or premium.
Query Insights (insights: true, +1 credit per result)
AI-generated analysis for each result explaining why this person matches your search query. Returns structured reasoning about the match relevance — how their background, role, and experience align with what you're looking for. Invaluable for qualifying leads or evaluating candidates at scale. Use when you need to understand the "why" behind each match, not just the "who".
{"query": "AI researchers in healthcare", "type": "premium", "insights": true, "limit": 10}
Profile Scoring (profile_scoring: true, +1 credit)
AI relevance scoring that assigns each result a score from 0 to 1, where 1.0 is a perfect match. Use to rank and prioritize results by relevance. Works with all search tiers including light. Combine with insights for both a score and an explanation.
{"query": "Senior engineers at fintech startups", "profile_scoring": true, "limit": 25}
High Freshness (high_freshness: true, +2 credits)
Prioritizes profiles that have been recently updated — people who recently changed jobs, updated their LinkedIn, or have fresh activity. Use when recency matters: hiring recently active candidates, targeting people who just moved to a new role, or finding profiles with current contact info. Not available for light type.
{"query": "Product managers who recently changed jobs", "type": "premium", "high_freshness": true, "show_emails": true}
Combining AI Features
Stack insights + scoring + freshness for maximum intelligence:
{
"query": "VP of Engineering at Series B startups in San Francisco",
"type": "premium",
"insights": true,
"profile_scoring": true,
"high_freshness": true,
"show_emails": true,
"limit": 10
}
Credit Costs
Credits are charged based on features used per request. Pagination within cached results is free.
| Feature | Credits | Description |
|---|
Fast Search (type: "light") | 1 | Basic search, fastest response (3-40 seconds) |
Pro Search (type: "premium") | 5 | Comprehensive search, best quality (30-300 seconds) |
Smart Ranking (profile_scoring, boolean) | 1 | AI-powered relevance scoring of results |
Candidate Insights (insights, boolean) | 1 | AI-generated insights about each result |
Realtime Profiles (high_freshness, boolean) | 2 | Prioritize recently updated profiles |
| Filter Without Contact Data | 1 | Search without email/phone enrichment |
Enrich Phones (show_phone_numbers, boolean) | 14 | Include phone numbers in results. Significantly increases latency |
Enrich Emails (show_emails, boolean) | 2 | Include email addresses in results. Significantly increases latency |
Require Emails (require_emails, boolean) | 1 | Only return profiles with email addresses |
Require Phones (require_phone_numbers, boolean) | 1 | Only return profiles with phone numbers |
Require Contact Info (require_phones_or_emails, boolean) | 1 | Only return profiles with phone OR email |
| Pagination (cached) | 0 | Free after initial search (30-day cache) |
Rate Limits
- Per minute: 60 requests
- Per hour: 1,000 requests
- Monthly: Plan-dependent
