Get Research Task Status

Retrieve the status and results of a research task using its request ID.

GET /research/{request_id}

Python SDK

Python

from tavily import TavilyClient

tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
response = tavily_client.get_research("123e4567-e89b-12d3-a456-426614174111")

print(response)

const { tavily } = require("@tavily/core");

const tvly = tavily({ apiKey: "tvly-YOUR_API_KEY" });
const response = await tvly.get_research("123e4567-e89b-12d3-a456-426614174111");

console.log(response);

curl --request GET \
  --url https://api.tavily.com/research/{request_id} \
  --header 'Authorization: Bearer <token>'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tavily.com/research/{request_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://api.tavily.com/research/{request_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))

}

HttpResponse<String> response = Unirest.get("https://api.tavily.com/research/{request_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.tavily.com/research/{request_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

200

{
  "request_id": "123e4567-e89b-12d3-a456-426614174111",
  "created_at": "2025-01-15T10:30:00Z",
  "status": "completed",
  "content": "Research Report: Latest Developments in AI\n\n## Executive Summary\n\nArtificial Intelligence has seen significant advancements in recent months, with major breakthroughs in large language models, multimodal AI systems, and real-world applications...",
  "sources": [
    {
      "title": "Latest AI Developments",
      "url": "https://example.com/ai-news",
      "favicon": "https://example.com/favicon.ico"
    },
    {
      "title": "AI Research Breakthroughs",
      "url": "https://example.com/ai-research",
      "favicon": "https://example.com/favicon.ico"
    }
  ],
  "response_time": 1.23
}

{
  "request_id": "123e4567-e89b-12d3-a456-426614174111",
  "status": "in_progress",
  "response_time": 1.23
}

{
  "detail": {
    "error": "Unauthorized: missing or invalid API key."
  }
}

{
  "detail": {
    "error": "Research task not found"
  }
}

{
  "detail": {
    "error": "Error getting research status"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header in the form Bearer , where is your Tavily API key (e.g., Bearer tvly-YOUR_API_KEY).

Path Parameters

request_id · string · required

The unique identifier of the research task.

Response

200

application/json

Research task is completed or failed.

Completed

Failed

request_id · string · required

The unique identifier of the research task.

Example:

"123e4567-e89b-12d3-a456-426614174111"

created_at · string · required

Timestamp when the research task was created.

Example:

"2025-01-15T10:30:00Z"

status · enum<string> · required

The current status of the research task.

Available options: completed

content · string object · required

The research report content. Can be a string or a structured object if output_schema was provided.

sources · object[] · required

List of sources used in the research.

Show child attributes

response_time · integer · required

Time in seconds it took to complete the request.

Example:

1.23