Skip to main content
GET
/
api
/
search
Search People
curl --request GET \
  --url https://search.clado.ai/api/search \
  --header 'Authorization: Bearer <token>'
{
  "results": [
    {
      "profile": {
        "id": "3917303",
        "name": "Alex Johnson",
        "location": "San Francisco, California, United States",
        "location_country": "United States",
        "location_regions": [
          "Americas",
          "Northern America",
          "AMER"
        ],
        "headline": "Senior Software Engineer at TechCorp Inc",
        "description": "Experienced software engineer specializing in machine learning and distributed systems",
        "linkedin_url": "https://www.linkedin.com/in/alexjohnson",
        "picture_permalink": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
        "connections_count": 500,
        "followers_count": 1200,
        "is_working": true,
        "is_decision_maker": false,
        "total_experience_duration_months": 48,
        "projected_total_salary": 150000,
        "post_count": 15,
        "posts": "Excited to share our latest ML research on distributed training optimization",
        "liked_posts": "Great insights on PyTorch optimization techniques",
        "recommendations": "Alex is an exceptional engineer with deep ML expertise",
        "recommendations_count": 8,
        "skills": [
          "Python",
          "Machine Learning",
          "Software Engineering",
          "Data Science"
        ]
      },
      "experience": [
        {
          "title": "Senior Software Engineer",
          "company_name": "TechCorp Inc",
          "start_date": "2021-01-01T00:00:00",
          "end_date": "1970-01-01T00:00:00",
          "description": "Working on machine learning infrastructure and scalable systems",
          "location": "San Francisco, CA"
        }
      ],
      "education": [
        {
          "degree": "Master of Science",
          "field_of_study": "Computer Science",
          "school_name": "State University",
          "start_date": "2017-09-01T00:00:00",
          "end_date": "2019-06-01T00:00:00"
        }
      ],
      "posts": [
        {
          "text": "Excited to share our latest ML research on distributed training optimization",
          "totalReactionCount": 45,
          "likeCount": 38,
          "appreciationCount": 2,
          "empathyCount": 1,
          "InterestCount": 1,
          "praiseCount": 3,
          "commentsCount": 8,
          "repostsCount": 2,
          "postUrl": "https://www.linkedin.com/feed/update/urn:li:activity:7276799769082007552/",
          "postedAt": "2w",
          "postedDate": "2024-01-15 10:30:00.000 +0000 UTC",
          "postedDateTimestamp": 1705315800000,
          "reposted": false,
          "urn": "7276799769082007552",
          "author": {
            "firstName": "Alex",
            "lastName": "Johnson",
            "username": "alexjohnson",
            "url": "https://www.linkedin.com/in/alexjohnson"
          },
          "image": [],
          "mentions": [],
          "companyMentions": [
            {
              "id": 12345,
              "name": "TechCorp Inc",
              "publicIdentifier": "techcorp-inc",
              "url": "https://www.linkedin.com/company/techcorp-inc/"
            }
          ],
          "isBrandPartnership": false
        }
      ]
    }
  ],
  "total": 1,
  "query": "software engineers at tech companies",
  "search_id": "550e8400-e29b-41d4-a716-446655440000"
}
Search through millions of LinkedIn profiles using natural language queries. This endpoint provides fast searching with AI-powered relevance matching, pagination support for large result sets, and optional agent-based filtering for higher quality results.
🚨 DEPRECATION NOTICE: The legacy response format will be deprecated on November 1st, 2025. The legacy parameter currently defaults to true but will be removed. Please migrate to the modern format by setting legacy=false. See https://docs.clado.ai/api-reference/changelog for migration details.

​
Search People

curl -X GET "https://search.clado.ai/api/search?query=software engineers in San Francisco&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

ParameterTypeRequiredDescription
querystringYes*Natural language search query (*Required for new searches, optional when using search_id)
limitintegerNoMaximum number of results (default: 30, max: 100)
companiesarray[string]NoList of company names to filter results by
schoolsarray[string]NoList of school names to filter results by
advanced_filteringbooleanNoEnable AI agent-based filtering for higher quality results (default: true)
search_idstringNoID from a previous search to continue pagination
offsetintegerNoNumber of results to skip for pagination (default: 0)
legacybooleanNoDEPRECATED: Return results in legacy format (default: true). Will be removed November 1st, 2025

​
Examples

Basic Search: 
curl -X GET "https://search.clado.ai/api/search?query=data scientists at startups" \
  -H "Authorization: Bearer YOUR_API_KEY"
Search with Limit: 
curl -X GET "https://search.clado.ai/api/search?query=product managers&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
Search with Advanced Filtering: 
curl -X GET "https://search.clado.ai/api/search?query=senior engineers at FAANG&limit=20&advanced_filtering=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
Continue Search with Pagination: 
# First search returns a search_id
curl -X GET "https://search.clado.ai/api/search?query=data scientists&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Returns: { ..., "search_id": "550e8400-e29b-41d4-a716-446655440000" }

# Get next 20 results using search_id and offset
curl -X GET "https://search.clado.ai/api/search?search_id=550e8400-e29b-41d4-a716-446655440000&offset=20&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "results": [
    {
      "profile": {
        "id": "3917303",
        "name": "Alex Johnson",
        "location": "San Francisco, CA",
        "headline": "Senior Software Engineer at TechCorp Inc",
        "description": "Experienced software engineer specializing in machine learning and distributed systems",
        "linkedin_url": "https://www.linkedin.com/in/alexjohnson"
      },
      "experience": [
        {
          "title": "Senior Software Engineer",
          "company_name": "TechCorp Inc",
          "start_date": "2021-01-01T00:00:00",
          "end_date": "1970-01-01T00:00:00",
          "description": "Working on machine learning infrastructure and scalable systems",
          "location": "San Francisco, CA"
        }
      ],
      "education": [
        {
          "degree": "Master of Science",
          "field_of_study": "Computer Science",
          "school_name": "State University",
          "start_date": "2017-09-01T00:00:00",
          "end_date": "2019-06-01T00:00:00"
        }
      ]
    }
  ],
  "total": 1,
  "query": "software engineers in San Francisco",
  "search_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Query Examples

QueryDescription
”software engineers at major tech companies”Find engineers at leading technology companies
”product managers with MBA”Find PMs with MBA education
”founders in fintech”Find startup founders in financial technology
”data scientists with PhD”Find PhD-level data scientists
”marketing directors in healthcare”Find marketing leaders in health industry

​
Rate Limits

Rate limits vary by subscription tier:
  • Free Tier: 5 requests per minute
  • Tier 1: 20 requests per minute
  • Tier 2: 200 requests per minute
  • Tier 3: 400 requests per minute

​
Error Responses

Status CodeDescription
400Bad Request - Invalid parameters or limit exceeded
401Unauthorized - API key missing or invalid
422Validation Error - Missing required ‘query’ parameter
500Internal Server Error - Search processing error
503Service Unavailable - Search service temporarily down

​
Notes

  • This endpoint costs 5 credits per request (standard search)
  • When advanced_filtering is enabled: 1 credit per result returned (no base charge)
  • End date of “1970-01-01T00:00:00” indicates current position
  • Results are ranked by AI-powered relevance matching
  • When advanced_filtering is enabled:
    • An AI agent reviews and filters results after the initial search
    • You may receive fewer results than the requested limit due to quality filtering
    • Results will have higher relevance and quality but may take slightly longer to process
    • Only pay for results that pass the AI filtering (1 credit per result)

​
Pagination

  • Every search returns a search_id that can be used to paginate through results
  • Use the search_id with the offset parameter to get subsequent pages
  • The same search criteria and OpenSearch query are reused for pagination
  • Pagination requests with search_id do not require the original query parameter
  • Results maintain consistent ordering across paginated requests
  • Example: To get results 21-40, use search_id from the initial search with offset=20 and limit=20

Authorizations

​
Authorization
string
header
required

API key authentication. Keys start with 'lk_'.

Query Parameters

​
query
string

Natural language search query to find LinkedIn profiles (e.g., 'software engineers at tech companies', 'product managers with MBA'). Required for new searches, optional when using search_id for continuation

​
limit
integer
default:30

Maximum number of profiles to return in the response (1-100)

Required range: 1 <= x <= 100
​
companies
string[]

List of company names to filter results by

​
schools
string[]

List of school names to filter results by

​
advanced_filtering
boolean
default:true

Enable AI agent-based filtering to improve result quality. When enabled, an AI agent reviews all results before returning them, which may return fewer results than the requested limit but with higher relevance and quality

​
search_id
string<uuid>

ID from a previous search to continue pagination. When provided, uses the same search criteria and query from the original search

​
offset
integer
default:0

Number of results to skip for pagination. Used with search_id to get subsequent pages of results

Required range: x >= 0
​
legacy
boolean
default:true

DEPRECATED: Return results in legacy format (default: true). Will be removed November 1st, 2025

Response

Successful response

​
results
object[]

Array of user profiles matching the search query

​
total
integer

Total number of profiles found

​
query
string

The search query that was executed

​
search_id
string<uuid>

Unique identifier for this search. Use this with offset parameter to paginate through results