Skip to main content
GET
/
api
/
search
/
deep_research
/
{job_id}
Get Deep Research Status
curl --request GET \
  --url https://search.clado.ai/api/search/deep_research/{job_id} \
  --header 'Authorization: Bearer <token>'
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "message": "Deep research completed successfully",
  "total_results": 47,
  "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,
        "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"
        }
      ],
      "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": 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
        }
      ]
    }
  ]
}
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 for migration details.

​
Get Deep Research Status

​
Without Pagination (All Results)

curl -X GET https://search.clado.ai/api/search/deep_research/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
With Pagination

# 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

ParameterTypeRequiredDescription
job_idstringYesThe job ID returned from initiating deep research

​
Query Parameters

ParameterTypeRequiredDescription
pageintegerNoPage number (1-indexed). If not provided, returns all results without pagination
page_sizeintegerNoNumber of results per page (1-100, default: 25). Only applies when page parameter is provided
legacybooleanNoDEPRECATED: Return results in legacy format (default: true). Will be removed November 1st, 2025

​
Response (Pending)

{
  "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: 
{
  "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: 
{
  "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

StatusDescription
pendingJob is queued and waiting to start
searchingJob is actively searching for profiles
processingJob is validating and processing found profiles
completedJob finished successfully with results
errorJob encountered an error
cancelledJob was cancelled by user

​
Error Responses

Status CodeDescription
400Bad Request - Invalid pagination parameters (e.g., page < 1 or page_size out of range)
401Unauthorized - API key missing or invalid
403Forbidden - Not authorized to access this job
404Not 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

Authorizations

​
Authorization
string
header
required

API key authentication. Keys start with 'lk_'.

Path Parameters

​
job_id
string
required

Unique identifier for the deep research job (returned from POST /api/search/deep_research)

Query Parameters

​
page
integer

Page number (1-indexed). If not provided, returns all results without pagination

Required range: x >= 1
​
page_size
integer
default:25

Number of results per page when pagination is used. Only applies when page parameter is provided

Required range: 1 <= x <= 100
​
legacy
boolean
default:true

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

Response

Job status and results (paginated if page parameter is provided)

​
job_id
string

Unique job identifier

​
status
string

Job status (pending, searching, processing, completed, error, cancelled)

​
message
string

Status message

​
created_at
number

Unix timestamp of when the job was created

​
opensearch_results
integer

Number of results found in OpenSearch

​
final_results_count
integer

Total number of validated profiles across all pages

​
total_filtered
integer

Number of filtered results

​
search_chunk_done
integer

Number of search chunks processed

​
search_chunk_total
integer

Total number of search chunks

​
results
object[]

Array of user profiles (paginated if page parameter is provided)

​
pagination
object

Pagination information (only present when page parameter is provided)

​
error
string

Error details (only present when status is 'error')