# API Changelog
Source: https://docs.clado.ai/api-reference/changelog
Breaking changes and migration guide for the Clado Search & Enrichment API
## \[October 2025] - Legacy Format Deprecation Notice + Realtime Data
**BREAKING CHANGE**: The legacy response format will be deprecated on **November 1st, 2025**.
The modern format is significantly more complex with 97+ profile fields, nested models, and detailed type safety. Review the full type definitions before migrating.
### 🚀 New: Realtime Data Updates
All API endpoints now return **realtime data**:
* Profile information is continuously updated
* Company details reflect current status
* Engagement metrics (connections, followers, posts) are live
* Experience changes are tracked and identified in real-time
* No more stale data - always get the most current information available
### Affected Endpoints
* `GET /api/search` - Search People
* `GET /api/search/deep_research/{job_id}` - Get Deep Research Status
* `GET /api/enrich/linkedin` - Get LinkedIn Profile
***
## Migration Complexity Warning
The modern format contains **significantly more data** than the legacy format. A single profile response can include:
* **97 profile fields** (vs 10-15 in legacy)
* **48 experience fields per job** (vs 10-15 in legacy)
* **Complex nested objects** for breakdowns and change tracking
* **Detailed company information** including financials, stock data, geographic details
* **Structured date fields** with separate year/month instead of formatted strings
* **Type-safe arrays** instead of string representations
**Plan accordingly** - your parsing logic will need significant updates.
***
## Implementation Details
### Response Format Migration
The API supports both formats during the transition period:
* **Default (Modern)**: Full type-safe models with extensive data
* **Legacy**: Simplified format using transformation functions
* **Migration Period**: Both formats supported until November 1st, 2025
***
## Complete Modern Response Example
```json theme={null}
{
"results": [
{
// Basic Identity (10 fields)
"id": "123456789",
"name": "John Doe", // Legacy compatibility
"full_name": "John Michael Doe", // Primary modern field
"first_name": "John",
"first_name_initial": "J",
"middle_name": "Michael",
"middle_name_initial": "M",
"last_name": "Doe",
"last_name_initial": "D",
// Professional Info (3 fields)
"headline": "Senior Software Engineer at TechCorp Inc",
"description": "Experienced software engineer specializing in ML",
"summary": "Full professional summary with detailed background...",
// Profile Images (2 fields)
"picture_permalink": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
"picture_url": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
// Location Breakdown (8 fields)
"location": "San Francisco, CA", // Legacy compatibility
"location_full": "San Francisco, California, United States",
"location_country": "United States",
"location_city": "San Francisco",
"location_state": "California",
"location_country_iso2": "US",
"location_country_iso3": "USA",
"location_regions": ["Americas", "Northern America", "AMER"],
// LinkedIn Data (2 fields)
"linkedin_url": "https://www.linkedin.com/in/johndoe",
"linkedin_shorthand_names": ["johndoe"],
// Engagement Metrics (5 fields)
"connections_count": 500,
"followers_count": 1200,
"post_count": 15,
"posts": "Recent posts content as concatenated string...",
"liked_posts": "Liked posts content as concatenated string...",
"recommendations": "Recommendations as concatenated string...",
"recommendations_count": 8,
// Work Status (3 fields)
"is_working": 1, // 0/1 or true/false
"is_decision_maker": 0, // 0/1 or true/false
"total_experience_duration_months": 48,
// Experience Breakdowns (2 complex arrays)
"total_experience_duration_months_breakdown_department": [
{
"department": "Engineering and Technical",
"management_level": null,
"total_experience_duration_months": 48
}
],
"total_experience_duration_months_breakdown_management_level": [
{
"department": null,
"management_level": "Senior",
"total_experience_duration_months": 24
}
],
// Active Experience Details (5 fields)
"active_experience_company_id": 12345,
"active_experience_title": "Senior Software Engineer",
"active_experience_description": "Working on ML systems...",
"active_experience_department": "Engineering and Technical",
"active_experience_management_level": "Senior",
// Skill Categories (5 fields)
"skills": ["Python", "JavaScript", "Machine Learning"],
"inferred_skills": ["Python", "ML", "Data Science"],
"historical_skills": ["Java", "C++", "PHP"],
"interests": ["AI", "Machine Learning", "Distributed Systems"],
"services": "Consulting, Development, Technical Leadership",
// Education Summary (2 fields)
"last_graduation_date": 2022,
"education_degrees": ["Computer Science", "MBA"],
// Salary Projections (16 fields!)
"projected_total_salary": 150000.0,
"projected_base_salary_p25": 120000.0,
"projected_base_salary_median": 140000.0,
"projected_base_salary_p75": 160000.0,
"projected_base_salary_period": "ANNUAL",
"projected_base_salary_currency": "USD",
"projected_base_salary_updated_at": "2024-01-01",
"projected_additional_salary_period": "ANNUAL",
"projected_additional_salary_currency": "USD",
"projected_additional_salary_updated_at": "2024-01-01",
"projected_total_salary_p25": 130000.0,
"projected_total_salary_median": 150000.0,
"projected_total_salary_p75": 170000.0,
"projected_total_salary_period": "ANNUAL",
"projected_total_salary_currency": "USD",
"projected_total_salary_updated_at": "2024-01-01",
"projected_additional_salary": [
{
"projected_additional_salary_type": "Bonus",
"projected_additional_salary_p25": 10000.0,
"projected_additional_salary_median": 15000.0,
"projected_additional_salary_p75": 20000.0
}
],
// Content Statistics (6 fields)
"patents_count": 2,
"patents_topics": ["AI", "Machine Learning"],
"publications_count": 5,
"publications_topics": ["Software Engineering", "AI"],
"projects_count": 3,
"projects_topics": ["Web Development", "ML"],
// Metadata Timestamps (7 fields)
"created_at": "2023-01-01T00:00:00Z",
"updated_at": "2024-01-01T00:00:00Z",
"checked_at": "2024-01-01T00:00:00Z",
"changed_at": "2024-01-01T00:00:00Z",
"experience_change_last_identified_at": "2024-01-01T00:00:00Z",
"op_created_at": "2023-01-01T00:00:00Z",
"op_updated_at": "2024-01-01T00:00:00Z",
// Change Tracking Arrays (4 complex arrays)
"profile_root_field_changes_summary": [
{
"field_name": "headline",
"change_type": "updated",
"last_changed_at": "2024-01-01T00:00:00Z"
}
],
"profile_collection_field_changes_summary": [
{
"field_name": "experience",
"last_changed_at": "2024-01-01T00:00:00Z"
}
],
"experience_recently_started": [
{
"company_id": 12345,
"company_name": "TechCorp",
"company_url": "https://techcorp.com",
"company_shorthand_name": "techcorp",
"date_from": "2024-01",
"date_to": null,
"title": "Senior Software Engineer",
"identification_date": "2024-01-01T00:00:00Z"
}
],
"experience_recently_closed": [],
"experience": [
{
// Position Details (6 fields)
"active_experience": 1, // 0 or 1
"position_title": "Senior Software Engineer",
"department": "Engineering and Technical",
"management_level": "Senior",
"location": "San Francisco, CA",
"description": "Working on ML systems and distributed architecture...",
// Date Information (7 fields)
"date_from": "January 2022", // Human readable
"date_from_year": 2022, // Separate integer fields
"date_from_month": 1,
"date_to": null, // Null for current
"date_to_year": null,
"date_to_month": null,
"duration_months": 24, // Pure integer
// Company Basic Info (4 fields)
"company_id": 12345, // Pure integer
"company_name": "TechCorp Inc",
"company_type": "Privately Held",
"company_founded_year": 2010,
// Company Engagement (2 fields)
"company_followers_count": 500,
"company_website": "https://techcorp.com",
// Company Social Media (4 fields)
"company_facebook_url": "https://facebook.com/techcorp", // Can be string or array
"company_twitter_url": ["https://twitter.com/techcorp"],
"company_professional_network_url": null,
"company_linkedin_url": "https://linkedin.com/company/techcorp",
// Company Size & Industry (4 fields)
"company_size_range": "201-500 employees",
"company_employees_count": 350,
"company_industry": "Software Development",
"company_categories_and_keywords": ["software", "technology", "saas"],
// Company Financials (6 fields)
"company_annual_revenue_source_1": 50000000.0,
"company_annual_revenue_currency_source_1": "USD",
"company_annual_revenue_source_5": 50000000,
"company_annual_revenue_currency_source_5": "USD",
"company_employees_count_change_yearly_percentage": 15.5,
"company_last_funding_round_date": "2023-01-01",
"company_last_funding_round_amount_raised": 10000000,
// Company Geographic Details (9 fields)
"company_hq_full_address": "123 Main St, San Francisco, CA 94105, US",
"company_hq_country": "United States",
"company_hq_regions": ["Americas", "Northern America", "AMER"],
"company_hq_country_iso2": "US",
"company_hq_country_iso3": "USA",
"company_hq_city": "San Francisco",
"company_hq_state": "California",
"company_hq_street": "123 Main St",
"company_hq_zipcode": "94105",
// Company Metadata (4 fields)
"company_last_updated_at": "2024-01-01",
"company_stock_ticker": [
{
"exchange": "NASDAQ",
"ticker": "TECH"
}
],
"company_is_b2b": 1, // 0 or 1
"order_in_profile": 1
}
],
"education": [
{
// Basic Education (3 fields)
"degree": "Master of Science",
"description": "Focus on Machine Learning and Distributed Systems",
"institution_url": "https://university.edu",
"institution_name": "State University",
// Institution Geographic Details (9 fields)
"institution_full_address": "456 University Ave, Berkeley, CA 94720, US",
"institution_country_iso2": "US",
"institution_country_iso3": "USA",
"institution_regions": ["Americas", "Northern America", "AMER"],
"institution_city": "Berkeley",
"institution_state": "California",
"institution_street": "456 University Ave",
"institution_zipcode": "94720",
// Education Timeline (2 fields)
"date_from_year": 2017,
"date_to_year": 2019,
// Additional Info (2 fields)
"activities_and_societies": "Computer Science Club, AI Research Group",
"order_in_profile": 1
}
],
"languages": [
{
"language": "English",
"proficiency": "Native",
"order_in_profile": 1
},
{
"language": "Spanish",
"proficiency": "Professional",
"order_in_profile": 2
}
],
"awards": [
{
"title": "Employee of the Year",
"issuer": "TechCorp Inc",
"description": "Outstanding contribution to ML infrastructure",
"date_year": 2023,
"date_month": 12,
"order_in_profile": 1
}
],
"certifications": [
{
"title": "AWS Solutions Architect",
"issuer": "Amazon Web Services",
"date_from_year": 2022,
"date_from_month": 6,
"date_to_year": 2025,
"date_to_month": 6
}
],
"organizations": [
{
"organization_name": "IEEE Computer Society",
"position": "Member",
"description": "Active member participating in ML conferences",
"date_from_year": 2020,
"date_from_month": 1,
"date_to_year": null,
"date_to_month": null
}
],
"patents": [
{
"title": "Distributed Machine Learning System",
"description": "Method for optimizing ML training across distributed nodes",
"status": "Granted",
"date_year": 2023,
"date_month": 8
}
],
"projects": [
{
"name": "ML Infrastructure Platform",
"description": "Built scalable ML training and inference platform",
"date_from_year": 2022,
"date_from_month": 1,
"date_to_year": 2023,
"date_to_month": 12
}
],
"publications": [
{
"title": "Optimizing Distributed ML Training",
"description": "Research on improving efficiency of distributed machine learning",
"publisher_names": ["IEEE Transactions on Parallel and Distributed Systems"],
"date_year": 2023,
"date_month": 3
}
],
"github_repos": [
{
"name": "ml-distributed-trainer",
"summary": "Open source distributed ML training framework",
"stars": 245,
"contributions_count": 156
}
],
"courses": [
{
"organizer": "Stanford University",
"title": "Advanced Machine Learning",
"order_in_profile": 1
}
],
"match_data": {
"similarity_score": 0.95,
"matched_criteria": ["machine learning", "senior engineer", "python"]
}
}
],
"total": 1,
"query": "senior machine learning engineers at tech companies",
"search_id": "550e8400-e29b-41d4-a716-446655440000"
}
```
**Field Count Summary (per result object):**
* **Root-level fields**: 97 fields across all categories (identity, professional info, location, engagement, work status, skills, salary projections, content statistics, metadata, change tracking)
* **Experience array**: 48 fields per job including 30+ company-specific fields
* **Education array**: 15 fields including detailed institution geography
* **Plus**: Languages, Awards, Certifications, Organizations, Patents, Projects, Publications, GitHub repos, Courses
***
# Cancel Deep Research
Source: https://docs.clado.ai/api-reference/endpoint/cancel-deep-research
POST /api/search/deep_research/{job_id}/cancel
Cancel a running deep research job
Cancel a deep research job that is currently running. This will stop the job and prevent further credit consumption.
## Cancel Deep Research
```bash theme={null}
curl -X POST https://search.clado.ai/api/search/deep_research/550e8400-e29b-41d4-a716-446655440000/cancel \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------------- |
| job\_id | string | Yes | The job ID of the deep research job to cancel |
### Response
```json theme={null}
{
"success": true,
"message": "Deep research job cancelled successfully"
}
```
### Response (Already Completed)
```json theme={null}
{
"success": false,
"message": "Cannot cancel job: already completed"
}
```
## Error Responses
| Status Code | Description |
| ----------- | ---------------------------------------------------------------- |
| 401 | Unauthorized - API key missing or invalid |
| 404 | Not Found - Job ID does not exist |
| 409 | Conflict - Job cannot be cancelled (already completed or failed) |
| 500 | Internal Server Error - Error cancelling job |
## Notes
* This endpoint is **free** - no credits are consumed
* No rate limiting applied
* Only pending jobs can be cancelled
* Cancelled jobs will not consume additional credits and only deduct credits correlating to partial results
* Partial results may be available for cancelled jobs
* Use the [Get Deep Research Status](/api-reference/endpoint/get-deep-research-status) endpoint to check final status
# Continue Deep Research
Source: https://docs.clado.ai/api-reference/endpoint/continue-deep-research
POST /api/search/deep_research/{job_id}/more
Expand existing deep research with additional results
Continue a completed deep research job to get additional results. This allows you to expand your search beyond the initial limit.
## Continue Deep Research
```bash theme={null}
curl -X POST https://search.clado.ai/api/search/deep_research/550e8400-e29b-41d4-a716-446655440000/more \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"additional_limit": 50
}'
```
### Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------------------- |
| job\_id | string | Yes | The job ID of the completed deep research job |
### Request Body
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ------------------------------------ |
| additional\_limit | integer | No | 30 | Number of additional results to find |
### Response
```json theme={null}
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"message": "Deep research continuation initiated"
}
```
## Requirements
* The original job must be in "completed" status
* There must be more unprocessed results available
* You must have sufficient credits for the additional results
## Error Responses
| Status Code | Description |
| ----------- | ---------------------------------------------------------------------- |
| 401 | Unauthorized - API key missing or invalid |
| 402 | Payment Required - Insufficient credits |
| 404 | Not Found - Job ID does not exist |
| 409 | Conflict - Job is not in completed status or no more results available |
| 500 | Internal Server Error - Error initiating continuation |
## Rate Limits
Rate limits vary by subscription tier (same as deep research):
* **Free Tier**: 2 requests per minute
* **Tier 1**: 5 requests per minute
* **Tier 2**: 50 requests per minute
* **Tier 3**: 100 requests per minute
## Notes
* Each additional profile returned costs **1 credit**
* Use [Get Deep Research Status](/api-reference/endpoint/get-deep-research-status) to monitor progress
* Results will be appended to the original job results
# Get Contact Information
Source: https://docs.clado.ai/api-reference/endpoint/get-contact-information
GET /api/enrich/contacts
Find email addresses and phone numbers for LinkedIn profiles
Retrieve contact information (emails and phone numbers) for a LinkedIn profile. You can optionally specify whether to get emails, phone numbers, or both using the enrichment parameters. When both are requested, the system uses a waterfall approach through multiple data sources to maximize the likelihood of finding both types of contact information.
## Get Contact Information
```bash theme={null}
# By LinkedIn URL
curl -X GET "https://search.clado.ai/api/enrich/contacts?linkedin_url=https://www.linkedin.com/in/alexjohnson" \
-H "Authorization: Bearer YOUR_API_KEY"
# By Email
curl -X GET "https://search.clado.ai/api/enrich/contacts?email=alex.johnson@example.com" \
-H "Authorization: Bearer YOUR_API_KEY"
# By Phone
curl -X GET "https://search.clado.ai/api/enrich/contacts?phone=+1234567890" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Query Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------- | ------------ | ---------------------------------------------------------------- |
| linkedin\_url | string | One of these | LinkedIn profile URL to enrich |
| email | string | One of these | Email address to find profile |
| phone | string | One of these | Phone number to find profile |
| email\_enrichment | boolean | Optional | If true, returns emails (costs 4 credits if email found) |
| phone\_enrichment | boolean | Optional | If true, returns phone numbers (costs 10 credits if phone found) |
**Note:**
* Exactly one of `linkedin_url`, `email`, or `phone` must be provided.
* Both `email_enrichment` and `phone_enrichment` can be true at the same time to request both types of contact info.
* If both are false (default), returns all available contact info.
* When both enrichments are requested, the system attempts to find both but only charges for what's actually found.
### Examples
**Get Contact Info by LinkedIn URL (all contact info):**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/contacts?linkedin_url=https://www.linkedin.com/in/alexjohnson" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Get Only Emails:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/contacts?linkedin_url=https://www.linkedin.com/in/alexjohnson&email_enrichment=true" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Get Only Phone Numbers:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/contacts?linkedin_url=https://www.linkedin.com/in/alexjohnson&phone_enrichment=true" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Get Both Email and Phone Numbers:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/contacts?linkedin_url=https://www.linkedin.com/in/alexjohnson&email_enrichment=true&phone_enrichment=true" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Get Contact Info by Email:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/contacts?email=john.doe@company.com" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Get Contact Info by Phone:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/contacts?phone=+14155552671" \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Response Format
### Success Response
```json theme={null}
{
"data": [
{
"error": false,
"contacts": [
{
"type": "email",
"value": "alex.johnson@techcorp.com",
"rating": 100,
"subType": "work"
},
{
"type": "phone",
"value": "+1-555-123-4567",
"rating": 90,
"subType": "mobile"
}
],
"social": [
{
"link": "https://www.linkedin.com/in/alexjohnson",
"type": "li",
"rating": 100
}
],
"provider": "database_verified"
}
]
}
```
### Response Fields
| Field | Type | Description |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `data` | array | Array containing contact information (always has one item) |
| `data.error` | boolean | Whether an error occurred during lookup |
| `data.contacts` | array | Array of contact information (emails/phones) |
| `data.contacts.type` | string | Contact type: `"email"` or `"phone"` |
| `data.contacts.value` | string | The actual email address or phone number |
| `data.contacts.rating` | integer | Confidence score from 0-100 (higher is better) |
| `data.contacts.subType` | string | Contact classification: `"personal"`, `"work"`, `"verified"`, `"mobile"`, `"work_phone"` |
| `data.social` | array | Array of social media profiles found |
| `data.social.link` | string | URL of the social media profile |
| `data.social.type` | string | Platform type (e.g., `"li"` for LinkedIn) |
| `data.social.rating` | integer | Confidence score from 0-100 |
| `data.provider` | string | Data source (optional): `"database_verified"`, `"database_bouncer_verified"`, etc. |
## Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------------------------------------ |
| 400 | Bad Request - Must provide exactly one of: LinkedIn URL, email, or phone |
| 401 | Unauthorized - API key missing or invalid |
| 402 | Payment Required - Insufficient credits or requires paid plan |
| 500 | Internal Server Error - Enrichment service error |
## Rate Limits
Rate limits vary by subscription tier:
* **Free Tier**: 0 requests per minute (not available)
* **Tier 1**: 5 requests per minute
* **Tier 2**: 60 requests per minute
* **Tier 3**: 120 requests per minute
## Notes
### Pricing
* **Default (all contact info):** 4 credits per request
* **Email enrichment only:** 4 credits if email is found, 0 credits if not found
* **Phone enrichment only:** 10 credits if phone is found, 0 credits if not found
* **Both email and phone enrichment:** Only charged for what's found
* Both found: 14 credits (4 for email + 10 for phone)
* Only email found: 4 credits
* Only phone found: 10 credits
* Neither found: 0 credits
### Other Information
* Requires purchased credits (not available on free trial)
* Rating scores range from 0 to 100 (higher is better)
* Multiple email addresses and phone numbers may be returned with different ratings
* Social media profiles may also be included in the response
* Both email and phone enrichment can be requested simultaneously
* When both are requested, the system uses a waterfall approach to maximize success rate
# Get Credits
Source: https://docs.clado.ai/api-reference/endpoint/get-credits
GET /api/credits
Check remaining credits for your API key
Check the remaining credit balance for your API key. This endpoint returns your current credit count and last top-up timestamp without consuming any credits.
## Get Credits
```bash theme={null}
curl -X GET "https://search.clado.ai/api/credits" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Response
The endpoint returns a JSON object with your credit information:
```json theme={null}
{
"credits": 150,
"last_topup_at": "2024-01-15T10:30:00Z"
}
```
### Response Fields
| Field | Type | Description |
| --------------- | -------------- | ------------------------------------------------------ |
| credits | integer | Number of credits remaining in your account |
| last\_topup\_at | string or null | ISO 8601 timestamp of your last credit purchase/top-up |
### Examples
**Check Credits:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/credits" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Example Response:**
```json theme={null}
{
"credits": 247,
"last_topup_at": "2024-01-15T10:30:00Z"
}
```
## Error Responses
| Status Code | Description |
| ----------- | ------------------------------------------------- |
| 401 | Unauthorized - API key missing or invalid |
| 404 | Not Found - Unable to retrieve credit information |
| 500 | Internal Server Error - Credit service error |
## Notes
* This endpoint is **free** - no credits are consumed
* `last_topup_at` will be `null` if no credits have been purchased
* Use this endpoint to check balance before making credit-consuming API calls
# Get Deep Research Status
Source: https://docs.clado.ai/api-reference/endpoint/get-deep-research-status
GET /api/search/deep_research/{job_id}
Check the status and results of a deep research job with optional pagination
Check the status of a deep research job and retrieve results when the job is completed. Supports optional pagination for managing large result sets.
> **🚨 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.
## Get Deep Research Status
### Without Pagination (All Results)
```bash theme={null}
curl -X GET https://search.clado.ai/api/search/deep_research/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer YOUR_API_KEY"
```
### With Pagination
```bash theme={null}
# Get first page with 25 results (default page size)
curl -X GET "https://search.clado.ai/api/search/deep_research/550e8400-e29b-41d4-a716-446655440000?page=1" \
-H "Authorization: Bearer YOUR_API_KEY"
# Get second page with custom page size
curl -X GET "https://search.clado.ai/api/search/deep_research/550e8400-e29b-41d4-a716-446655440000?page=2&page_size=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Path Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------- |
| job\_id | string | Yes | The job ID returned from initiating deep research |
### Query Parameters
| Parameter | Type | Required | Description |
| ---------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| page | integer | No | Page number (1-indexed). If not provided, returns all results without pagination |
| page\_size | integer | No | Number of results per page (1-100, default: 25). Only applies when page parameter is provided |
| legacy | boolean | No | **DEPRECATED**: Return results in legacy format (default: true). Will be removed November 1st, 2025 |
### Response (Pending)
```json theme={null}
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"message": "Deep research job is still processing"
}
```
### Response (Completed - Without Pagination)
When no `page` parameter is provided, all results are returned:
```json theme={null}
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"message": "Deep research completed with 47 validated profiles",
"created_at": 1706266200,
"opensearch_results": 150,
"final_results_count": 47,
"total_filtered": 47,
"search_chunk_done": 5,
"search_chunk_total": 5,
"results": [
{
"profile": {
"id": "103901716",
"name": "Alex Johnson",
"location": "San Francisco, California, United States",
"location_country": "United States",
"location_regions": ["Americas", "Northern America", "AMER"],
"headline": "Principal Engineer at TechCorp Inc",
"description": "Machine Learning Engineer at TechCorp. Previously at StartupCo and InnovateTech. Expert in distributed systems and AI infrastructure.",
"linkedin_url": "https://www.linkedin.com/in/alexjohnson",
"picture_permalink": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
"connections_count": 500,
"followers_count": 9497,
"is_working": true,
"is_decision_maker": false,
"total_experience_duration_months": 234,
"projected_total_salary": 285000.0,
"post_count": 12,
"posts": "Excited to share our latest ML research on distributed training optimization. Working on next-gen AI infrastructure at TechCorp.",
"liked_posts": "Three ways to create efficient ML pipelines. Here's a potential breakthrough in self-training AI systems. Excited about the future of distributed computing.",
"recommendations": "Alex is an exceptional engineer with deep expertise in machine learning infrastructure. His work on distributed systems has been instrumental to our team's success.",
"recommendations_count": 8,
"skills": ["Machine Learning", "Python", "Distributed Systems", "PyTorch", "Kubernetes", "AI Infrastructure"]
},
"experience": [
{
"title": "Principal Engineer",
"company_name": "TechCorp Inc",
"start_date": "2022-03-01T00:00:00",
"end_date": "1970-01-01T00:00:00",
"description": "Leading ML infrastructure team, developing scalable AI systems for production deployment",
"location": "San Francisco, CA"
},
{
"title": "Senior Software Engineer",
"company_name": "StartupCo",
"start_date": "2019-06-01T00:00:00",
"end_date": "2022-02-28T00:00:00",
"description": "Built distributed training systems and ML pipelines",
"location": "Palo Alto, 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"
},
{
"degree": "Bachelor of Science",
"field_of_study": "Computer Engineering",
"school_name": "Tech Institute",
"start_date": "2013-09-01T00:00:00",
"end_date": "2017-06-01T00:00:00"
}
],
"posts": [
{
"text": "Excited to share our latest ML research on distributed training optimization",
"totalReactionCount": 156,
"likeCount": 89,
"appreciationCount": 23,
"empathyCount": 18,
"InterestCount": 12,
"praiseCount": 10,
"commentsCount": 24,
"repostsCount": 8,
"postUrl": "https://www.linkedin.com/posts/alexjohnson_ml-research-activity-7150123456789",
"postedAt": "2 days ago",
"postedDate": "2024-01-26T10:30:00Z",
"postedDateTimestamp": 1706266200,
"reposted": false,
"urn": "urn:li:activity:7150123456789",
"author": {
"firstName": "Alex",
"lastName": "Johnson",
"username": "alexjohnson",
"url": "https://www.linkedin.com/in/alexjohnson"
},
"mentions": [],
"companyMentions": [
{
"id": 12345,
"name": "TechCorp Inc",
"publicIdentifier": "techcorp-inc",
"url": "https://www.linkedin.com/company/techcorp-inc"
}
],
"isBrandPartnership": false
}
]
},
{
"profile": {
"id": "203901717",
"name": "Sarah Wilson",
"location": "New York, New York, United States",
"location_country": "United States",
"location_regions": ["Americas", "Northern America", "AMER"],
"headline": "Senior Data Scientist at InnovateTech",
"description": "Data Science leader with 8+ years experience in ML and analytics. Passionate about AI ethics and responsible ML deployment.",
"linkedin_url": "https://www.linkedin.com/in/sarahwilson",
"connections_count": 750,
"followers_count": 3200,
"is_working": true,
"is_decision_maker": true,
"total_experience_duration_months": 96,
"projected_total_salary": 195000.0,
"post_count": 8,
"skills": ["Data Science", "Machine Learning", "Python", "R", "Statistics", "AI Ethics"]
},
"experience": [
{
"title": "Senior Data Scientist",
"company_name": "InnovateTech",
"start_date": "2021-01-01T00:00:00",
"end_date": "1970-01-01T00:00:00",
"description": "Leading data science initiatives and ML model development",
"location": "New York, NY"
}
],
"education": [
{
"degree": "PhD",
"field_of_study": "Statistics",
"school_name": "Research University",
"start_date": "2015-09-01T00:00:00",
"end_date": "2019-12-01T00:00:00"
}
]
}
]
}
```
### Response (Completed - With Pagination)
When `page` parameter is provided, results are paginated:
```json theme={null}
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"message": "Deep research completed with 47 validated profiles",
"created_at": 1706266200,
"opensearch_results": 150,
"final_results_count": 47,
"total_filtered": 47,
"search_chunk_done": 5,
"search_chunk_total": 5,
"results": [
{
"profile": {
"id": "103901716",
"name": "Alex Johnson",
"location": "San Francisco, California, United States",
"headline": "Principal Engineer at TechCorp Inc",
"linkedin_url": "https://www.linkedin.com/in/alexjohnson"
}
}
// ... 24 more results for this page
],
"pagination": {
"page": 1,
"page_size": 25,
"total_pages": 2,
"total_results": 47,
"has_next": true,
"has_previous": false
}
}
```
## Status Values
| Status | Description |
| ---------- | ----------------------------------------------- |
| pending | Job is queued and waiting to start |
| searching | Job is actively searching for profiles |
| processing | Job is validating and processing found profiles |
| completed | Job finished successfully with results |
| error | Job encountered an error |
| cancelled | Job was cancelled by user |
## Error Responses
| Status Code | Description |
| ----------- | ---------------------------------------------------------------------------------------- |
| 400 | Bad Request - Invalid pagination parameters (e.g., page \< 1 or page\_size out of range) |
| 401 | Unauthorized - API key missing or invalid |
| 403 | Forbidden - Not authorized to access this job |
| 404 | Not Found - Job ID does not exist |
## Pagination Notes
* **Optional pagination**: If no `page` parameter is provided, all results are returned (backward compatible)
* **Page numbering**: Pages are 1-indexed (first page is page 1)
* **Page size**: Default is 25 results per page, can be customized from 1 to 100
* **Efficient browsing**: Use pagination to efficiently browse through large result sets
* **Pagination metadata**: The `pagination` object is only included in responses when the `page` parameter is provided
## General Notes
* This endpoint is **free** - no credits are consumed for checking status
* Poll this endpoint periodically to check job progress
* Results will become available gradually as the search is running
* Jobs typically complete within 2-15 minutes depending on query complexity
* The `final_results_count` field shows the total number of validated profiles across all pages
# Get LinkedIn Profile
Source: https://docs.clado.ai/api-reference/endpoint/get-linkedin-profile
GET /api/enrich/linkedin
Retrieve LinkedIn profile data from database
Retrieve LinkedIn profile data from our database. This endpoint provides fast access to previously scraped profile information.
> **🚨 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.
## Get LinkedIn Profile
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/linkedin?linkedin_url=https://www.linkedin.com/in/alexjohnson" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Query Parameters
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | --------------------------------------------------------------------------------------------------- |
| linkedin\_url | string | Yes | LinkedIn profile URL to retrieve |
| legacy | boolean | No | **DEPRECATED**: Return results in legacy format (default: true). Will be removed November 1st, 2025 |
### Examples
**Get Profile from Database:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/linkedin?linkedin_url=https://www.linkedin.com/in/alexjohnson" \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Error Responses
| Status Code | Description |
| ----------- | --------------------------------------------- |
| 400 | Bad Request - Missing or invalid LinkedIn URL |
| 401 | Unauthorized - API key missing or invalid |
| 404 | Not Found - Profile not in database |
| 500 | Internal Server Error - Database error |
## Rate Limits
Rate limits vary by subscription tier:
* **Free Tier**: 5 requests per minute
* **Tier 1**: 20 requests per minute
* **Tier 2**: 100 requests per minute
* **Tier 3**: 200 requests per minute
## Notes
* This endpoint costs 1 credit
* Data may be older than real-time scraping
* If profile not found, consider using the [Scrape LinkedIn Profile](/api-reference/endpoint/scrape-linkedin-profile) endpoint
* End date of "1970-01-01T00:00:00" indicates current position
# Get Post Reactions
Source: https://docs.clado.ai/api-reference/endpoint/get-post-reactions
GET /api/enrich/post-reactions
Analyze LinkedIn post reactions and engagement
Get detailed reaction data for LinkedIn posts, including who reacted and what type of reactions were given.
## Get Post Reactions
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/post-reactions?url=https://www.linkedin.com/posts/alexjohnson_activity-123456789&page=1" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Query Parameters
| Parameter | Type | Required | Description |
| -------------- | ------- | -------- | ----------------------------------------------------- |
| url | string | Yes | LinkedIn post URL to analyze |
| page | integer | No | Page number for pagination (default: 1) |
| reaction\_type | string | No | Filter by reaction type (like, love, celebrate, etc.) |
### Examples
**Get All Reactions:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/post-reactions?url=https://www.linkedin.com/posts/alexjohnson_activity-123456789" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Get Specific Reaction Type:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/post-reactions?url=https://www.linkedin.com/posts/alexjohnson_activity-123456789&reaction_type=like" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Paginated Results:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/post-reactions?url=https://www.linkedin.com/posts/alexjohnson_activity-123456789&page=2" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Response
```json theme={null}
{
"data": {
"post_url": "https://www.linkedin.com/posts/alexjohnson_activity-123456789",
"total_reactions": 245,
"reaction_breakdown": {
"like": 180,
"love": 35,
"celebrate": 20,
"support": 8,
"insightful": 2
},
"reactions": [
{
"profile": {
"name": "Sarah Wilson",
"headline": "Product Manager at StartupCo",
"linkedin_url": "https://www.linkedin.com/in/sarahwilson"
},
"reaction_type": "like",
"timestamp": "2024-01-15T10:30:00Z"
},
{
"profile": {
"name": "David Chen",
"headline": "Software Engineer at InnovateTech",
"linkedin_url": "https://www.linkedin.com/in/davidchen"
},
"reaction_type": "celebrate",
"timestamp": "2024-01-15T11:45:00Z"
}
],
"pagination": {
"current_page": 1,
"total_pages": 5,
"has_next": true
}
}
}
```
## Reaction Types
| Type | Description |
| ---------- | ---------------------- |
| like | Standard like reaction |
| love | Love/heart reaction |
| celebrate | Celebration reaction |
| support | Support reaction |
| insightful | Insightful reaction |
| funny | Funny/laugh reaction |
## Error Responses
| Status Code | Description |
| ----------- | ---------------------------------------------- |
| 400 | Bad Request - Missing or invalid post URL |
| 401 | Unauthorized - API key missing or invalid |
| 402 | Payment Required - Insufficient credits |
| 404 | Not Found - Post not found or private |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Analysis service error |
## Rate Limits
Rate limits vary by subscription tier:
* **Free Tier**: 5 requests per minute
* **Tier 1**: 15 requests per minute
* **Tier 2**: 150 requests per minute
* **Tier 3**: 300 requests per minute
## Notes
* Costs **1 credit** per request
* Results are paginated with up to 50 reactions per page
* Some posts may be private or have restricted access
* Reaction data includes profile information of reactors
# Initiate Deep Research
Source: https://docs.clado.ai/api-reference/endpoint/initiate-deep-research
POST /api/search/deep_research
Initiate a deep research job for comprehensive user profile data.
Deep research is an advanced search feature that performs a broad search to provide comprehensive results. The process is asynchronous and uses a job-based system. To check the status of a job, use the [Get Research Status](/api-reference/endpoint/get-deep-research-status) endpoint.
## Initiate Deep Research
```bash curl theme={null}
curl -X POST https://search.clado.ai/api/search/deep_research \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "software engineers",
"limit": 50,
"hard_filter_company_urls": ["https://www.linkedin.com/company/google", "https://wwww.linkedin.com/company/microsoft"]
}'
```
### Request Body
| Parameter | Type | Required | Default | Description |
| --------------------------- | ---------------- | -------- | ------- | ------------------------------------------------------------------------ |
| query | string | Yes | | The search query to research. |
| limit | integer | No | 30 | The maximum number of results to return. |
| hard\_filter\_company\_urls | array of strings | No | | A list of company LinkedIn URLs to filter results to specific companies. |
### Response
```json theme={null}
{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"message": "Deep research job initiated"
}
```
## Error Responses
| Status Code | Description |
| ----------- | ----------------------------------------- |
| 401 | Unauthorized - API key missing or invalid |
| 402 | Payment Required - Insufficient credits |
## Rate Limits
Rate limits vary by subscription tier:
* **Free Tier**: 2 requests per minute
* **Tier 1**: 5 requests per minute
* **Tier 2**: 50 requests per minute
* **Tier 3**: 100 requests per minute
## Notes
* Deep research jobs can take several minutes to complete.
* The `job_id` returned in the response is used to check the status of the research.
* Each validated profile returned costs 1 credit.
# Scrape LinkedIn Profile
Source: https://docs.clado.ai/api-reference/endpoint/scrape-linkedin-profile
GET /api/enrich/scrape
Extract detailed profile data from LinkedIn URLs
Scrape comprehensive profile data directly from LinkedIn. This endpoint provides the most up-to-date profile information including recent posts and activity.
## Scrape LinkedIn Profile
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/scrape?linkedin_url=https://www.linkedin.com/in/alexjohnson" \
-H "Authorization: Bearer YOUR_API_KEY"
```
### Query Parameters
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------ |
| linkedin\_url | string | Yes | LinkedIn profile URL to scrape |
### Examples
**Scrape Profile Data:**
```bash theme={null}
curl -X GET "https://search.clado.ai/api/enrich/scrape?linkedin_url=https://www.linkedin.com/in/alexjohnson" \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Error Responses
| Status Code | Description |
| ----------- | ---------------------------------------------- |
| 400 | Bad Request - Missing or invalid LinkedIn URL |
| 401 | Unauthorized - API key missing or invalid |
| 402 | Payment Required - Insufficient credits |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Scraping service error |
## Rate Limits
Rate limits vary by subscription tier:
* **Free Tier**: 5 requests per minute
* **Tier 1**: 15 requests per minute
* **Tier 2**: 150 requests per minute
* **Tier 3**: 300 requests per minute
## Notes
* Costs **2 credits** per request
* Provides the most current profile data available
* Includes recent posts and activity when available
* May take longer than database lookups due to real-time scraping
* Some profiles may be private or have restricted access
# Search People
Source: https://docs.clado.ai/api-reference/endpoint/search-people
GET /api/search
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`
# Introduction
Source: https://docs.clado.ai/api-reference/introduction
Introduction to the Clado Search & Enrichment API
The Clado Search & Enrichment API provides powerful capabilities for finding and enriching LinkedIn profiles using natural language queries. Built on advanced AI technology, it transforms simple English queries into precise searches across millions of professional profiles.
## Core Functionality
### **Search API**
* **People Search:** Find LinkedIn profiles using natural language queries
### **Deep Research**
* **Advanced Search:** Comprehensive profile discovery with AI validation
* **Job Management:** Asynchronous processing for large-scale searches
* **Continuation Support:** Expand existing research with additional results
### **Enrichment API**
* **Contact Discovery:** Find email addresses and phone numbers for profiles
* **Profile Scraping:** Extract detailed LinkedIn profile data
* **Bulk Processing:** Enrich multiple profiles simultaneously
* **Post Analytics:** Analyze LinkedIn post reactions and engagement
## How It Works
1. **Natural Language Input:** Submit queries in plain English (e.g., "software engineers at Y Combinator companies")
2. **AI Processing:** Advanced LLMs translate your query into structured search criteria
3. **Intelligent Matching:** Profiles are scored and filtered using AI-powered relevance matching
4. **Data Enrichment:** Enhance results with contact information from multiple data sources
5. **Structured Output:** Receive comprehensive profile data in standardized JSON format
## Authentication & Pricing
* **API Key Required:** All endpoints require Bearer token authentication with keys starting with `lk_`
* **Credit-Based System:** Pay only for successful operations with transparent per-request pricing
* **Rate Limiting:** Built-in rate limits ensure fair usage and optimal performance
## Base URL
All API requests should be made to: `https://search.clado.ai`
# API Pricing
Source: https://docs.clado.ai/api-reference/pricing
Transparent pricing for all Clado API endpoints
## Overview
Clado API uses usage-based pricing with a credit system. You only pay for what you use - each API endpoint consumes a specific number of credits based on the operation performed. Each credit costs \$0.01 USD.
## Search API Pricing
| Endpoint | Description | Cost per Request |
| --------------------------------------------- | ------------------------------------ | ---------------------------- |
| **Search People (default)** | AI agent-filtered search results | 1 credit per result returned |
| **Search People (advanced\_filtering=false)** | Standard search without AI filtering | 5 credits (fixed cost) |
### Search Pricing Details
* **Default behavior:** Advanced filtering is **ON** by default - you pay 1 credit per result returned
* **Advanced filtering disabled:** Set `advanced_filtering=false` to use standard search for 5 credits (fixed cost regardless of results)
### Search Pricing Examples
* **Default search** with `limit=30` returning 20 results after AI filtering: **20 credits** (1 credit per result)
* **Standard search** with `advanced_filtering=false` and `limit=30`: **5 credits** (fixed cost regardless of results)
## Deep Research Pricing
| Endpoint | Description | Cost per Request |
| ---------------------------- | ------------------------------------ | ------------------- |
| **Initiate Deep Research** | Start comprehensive profile research | 1 credit per result |
| **Get Deep Research Status** | Check status of research jobs | Free |
| **Cancel Deep Research** | Cancel running research jobs | Free |
| **Continue Deep Research** | Expand existing research | 1 credit per result |
## Enrichment API Pricing
| Endpoint | Description | Cost per Request |
| ------------------------------ | -------------------------------------- | ---------------------------------------------------- |
| **Get Contact Information** | Find email/phone for LinkedIn profiles | 4 credits (email) / 10 credits (phone)\* |
| **Scrape LinkedIn Profile** | Extract detailed profile data | 2 credits |
| **Get LinkedIn Profile** | Retrieve profile from database | 1 credit |
| **Get Post Reactions** | Analyze LinkedIn post engagement | 1 credit |
| **Bulk Contact Enrichment** | Process multiple profiles | 4 credits (email) / 10 credits (phone) per success\* |
| **Get Bulk Enrichment Status** | Check bulk job status | Free |
\*Requires purchased credits (not available on free trial)
### Contact Information Pricing Details
* **Default mode:** Returns all available contact info for 4 credits
* **Email enrichment only:** 4 credits if email is found, 0 credits if not found
* **Phone enrichment only:** 10 credits if phone is found, 0 credits if not found
* **Both email & phone enrichment:** 4 credits for email + 10 credits for phone (only charged for what's actually found)
* If both requested but only email found: 4 credits
* If both requested but only phone found: 10 credits
* If both requested and both found: 14 credits
## Important Notes
* **Usage-based pricing** - You only pay for successful API calls
* Each successful API call consumes credits based on the endpoint
* Failed requests due to server errors (5xx) are not charged
* Cached responses (when applicable) consume the same credits as fresh data
* Rate limits apply to all endpoints to ensure optimal performance
## Need Custom Pricing?
For custom pricing or enterprise needs, please [contact our sales team](https://cal.com/team/clado/support).
# Rate Limits
Source: https://docs.clado.ai/api-reference/rate-limits
Understanding Clado API rate limits and usage guidelines
## Endpoint-Specific Rate Limits
Each endpoint has specific rate limits based on your tier (requests per minute):
| Endpoint | Free | >\$0 paid | \$50 paid | \$250 paid |
| --------------------------- | ---- | --------- | --------- | ---------- |
| **Search People** | 20 | 20 | 200 | 400 |
| **Get Contact Information** | 0 | 5 | 60 | 120 |
| **Scrape LinkedIn Profile** | 15 | 15 | 150 | 300 |
| **Get LinkedIn Profile** | 20 | 20 | 200 | 400 |
| **Get Post Reactions** | 10 | 10 | 100 | 200 |
| **Initiate Deep Research** | 5 | 5 | 50 | 100 |
## Handling Rate Limits
When you exceed the rate limit, the API returns a `429 Too Many Requests` status code. The response includes:
```json theme={null}
{
"error": "Rate limit exceeded",
"retry_after": 60
}
```
### Best Practices
1. **Implement exponential backoff** - When receiving a 429 response, wait before retrying
2. **Monitor rate limit headers** - Track your usage to avoid hitting limits
3. **Spread requests over time** - Avoid bursts/concurrent requests
4. **Cache responses** - Store frequently accessed data locally when possible
## Custom Rate Limits
Enterprise customers can request custom rate limits tailored to their needs. Contact our [sales team](https://cal.com/team/clado/support) to discuss custom limits.
## Questions?
If you have questions about rate limits or need higher limits, please [contact support](mailto:founders@clado.ai).