curl --request POST \
--url https://api.browser.tinyfish.ai/ \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"url": "https://www.tinyfish.ai",
"timeout_seconds": 300,
"proxy_config": {
"enabled": true,
"type": "tinyfish",
"country_code": "US",
"url": "http://proxy.example.com:8080",
"username": "<string>",
"password": "<string>"
}
}
'import requests
url = "https://api.browser.tinyfish.ai/"
payload = {
"url": "https://www.tinyfish.ai",
"timeout_seconds": 300,
"proxy_config": {
"enabled": True,
"type": "tinyfish",
"country_code": "US",
"url": "http://proxy.example.com:8080",
"username": "<string>",
"password": "<string>"
}
}
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({
url: 'https://www.tinyfish.ai',
timeout_seconds: 300,
proxy_config: {
enabled: true,
type: 'tinyfish',
country_code: 'US',
url: 'http://proxy.example.com:8080',
username: '<string>',
password: '<string>'
}
})
};
fetch('https://api.browser.tinyfish.ai/', 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://api.browser.tinyfish.ai/",
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([
'url' => 'https://www.tinyfish.ai',
'timeout_seconds' => 300,
'proxy_config' => [
'enabled' => true,
'type' => 'tinyfish',
'country_code' => 'US',
'url' => 'http://proxy.example.com:8080',
'username' => '<string>',
'password' => '<string>'
]
]),
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://api.browser.tinyfish.ai/"
payload := strings.NewReader("{\n \"url\": \"https://www.tinyfish.ai\",\n \"timeout_seconds\": 300,\n \"proxy_config\": {\n \"enabled\": true,\n \"type\": \"tinyfish\",\n \"country_code\": \"US\",\n \"url\": \"http://proxy.example.com:8080\",\n \"username\": \"<string>\",\n \"password\": \"<string>\"\n }\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://api.browser.tinyfish.ai/")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://www.tinyfish.ai\",\n \"timeout_seconds\": 300,\n \"proxy_config\": {\n \"enabled\": true,\n \"type\": \"tinyfish\",\n \"country_code\": \"US\",\n \"url\": \"http://proxy.example.com:8080\",\n \"username\": \"<string>\",\n \"password\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.browser.tinyfish.ai/")
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 \"url\": \"https://www.tinyfish.ai\",\n \"timeout_seconds\": 300,\n \"proxy_config\": {\n \"enabled\": true,\n \"type\": \"tinyfish\",\n \"country_code\": \"US\",\n \"url\": \"http://proxy.example.com:8080\",\n \"username\": \"<string>\",\n \"password\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"session_id": "tf-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"cdp_url": "wss://tetra-abc123.cluster.unikraft.cloud/cdp",
"base_url": "https://tetra-abc123.cluster.unikraft.cloud"
}{
"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"
}Create a remote browser session
Creates a remote tf-browser session and returns CDP connection details. Connect to the browser via CDP WebSocket at cdp_url.
By default the session egresses through the TinyFish residential proxy in the US, pinned to one exit IP for the life of the session. Use proxy_config to pick another country (country_code, any ISO 3166-1 alpha-2), bring your own proxy (type: "custom"), or disable the proxy (enabled: false).
Use timeout_seconds to set a custom inactivity timeout (5–86400 seconds). If omitted, null, or greater than your plan maximum, the plan maximum is used (15 min on free tier, 60 min on paid).
curl --request POST \
--url https://api.browser.tinyfish.ai/ \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"url": "https://www.tinyfish.ai",
"timeout_seconds": 300,
"proxy_config": {
"enabled": true,
"type": "tinyfish",
"country_code": "US",
"url": "http://proxy.example.com:8080",
"username": "<string>",
"password": "<string>"
}
}
'import requests
url = "https://api.browser.tinyfish.ai/"
payload = {
"url": "https://www.tinyfish.ai",
"timeout_seconds": 300,
"proxy_config": {
"enabled": True,
"type": "tinyfish",
"country_code": "US",
"url": "http://proxy.example.com:8080",
"username": "<string>",
"password": "<string>"
}
}
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({
url: 'https://www.tinyfish.ai',
timeout_seconds: 300,
proxy_config: {
enabled: true,
type: 'tinyfish',
country_code: 'US',
url: 'http://proxy.example.com:8080',
username: '<string>',
password: '<string>'
}
})
};
fetch('https://api.browser.tinyfish.ai/', 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://api.browser.tinyfish.ai/",
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([
'url' => 'https://www.tinyfish.ai',
'timeout_seconds' => 300,
'proxy_config' => [
'enabled' => true,
'type' => 'tinyfish',
'country_code' => 'US',
'url' => 'http://proxy.example.com:8080',
'username' => '<string>',
'password' => '<string>'
]
]),
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://api.browser.tinyfish.ai/"
payload := strings.NewReader("{\n \"url\": \"https://www.tinyfish.ai\",\n \"timeout_seconds\": 300,\n \"proxy_config\": {\n \"enabled\": true,\n \"type\": \"tinyfish\",\n \"country_code\": \"US\",\n \"url\": \"http://proxy.example.com:8080\",\n \"username\": \"<string>\",\n \"password\": \"<string>\"\n }\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://api.browser.tinyfish.ai/")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://www.tinyfish.ai\",\n \"timeout_seconds\": 300,\n \"proxy_config\": {\n \"enabled\": true,\n \"type\": \"tinyfish\",\n \"country_code\": \"US\",\n \"url\": \"http://proxy.example.com:8080\",\n \"username\": \"<string>\",\n \"password\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.browser.tinyfish.ai/")
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 \"url\": \"https://www.tinyfish.ai\",\n \"timeout_seconds\": 300,\n \"proxy_config\": {\n \"enabled\": true,\n \"type\": \"tinyfish\",\n \"country_code\": \"US\",\n \"url\": \"http://proxy.example.com:8080\",\n \"username\": \"<string>\",\n \"password\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"session_id": "tf-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"cdp_url": "wss://tetra-abc123.cluster.unikraft.cloud/cdp",
"base_url": "https://tetra-abc123.cluster.unikraft.cloud"
}{
"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
Browser session parameters
Browser session creation parameters
Target URL the browser session will navigate to on startup. Bare domains (e.g. tinyfish.ai) are automatically prefixed with https://. If omitted, the browser starts at about:blank.
"https://www.tinyfish.ai"
Inactivity timeout in seconds (5–86400). If omitted, null, or greater than your plan maximum, the plan maximum is used.
5 <= x <= 86400300
Proxy for the session. Omit to use the TinyFish proxy in the US.
Show child attributes
Show child attributes
Response
Browser session created successfully.
Browser session created successfully. Connect to the browser via cdp_url.
Unique identifier for this browser session.
1"br-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
WebSocket URL for browser connection. Pass this to Playwright's connect_over_cdp or any WebSocket-based CDP client.
"wss://browser.example.tinyfish.io/session/cdp"
HTTPS base URL for the session. Use to access session endpoints such as /pages.
"https://browser.example.tinyfish.io/session"
Was this page helpful?