> ## Documentation Index > Fetch the complete documentation index at: https://docs.clado.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search People > Search for LinkedIn profiles using natural language queries with pagination support 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](https://docs.clado.ai/api-reference/changelog) for migration details. ## Search People ```bash theme={null} 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 | Parameter | Type | Required | Description | | ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------- | | query | string | Yes\* | Natural language search query (\*Required for new searches, optional when using search\_id) | | limit | integer | No | Maximum number of results (default: 30, max: 100) | | companies | array\[string] | No | List of company names to filter results by | | schools | array\[string] | No | List of school names to filter results by | | advanced\_filtering | boolean | No | Enable AI agent-based filtering for higher quality results (default: true) | | search\_id | string | No | ID from a previous search to continue pagination | | offset | integer | No | Number of results to skip for pagination (default: 0) | | legacy | boolean | No | **DEPRECATED**: Return results in legacy format (default: true). Will be removed November 1st, 2025 | ### Examples **Basic Search:** ```bash theme={null} curl -X GET "https://search.clado.ai/api/search?query=data scientists at startups" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Search with Limit:** ```bash theme={null} curl -X GET "https://search.clado.ai/api/search?query=product managers&limit=50" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Search with Advanced Filtering:** ```bash theme={null} 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:** ```bash theme={null} # 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 ```json theme={null} { "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 | Query | Description | | -------------------------------------------- | ---------------------------------------------- | | "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 Code | Description | | ----------- | ----------------------------------------------------- | | 400 | Bad Request - Invalid parameters or limit exceeded | | 401 | Unauthorized - API key missing or invalid | | 422 | Validation Error - Missing required 'query' parameter | | 500 | Internal Server Error - Search processing error | | 503 | Service 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` ## OpenAPI ````yaml GET /api/search openapi: 3.1.0 info: title: Clado Search & Enrichment API description: API for searching LinkedIn profiles and enriching contact information version: 1.0.0 servers: - url: https://search.clado.ai description: Production server security: - bearerAuth: [] paths: /api/search: get: tags: - Search summary: Search People description: >- Search for users with pagination support. Returns a search_id for continuing searches with offset. Costs 5 credits per request (standard) or 1 credit per result (with advanced_filtering). Rate limits vary by tier: 5/min (free), 20/min (Tier 1), 200/min (Tier 2), 400/min (Tier 3). operationId: searchPeople parameters: - name: query in: query required: false description: >- 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 schema: type: string - name: limit in: query required: false description: Maximum number of profiles to return in the response (1-100) schema: type: integer default: 30 minimum: 1 maximum: 100 - name: companies in: query required: false description: List of company names to filter results by schema: type: array items: type: string - name: schools in: query required: false description: List of school names to filter results by schema: type: array items: type: string - name: advanced_filtering in: query required: false description: >- 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 schema: type: boolean default: true - name: search_id in: query required: false description: >- ID from a previous search to continue pagination. When provided, uses the same search criteria and query from the original search schema: type: string format: uuid - name: offset in: query required: false description: >- Number of results to skip for pagination. Used with search_id to get subsequent pages of results schema: type: integer default: 0 minimum: 0 - name: legacy in: query required: false description: >- DEPRECATED: Return results in legacy format (default: true). Will be removed November 1st, 2025 schema: type: boolean default: true responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/UserSearchResponse' '400': description: Bad request - invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Limit is invalid '401': description: Unauthorized - invalid or expired API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Invalid or expired API key '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: 'Internal server error: Query execution failed' '503': description: Service temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Search service temporarily unavailable components: schemas: UserSearchResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/UserResult' description: Array of user profiles matching the search query total: type: integer description: Total number of profiles found query: type: string description: The search query that was executed search_id: type: string format: uuid description: >- Unique identifier for this search. Use this with offset parameter to paginate through results example: 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 ErrorResponse: type: object properties: detail: type: string description: Error message required: - detail UserResult: type: object properties: profile: $ref: '#/components/schemas/UserProfile' experience: type: array items: $ref: '#/components/schemas/Experience' description: Work experience history education: type: array items: $ref: '#/components/schemas/Education' description: Educational background posts: type: array items: $ref: '#/components/schemas/Post' description: Recent LinkedIn posts and activity awards: type: array items: $ref: '#/components/schemas/Award' description: Awards and honors received certifications: type: array items: $ref: '#/components/schemas/Certification' description: Professional certifications organizations: type: array items: $ref: '#/components/schemas/Organization' description: Organizations and associations patents: type: array items: $ref: '#/components/schemas/Patent' description: Patents filed or granted projects: type: array items: $ref: '#/components/schemas/Project' description: Professional projects publications: type: array items: $ref: '#/components/schemas/Publication' description: Published works and articles github_repos: type: array items: $ref: '#/components/schemas/GitHubRepo' description: GitHub repositories UserProfile: type: object properties: id: type: string description: Unique identifier for the profile name: type: string description: Full name of the person location: type: string description: Geographic location location_country: type: string description: Country of location location_regions: type: array items: type: string description: Geographic regions (e.g., Americas, Northern America, AMER) headline: type: string description: Professional headline or current position description: type: string description: About section or professional summary linkedin_url: type: string description: LinkedIn profile URL picture_permalink: type: string description: Profile picture URL connections_count: type: integer description: Number of LinkedIn connections followers_count: type: integer description: Number of LinkedIn followers is_working: type: boolean description: Whether the person is currently working is_decision_maker: type: boolean description: Whether the person is identified as a decision maker total_experience_duration_months: type: integer description: Total work experience in months projected_total_salary: type: number description: Estimated total salary post_count: type: integer description: Number of LinkedIn posts posts: type: string description: Recent posts content liked_posts: type: string description: Content of posts the user has liked recommendations: type: string description: LinkedIn recommendations recommendations_count: type: integer description: Number of recommendations skills: type: array items: type: string description: Professional skills Experience: type: object properties: title: type: string description: Job title company_name: type: string description: Company name start_date: type: string description: Start date in ISO format end_date: type: string description: End date in ISO format (1970-01-01T00:00:00 for current) description: type: string description: Job description location: type: string description: Work location Education: type: object properties: degree: type: string description: Degree type field_of_study: type: string description: Field of study school_name: type: string description: School or university name start_date: type: string description: Start date in ISO format end_date: type: string description: End date in ISO format Post: type: object properties: text: type: string description: Post content text totalReactionCount: type: integer description: Total number of reactions likeCount: type: integer description: Number of like reactions appreciationCount: type: integer description: Number of appreciation reactions empathyCount: type: integer description: Number of empathy reactions InterestCount: type: integer description: Number of interest reactions praiseCount: type: integer description: Number of praise reactions commentsCount: type: integer description: Number of comments repostsCount: type: integer description: Number of reposts postUrl: type: string description: URL to the LinkedIn post postedAt: type: string description: Human-readable time since posted postedDate: type: string description: ISO timestamp of when posted postedDateTimestamp: type: integer description: Unix timestamp of when posted reposted: type: boolean description: Whether this is a repost urn: type: string description: LinkedIn URN identifier author: $ref: '#/components/schemas/PostAuthor' image: type: array items: $ref: '#/components/schemas/PostImage' description: Post images video: type: array items: $ref: '#/components/schemas/PostVideo' description: Post videos mentions: type: array items: $ref: '#/components/schemas/PostMention' description: People mentioned in the post companyMentions: type: array items: $ref: '#/components/schemas/CompanyMention' description: Companies mentioned in the post isBrandPartnership: type: boolean description: Whether this is a brand partnership post Award: type: object properties: title: type: string description: Award title issuer: type: string description: Organization that issued the award description: type: string description: Award description date_year: type: integer description: Year the award was received date_month: type: integer description: Month the award was received order_in_profile: type: integer description: Display order in profile Certification: type: object properties: title: type: string description: Certification title issuer: type: string description: Issuing organization date_from_year: type: integer description: Year certification was obtained date_from_month: type: integer description: Month certification was obtained date_to_year: type: integer description: Year certification expires date_to_month: type: integer description: Month certification expires Organization: type: object properties: organization_name: type: string description: Name of the organization position: type: string description: Position held in the organization description: type: string description: Description of role or involvement date_from_year: type: integer description: Start year date_from_month: type: integer description: Start month date_to_year: type: integer description: End year date_to_month: type: integer description: End month Patent: type: object properties: title: type: string description: Patent title description: type: string description: Patent description status: type: string description: Patent status (pending, granted, etc.) date_year: type: integer description: Year of patent filing/grant date_month: type: integer description: Month of patent filing/grant Project: type: object properties: name: type: string description: Project name description: type: string description: Project description date_from_year: type: integer description: Project start year date_from_month: type: integer description: Project start month date_to_year: type: integer description: Project end year date_to_month: type: integer description: Project end month Publication: type: object properties: title: type: string description: Publication title description: type: string description: Publication description or abstract publisher_names: type: string description: Publisher or journal name date_year: type: integer description: Publication year date_month: type: integer description: Publication month GitHubRepo: type: object properties: name: type: string description: Repository name summary: type: string description: Repository description stars: type: integer description: Number of stars contributions_count: type: integer description: Number of contributions PostAuthor: type: object properties: firstName: type: string description: Author's first name lastName: type: string description: Author's last name username: type: string description: LinkedIn username url: type: string description: LinkedIn profile URL PostImage: type: object properties: url: type: string description: Image URL width: type: integer description: Image width in pixels height: type: integer description: Image height in pixels PostVideo: type: object properties: url: type: string description: Video URL width: type: integer description: Video width in pixels height: type: integer description: Video height in pixels PostMention: type: object properties: firstName: type: string description: Mentioned person's first name lastName: type: string description: Mentioned person's last name urn: type: string description: LinkedIn URN publicIdentifier: type: string description: LinkedIn public identifier CompanyMention: type: object properties: id: type: integer description: Company ID name: type: string description: Company name publicIdentifier: type: string description: Company LinkedIn identifier url: type: string description: Company LinkedIn URL securitySchemes: bearerAuth: type: http scheme: bearer description: API key authentication. Keys start with 'lk_'. ````