​
GET /jobs/<job_id>/search

Find candidates matching a stored job description using AI-powered vector search. This endpoint uses advanced semantic search to find developer profiles that best match your job requirements, ranked by relevance using machine learning models.

​
🔑 Credits

  • Cost: 1 credit per candidate returned (e.g., 50 candidates = 50 credits)
  • Credit Pool: Uses search-specific credits if configured, otherwise falls back to general credits
  • Pre-check: Credits are verified before processing the request
  • Separate Limit: Search operations can have their own credit limit independent of other endpoints

​
Authentication

API key can be provided in two ways:
  • Header: x-api-key: YOUR_API_KEY
  • Query parameter: api_key=YOUR_API_KEY

​
URL Parameters

NameTypeRequiredDescription
job_idstring✅ YesThe job ID from /jobs/create

​
Query Parameters

NameTypeRequiredDescription
api_keystring✅ YesAPI key for authentication (can also be in x-api-key header)
sizeinteger❌ NoNumber of candidates to return. Default: 100, Range: 1-1000
summary_lengthinteger❌ NoLength of generated summary. Default: 1024, Range: 30-8192
countriesarray❌ NoFilter by country codes (e.g., ['US', 'CA', 'UK'])
segmentsarray❌ NoFilter by data segments (integers 0-9999)
required_fieldsarray❌ NoOnly return profiles containing these fields

​
Response Headers

HeaderDescription
X-Credits-UsedTotal credits used by your API key across all endpoints
X-Credits-Used-UserCredits used specifically for /user endpoint
X-Credits-Used-SearchCredits used specifically for /jobs/search endpoint
X-Credits-Used-AssessCredits used specifically for /jobs/assess endpoint
X-Credits-RemainingRemaining general credits (-1 for unlimited accounts)
X-Credits-Remaining-SearchRemaining search-specific credits (if configured)
X-Credits-Remaining-AssessRemaining assess-specific credits (if configured)
X-Calls-UserTotal number of calls made to /user endpoint
X-Calls-SearchTotal number of calls made to /jobs/search endpoint
X-Calls-AssessTotal number of calls made to /jobs/assess endpoint

​
Response

Returns an array of matching developer profiles ranked by relevance. 
{
  "results": [
    {
      "github_username": "torvalds",
      "email": "torvalds@linux-foundation.org",
      "full_name": "Linus Torvalds",
      "bio": "Creator of Linux and Git",
      "location": "Portland, OR",
      "company": "Linux Foundation",
      "followers": 150000,
      "public_repos": 50,
      "skills": [
        {"skill": "C", "score": 95},
        {"skill": "Linux", "score": 100},
        {"skill": "Git", "score": 98}
      ],
      "summary_text": "Legendary software developer and creator of the Linux operating system...",
      "repos": [
        {
          "full_name": "torvalds/linux",
          "description": "Linux kernel source tree",
          "language": "C",
          "stargazers_count": 150000,
          "updated_at": "2025-08-06"
        }
      ]
    }
  ]
}

​
Examples

Using cURL 
curl -X GET "https://api.b2d.ai/jobs/550e8400-e29b-41d4-a716-446655440000/search?size=10&countries=US,CA" \
  -H "x-api-key: YOUR_API_KEY"
Using Python 
import requests

job_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {"x-api-key": "YOUR_API_KEY"}
params = {
    "size": 25,
    "countries": ["United States", "Canada"],
    "summary_length": 2048,
    "required_fields": ["email", "full_name"]
}

response = requests.get(f"https://api.b2d.ai/jobs/{job_id}/search", 
                       headers=headers, params=params)

if response.status_code == 200:
    data = response.json()
    candidates = data['results']
    
    print(f"Found {len(candidates)} matching candidates:")
    for candidate in candidates[:5]:  # Show first 5
        print(f"- {candidate.get('full_name', 'N/A')} (@{candidate['github_username']})")
        print(f"  Location: {candidate.get('location', 'N/A')}")
        print(f"  Followers: {candidate.get('followers', 0)}")
        print()
    
    # Check usage and costs
    credits_used = int(response.headers.get('X-Credits-Used', 0))
    credits_remaining = response.headers.get('X-Credits-Remaining')
    print(f"Credits used for search: {len(candidates)}")
    print(f"Total credits used: {credits_used}")
    print(f"Credits remaining: {credits_remaining}")
else:
    print(f"Error: {response.status_code} - {response.json()}")
Using Python with POST (for complex parameters) 
import requests

job_id = "550e8400-e29b-41d4-a716-446655440000"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "size": 50,
    "countries": ["United States", "Canada", "United Kingdom"],
    "segments": [100, 101, 102],  # Specific data segments
    "required_fields": ["email", "linkedin_username"],
    "summary_length": 1024
}

response = requests.post(f"https://api.b2d.ai/jobs/{job_id}/search", 
                        headers=headers, json=data)
Raw HTTP Request 
GET https://api.b2d.ai/jobs/550e8400-e29b-41d4-a716-446655440000/search?size=10&countries=US,CA&api_key=YOUR_API_KEY

​
Advanced Filtering

Country Filtering 
# Accepted country formats
params = {
    "countries": ["US", "CA", "UK"]           # ISO codes
    # or
    "countries": ["United States", "Canada"]   # Full names
}
Segment Filtering 
# Filter by data segments (0-9999)
params = {
    "segments": [100, 101, 102]  # Specific segments
}
Required Fields 
# Only return profiles with these fields
params = {
    "required_fields": ["email", "linkedin_username", "full_name"]
}

​
Error Responses

Status CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Missing API key
403Forbidden - Invalid API key or access denied
404Not Found - Job ID not found
500Internal Server Error
Example Error Responses: 
{
  "error": "Job not found"
}

{
  "error": "size must be between 1 and 1000"
}

​
AI-Powered Matching

The search uses advanced semantic similarity to match candidates:
  • Vector Embeddings: Job descriptions and developer profiles are converted to high-dimensional vectors
  • Semantic Search: Matches based on meaning, not just keywords
  • ML Ranking: Results ranked by relevance using machine learning models
  • Technology Detection: Identifies relevant technologies and skills automatically
  • Experience Weighting: Considers experience level and project complexity

​
Performance Notes

  • Response Time: Typically 1-3 seconds depending on search complexity
  • Relevance Scoring: Results are pre-ranked by AI similarity
  • Caching: Frequent searches are cached for improved performance
  • Pagination: Use size parameter to control result count vs. performance
  • Filtering: Country/segment filters applied before expensive AI operations

​
Next Steps

After finding candidates, use their github_username with:
  • Job Assessment - Get detailed AI assessment for specific candidates
  • User Lookup - Get complete profile data for interesting candidates