Run research with SSE streaming
curl --request POST \
--url https://agent.tinyfish.ai/v1/automation/run-research \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"query": "Compare long-duration energy storage approaches",
"mode": "standard",
"stream": true,
"output_language": "ja",
"browser_enabled": true,
"weak_sources_enabled": true,
"domain_type": "news",
"after_date": "2026-01-01",
"before_date": "2026-06-30",
"recency_minutes": 1440,
"prior_run_id": "<string>",
"session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://agent.tinyfish.ai/v1/automation/run-research"
payload = {
"query": "Compare long-duration energy storage approaches",
"mode": "standard",
"stream": True,
"output_language": "ja",
"browser_enabled": True,
"weak_sources_enabled": True,
"domain_type": "news",
"after_date": "2026-01-01",
"before_date": "2026-06-30",
"recency_minutes": 1440,
"prior_run_id": "<string>",
"session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'Compare long-duration energy storage approaches',
mode: 'standard',
stream: true,
output_language: 'ja',
browser_enabled: true,
weak_sources_enabled: true,
domain_type: 'news',
after_date: '2026-01-01',
before_date: '2026-06-30',
recency_minutes: 1440,
prior_run_id: '<string>',
session_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://agent.tinyfish.ai/v1/automation/run-research', 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://agent.tinyfish.ai/v1/automation/run-research",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'Compare long-duration energy storage approaches',
'mode' => 'standard',
'stream' => true,
'output_language' => 'ja',
'browser_enabled' => true,
'weak_sources_enabled' => true,
'domain_type' => 'news',
'after_date' => '2026-01-01',
'before_date' => '2026-06-30',
'recency_minutes' => 1440,
'prior_run_id' => '<string>',
'session_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agent.tinyfish.ai/v1/automation/run-research"
payload := strings.NewReader("{\n \"query\": \"Compare long-duration energy storage approaches\",\n \"mode\": \"standard\",\n \"stream\": true,\n \"output_language\": \"ja\",\n \"browser_enabled\": true,\n \"weak_sources_enabled\": true,\n \"domain_type\": \"news\",\n \"after_date\": \"2026-01-01\",\n \"before_date\": \"2026-06-30\",\n \"recency_minutes\": 1440,\n \"prior_run_id\": \"<string>\",\n \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agent.tinyfish.ai/v1/automation/run-research")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"Compare long-duration energy storage approaches\",\n \"mode\": \"standard\",\n \"stream\": true,\n \"output_language\": \"ja\",\n \"browser_enabled\": true,\n \"weak_sources_enabled\": true,\n \"domain_type\": \"news\",\n \"after_date\": \"2026-01-01\",\n \"before_date\": \"2026-06-30\",\n \"recency_minutes\": 1440,\n \"prior_run_id\": \"<string>\",\n \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agent.tinyfish.ai/v1/automation/run-research")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"Compare long-duration energy storage approaches\",\n \"mode\": \"standard\",\n \"stream\": true,\n \"output_language\": \"ja\",\n \"browser_enabled\": true,\n \"weak_sources_enabled\": true,\n \"domain_type\": \"news\",\n \"after_date\": \"2026-01-01\",\n \"before_date\": \"2026-06-30\",\n \"recency_minutes\": 1440,\n \"prior_run_id\": \"<string>\",\n \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body"data: {\"event\":\"created\",\"research_run_id\":\"019...\"}\n\ndata: {\"event\":\"plan_updated\",\"iteration\":1}\n\ndata: {\"event\":\"final_result\",\"result\":\"...\",\"citations\":[]}\n\ndata: {\"event\":\"done\"}"{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}API Reference
Run research with SSE streaming
Search, evaluate sources, and synthesize a cited report from a natural-language query. Accepted requests always return a Server-Sent Events stream, including when stream is false.
POST
/
v1
/
automation
/
run-research
Run research with SSE streaming
curl --request POST \
--url https://agent.tinyfish.ai/v1/automation/run-research \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"query": "Compare long-duration energy storage approaches",
"mode": "standard",
"stream": true,
"output_language": "ja",
"browser_enabled": true,
"weak_sources_enabled": true,
"domain_type": "news",
"after_date": "2026-01-01",
"before_date": "2026-06-30",
"recency_minutes": 1440,
"prior_run_id": "<string>",
"session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'import requests
url = "https://agent.tinyfish.ai/v1/automation/run-research"
payload = {
"query": "Compare long-duration energy storage approaches",
"mode": "standard",
"stream": True,
"output_language": "ja",
"browser_enabled": True,
"weak_sources_enabled": True,
"domain_type": "news",
"after_date": "2026-01-01",
"before_date": "2026-06-30",
"recency_minutes": 1440,
"prior_run_id": "<string>",
"session_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: 'Compare long-duration energy storage approaches',
mode: 'standard',
stream: true,
output_language: 'ja',
browser_enabled: true,
weak_sources_enabled: true,
domain_type: 'news',
after_date: '2026-01-01',
before_date: '2026-06-30',
recency_minutes: 1440,
prior_run_id: '<string>',
session_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a'
})
};
fetch('https://agent.tinyfish.ai/v1/automation/run-research', 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://agent.tinyfish.ai/v1/automation/run-research",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'Compare long-duration energy storage approaches',
'mode' => 'standard',
'stream' => true,
'output_language' => 'ja',
'browser_enabled' => true,
'weak_sources_enabled' => true,
'domain_type' => 'news',
'after_date' => '2026-01-01',
'before_date' => '2026-06-30',
'recency_minutes' => 1440,
'prior_run_id' => '<string>',
'session_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://agent.tinyfish.ai/v1/automation/run-research"
payload := strings.NewReader("{\n \"query\": \"Compare long-duration energy storage approaches\",\n \"mode\": \"standard\",\n \"stream\": true,\n \"output_language\": \"ja\",\n \"browser_enabled\": true,\n \"weak_sources_enabled\": true,\n \"domain_type\": \"news\",\n \"after_date\": \"2026-01-01\",\n \"before_date\": \"2026-06-30\",\n \"recency_minutes\": 1440,\n \"prior_run_id\": \"<string>\",\n \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://agent.tinyfish.ai/v1/automation/run-research")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"Compare long-duration energy storage approaches\",\n \"mode\": \"standard\",\n \"stream\": true,\n \"output_language\": \"ja\",\n \"browser_enabled\": true,\n \"weak_sources_enabled\": true,\n \"domain_type\": \"news\",\n \"after_date\": \"2026-01-01\",\n \"before_date\": \"2026-06-30\",\n \"recency_minutes\": 1440,\n \"prior_run_id\": \"<string>\",\n \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://agent.tinyfish.ai/v1/automation/run-research")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"Compare long-duration energy storage approaches\",\n \"mode\": \"standard\",\n \"stream\": true,\n \"output_language\": \"ja\",\n \"browser_enabled\": true,\n \"weak_sources_enabled\": true,\n \"domain_type\": \"news\",\n \"after_date\": \"2026-01-01\",\n \"before_date\": \"2026-06-30\",\n \"recency_minutes\": 1440,\n \"prior_run_id\": \"<string>\",\n \"session_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}"
response = http.request(request)
puts response.read_body"data: {\"event\":\"created\",\"research_run_id\":\"019...\"}\n\ndata: {\"event\":\"plan_updated\",\"iteration\":1}\n\ndata: {\"event\":\"final_result\",\"result\":\"...\",\"citations\":[]}\n\ndata: {\"event\":\"done\"}"{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}{
"error": {
"code": "INVALID_INPUT",
"message": "Field \"url\" is required and must be a string",
"details": "<unknown>"
},
"request_id": "8f9dba20-e37b-4749-a919-2269e28b4a2c"
}Authorizations
API key for authentication. Get your key from the API Keys page.
Body
application/json
Research parameters
Research question
Required string length:
1 - 2000Example:
"Compare long-duration energy storage approaches"
Depth of research. Omitted selects deep; legacy auto selects standard. Max enables browser agents.
Available options:
auto, standard, deep, max Example:
"standard"
Emit report text through synthesis_delta events as it is written
BCP 47 language tag for the report
Example:
"ja"
Max mode only. Defaults to true in Max mode; set false for search and static fetches only.
Allow relevant social and community sources
Source pool to research over
Available options:
web, news, research_paper Example:
"news"
Include results on or after this date (YYYY-MM-DD)
Example:
"2026-01-01"
Include results on or before this date (YYYY-MM-DD)
Example:
"2026-06-30"
Include results from the last 1-5,256,000 minutes. Not combinable with date filters.
Required range:
1 <= x <= 5256000Example:
1440
Domain preferences. Each list accepts at most 150 entries.
Show child attributes
Show child attributes
Seed this run with a completed report and its evidence
Continue a standard-mode session. Mutually exclusive with prior_run_id.
Response
Server-Sent Events stream. Save the run ID from created and stop reading after done. See the Research API reference for the full event catalog.
The response is of type string.
Was this page helpful?