Get Deep Research Status

curl --request GET \
  --url https://search.clado.ai/api/search/deep_research/{job_id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://search.clado.ai/api/search/deep_research/{job_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://search.clado.ai/api/search/deep_research/{job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://search.clado.ai/api/search/deep_research/{job_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://search.clado.ai/api/search/deep_research/{job_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
        }
      ]
    }
  ]
}

{
  "detail": "Page number must be >= 1"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

GET

api

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>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://search.clado.ai/api/search/deep_research/{job_id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://search.clado.ai/api/search/deep_research/{job_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://search.clado.ai/api/search/deep_research/{job_id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://search.clado.ai/api/search/deep_research/{job_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "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
        }
      ]
    }
  ]
}

{
  "detail": "Page number must be >= 1"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

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

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)

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

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

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)

Show child attributes

pagination

object

Pagination information (only present when page parameter is provided)

Show child attributes

error

string

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

Getting Started

Search API

Deep Research

Enrichment API

Platform API

Get Deep Research Status

Get Deep Research Status

Path Parameters

Query Parameters

Response (Pending)

Status Values

Error Responses

General Notes

Authorizations

Path Parameters

Query Parameters

Response

​Get Deep Research Status

​Without Pagination (All Results)

​With Pagination

​Path Parameters

​Query Parameters

​Response (Pending)

​Response (Completed - Without Pagination)

​Response (Completed - With Pagination)

​Status Values

​Error Responses

​Pagination Notes

​General Notes

Authorizations

Path Parameters

Query Parameters

Response

Get Deep Research Status

Without Pagination (All Results)

With Pagination

Path Parameters

Query Parameters

Response (Pending)

Response (Completed - Without Pagination)

Response (Completed - With Pagination)

Status Values

Error Responses

Pagination Notes

General Notes