Agent
cancelRun
agent.cancelRun
Cancel a pending or running run
Risk: write
await corsair.tinyfish.api.agent.cancelRun({ runId: 'run_...' });
| Name | Type | Required | Description |
|---|---|---|---|
runId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
run_id | string | Yes | — |
status | CANCELLED | COMPLETED | FAILED | Yes | — |
cancelled_at | string | null | Yes | — |
message | string | null | Yes | — |
cancelRuns
agent.cancelRuns
Cancel up to 100 runs in one request
Risk: write
await corsair.tinyfish.api.agent.cancelRuns({ run_ids: ['run_...'] });
| Name | Type | Required | Description |
|---|---|---|---|
run_ids | string[] | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
results | object[] | Yes | — |
not_found | string[] | null | Yes | — |
results full type
results full type
{
run_id: string,
status: CANCELLED | COMPLETED | FAILED,
cancelled_at: string | null,
message: string | null
}[]
getRun
agent.getRun
Get one run with its steps, screenshots and HTML artifacts
Risk: read
await corsair.tinyfish.api.agent.getRun({ runId: 'run_...', screenshots: 'url' });
| Name | Type | Required | Description |
|---|---|---|---|
runId | string | Yes | — |
screenshots | base64 | url | none | No | — |
html | url | none | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
run_id | string | Yes | — |
status | PENDING | RUNNING | COMPLETED | FAILED | CANCELLED | Yes | — |
goal | string | Yes | — |
created_at | string | Yes | — |
started_at | string | null | Yes | — |
finished_at | string | null | Yes | — |
num_of_steps | number | null | Yes | — |
result | Record<string, any> | null | Yes | — |
output_schema | Record<string, any> | null | Yes | — |
profile_attached | boolean | Yes | — |
profile_id | string | null | Yes | — |
error | object | null | Yes | — |
profile_hint | object | null | No | — |
streaming_url | string | null | Yes | — |
browser_config | object | null | Yes | — |
video_url | string | null | Yes | — |
steps | object[] | Yes | — |
error full type
error full type
{
code?: string | null,
message: string,
category: SYSTEM_FAILURE | AGENT_FAILURE | BILLING_FAILURE | UNKNOWN,
retry_after?: number | null,
help_url?: string | null,
help_message?: string | null,
profile_hint?: {
message: string,
setup_url: string,
reason: auth_wall | bot_challenge
} | null
} | null
profile_hint full type
profile_hint full type
{
message: string,
setup_url: string,
reason: auth_wall | bot_challenge
} | null
browser_config full type
browser_config full type
{
proxy_enabled: boolean | null,
proxy_country_code: string | null
} | null
steps full type
steps full type
{
id: string,
timestamp: string,
status: PENDING | RUNNING | COMPLETED | FAILED | CANCELLED,
action?: string | null,
screenshot?: string | null,
html?: string | null,
duration?: string | null
}[]
getRuns
agent.getRuns
Get up to 100 runs by ID in one request
Risk: read
await corsair.tinyfish.api.agent.getRuns({ run_ids: ['run_...'] });
| Name | Type | Required | Description |
|---|---|---|---|
run_ids | string[] | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
data | object[] | Yes | — |
not_found | string[] | null | Yes | — |
data full type
data full type
{
run_id: string,
status: PENDING | RUNNING | COMPLETED | FAILED | CANCELLED,
goal: string,
created_at: string,
started_at: string | null,
finished_at: string | null,
num_of_steps: number | null,
result: Record<string, any> | null,
output_schema: Record<string, any> | null,
profile_attached: boolean,
profile_id: string | null,
error: {
code?: string | null,
message: string,
category: SYSTEM_FAILURE | AGENT_FAILURE | BILLING_FAILURE | UNKNOWN,
retry_after?: number | null,
help_url?: string | null,
help_message?: string | null,
profile_hint?: {
message: string,
setup_url: string,
reason: auth_wall | bot_challenge
} | null
} | null,
profile_hint?: {
message: string,
setup_url: string,
reason: auth_wall | bot_challenge
} | null,
streaming_url: string | null,
browser_config: {
proxy_enabled: boolean | null,
proxy_country_code: string | null
} | null,
video_url: string | null,
steps: {
id: string,
timestamp: string,
status: PENDING | RUNNING | COMPLETED | FAILED | CANCELLED,
action?: string | null,
screenshot?: string | null,
html?: string | null,
duration?: string | null
}[]
}[]
getStepHtml
agent.getStepHtml
Get the full-page HTML snapshot captured at one step
Risk: read
await corsair.tinyfish.api.agent.getStepHtml({ runId: 'run_...', stepId: 'evt_...' });
| Name | Type | Required | Description |
|---|---|---|---|
runId | string | Yes | — |
stepId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
contentType | string | Yes | — |
html | string | Yes | — |
getStepScreenshot
agent.getStepScreenshot
Get the JPEG screenshot captured at one step of a run. On Corsair up to about 700 KB comes back inline as base64 and a larger image comes back as fileId, a Files id.
Risk: read
await corsair.tinyfish.api.agent.getStepScreenshot({ runId: 'run_...', stepId: 'evt_...' });
| Name | Type | Required | Description |
|---|---|---|---|
runId | string | Yes | — |
stepId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
contentType | string | Yes | — |
byteLength | number | Yes | Size of the file in bytes. |
filename | string | No | The file name, when known. |
contentOmitted | not_requested | over_limit | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
fileId | string | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read_text. |
base64 | string | No | The screenshot, base64-encoded. Missing when contentOmitted is set, or when a host kept a file too large to return inline (fileId). |
sizeBytes | number | Yes | — |
listRuns
agent.listRuns
List automation runs with status and date filters
Risk: read
await corsair.tinyfish.api.agent.listRuns({ status: 'RUNNING', limit: 20 });
| Name | Type | Required | Description |
|---|---|---|---|
status | PENDING | RUNNING | COMPLETED | FAILED | CANCELLED | No | — |
goal | string | No | — |
created_after | string | No | — |
created_before | string | No | — |
sort_direction | asc | desc | No | — |
cursor | string | No | — |
limit | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
data | object[] | Yes | — |
pagination | object | Yes | — |
data full type
data full type
{
run_id: string,
status: PENDING | RUNNING | COMPLETED | FAILED | CANCELLED,
goal: string,
created_at: string,
started_at: string | null,
finished_at: string | null,
num_of_steps: number | null,
result: Record<string, any> | null,
output_schema: Record<string, any> | null,
profile_attached: boolean,
profile_id: string | null,
error: {
code?: string | null,
message: string,
category: SYSTEM_FAILURE | AGENT_FAILURE | BILLING_FAILURE | UNKNOWN,
retry_after?: number | null,
help_url?: string | null,
help_message?: string | null,
profile_hint?: {
message: string,
setup_url: string,
reason: auth_wall | bot_challenge
} | null
} | null,
profile_hint?: {
message: string,
setup_url: string,
reason: auth_wall | bot_challenge
} | null,
streaming_url: string | null,
browser_config: {
proxy_enabled: boolean | null,
proxy_country_code: string | null
} | null
}[]
pagination full type
pagination full type
{
total: number,
next_cursor: string | null,
has_more: boolean
}
run
agent.run
Automate a goal on a live website and wait for the result (billed per step)
Risk: write
await corsair.tinyfish.api.agent.run({ url: 'https://example.com', goal: 'Extract the page title' });
| Name | Type | Required | Description |
|---|---|---|---|
url | string | Yes | — |
goal | string | Yes | — |
browser_profile | lite | stealth | No | — |
api_integration | string | No | — |
agent_config | object | No | — |
capture_config | object | No | — |
webhook_url | string | No | — |
use_vault | boolean | No | — |
use_profile | boolean | No | — |
profile_id | string | No | — |
credential_item_ids | string[] | No | — |
proxy_config | object | No | — |
output_schema | Record<string, any> | No | — |
agent_config full type
agent_config full type
{
mode?: default | strict,
cursor_style?: fish | standard | green-pointer,
max_steps?: number,
max_duration_seconds?: number
}
capture_config full type
capture_config full type
{
elements?: boolean,
snapshots?: boolean,
screenshots?: boolean,
recording?: boolean,
html?: boolean
}
proxy_config full type
proxy_config full type
{
enabled: boolean,
country_code?: US | GB | CA | DE | FR | JP | AU | null
}
| Name | Type | Required | Description |
|---|---|---|---|
run_id | string | null | Yes | — |
status | COMPLETED | FAILED | Yes | — |
started_at | string | null | Yes | — |
finished_at | string | null | Yes | — |
num_of_steps | number | null | Yes | — |
result | Record<string, any> | null | Yes | — |
error | object | null | Yes | — |
profile_hint | object | null | No | — |
error full type
error full type
{
code?: string | null,
message: string,
category: SYSTEM_FAILURE | AGENT_FAILURE | BILLING_FAILURE | UNKNOWN,
retry_after?: number | null,
help_url?: string | null,
help_message?: string | null,
profile_hint?: {
message: string,
setup_url: string,
reason: auth_wall | bot_challenge
} | null
} | null
profile_hint full type
profile_hint full type
{
message: string,
setup_url: string,
reason: auth_wall | bot_challenge
} | null
runAsync
agent.runAsync
Queue a web automation run and return its run ID (billed per step)
Risk: write
await corsair.tinyfish.api.agent.runAsync({ url: 'https://example.com', goal: 'Extract the page title', webhook_url: 'https://hooks.example.com/tinyfish' });
| Name | Type | Required | Description |
|---|---|---|---|
url | string | Yes | — |
goal | string | Yes | — |
browser_profile | lite | stealth | No | — |
api_integration | string | No | — |
agent_config | object | No | — |
capture_config | object | No | — |
webhook_url | string | No | — |
use_vault | boolean | No | — |
use_profile | boolean | No | — |
profile_id | string | No | — |
credential_item_ids | string[] | No | — |
proxy_config | object | No | — |
output_schema | Record<string, any> | No | — |
agent_config full type
agent_config full type
{
mode?: default | strict,
cursor_style?: fish | standard | green-pointer,
max_steps?: number,
max_duration_seconds?: number
}
capture_config full type
capture_config full type
{
elements?: boolean,
snapshots?: boolean,
screenshots?: boolean,
recording?: boolean,
html?: boolean
}
proxy_config full type
proxy_config full type
{
enabled: boolean,
country_code?: US | GB | CA | DE | FR | JP | AU | null
}
| Name | Type | Required | Description |
|---|---|---|---|
run_id | string | null | Yes | — |
error | object | null | Yes | — |
error full type
error full type
{
code: string,
message: string
} | null
runBatch
agent.runBatch
Queue up to 100 automation runs in a single atomic request (billed per step)
Risk: write
await corsair.tinyfish.api.agent.runBatch({ runs: [{ url: 'https://example.com', goal: 'Extract the page title' }] });
| Name | Type | Required | Description |
|---|---|---|---|
runs | object[] | Yes | — |
profile_id | string | No | — |
output_schema | Record<string, any> | No | — |
runs full type
runs full type
{
url: string,
goal: string,
browser_profile?: lite | stealth,
api_integration?: string,
agent_config?: {
mode?: default | strict,
cursor_style?: fish | standard | green-pointer,
max_steps?: number,
max_duration_seconds?: number
},
capture_config?: {
elements?: boolean,
snapshots?: boolean,
screenshots?: boolean,
recording?: boolean,
html?: boolean
},
webhook_url?: string,
use_vault?: boolean,
credential_item_ids?: string[],
proxy_config?: {
enabled: boolean,
country_code?: US | GB | CA | DE | FR | JP | AU | null
},
output_schema?: Record<string, any>
}[]
| Name | Type | Required | Description |
|---|---|---|---|
run_ids | string[] | null | Yes | — |
error | object | null | Yes | — |
error full type
error full type
{
code: string,
message: string,
details?: any | null
} | null
Browser
createSession
browser.createSession
Start a cloud browser session and return its CDP connection URL
Risk: write
await corsair.tinyfish.api.browser.createSession({ url: 'https://example.com', timeout_seconds: 600 });
| Name | Type | Required | Description |
|---|---|---|---|
url | string | No | — |
timeout_seconds | number | null | No | — |
proxy_config | object | No | — |
proxy_config full type
proxy_config full type
{
enabled?: boolean,
type?: tinyfish | custom,
country_code?: string,
url?: string,
username?: string,
password?: string
}
| Name | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | — |
cdp_url | string | Yes | — |
base_url | string | Yes | — |
terminateSession
browser.terminateSession
Terminate a cloud browser session
Risk: write
await corsair.tinyfish.api.browser.terminateSession({ sessionId: 'sess_...' });
| Name | Type | Required | Description |
|---|---|---|---|
sessionId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
terminated | true | Yes | — |
session_id | string | Yes | — |
usage
browser.usage
List browser session usage and byte volumes
Risk: read
await corsair.tinyfish.api.browser.usage({ status: 'ended', limit: 50 });
| Name | Type | Required | Description |
|---|---|---|---|
session_id | string | No | — |
start_after | string | No | — |
end_before | string | No | — |
status | running | ended | No | — |
limit | number | No | — |
page | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
items | object[] | Yes | — |
total | number | Yes | — |
limit | number | Yes | — |
page | number | Yes | — |
total_pages | number | Yes | — |
has_more | boolean | Yes | — |
items full type
items full type
{
session_id: string,
user_id: string,
sub_user_id: string | null,
mode: light | stealth | tf-browser,
start_time: string,
end_time: string | null,
duration_ms: number | null,
proxy_trg_rx_bytes: number | null,
proxy_trg_tx_bytes: number | null,
status: running | ended | created,
created_at: string,
updated_at: string
}[]
Fetch
fetch
fetch.fetch
Fetch up to 10 URLs as markdown, HTML or JSON with cache revalidation
Risk: read
await corsair.tinyfish.api.fetch.fetch({ urls: ['https://example.com'], format: 'markdown', links: true });
| Name | Type | Required | Description |
|---|---|---|---|
urls | string[] | Yes | — |
purpose | string | No | — |
format | markdown | html | json | No | — |
links | boolean | No | — |
image_links | boolean | No | — |
iframe_links | boolean | No | — |
page_metadata | boolean | No | — |
ttl | number | No | — |
per_url_timeout_ms | number | No | — |
if_none_match | string | No | — |
if_modified_since | string | No | — |
include_etag_and_last_modified | boolean | No | — |
include_selectors | string[] | No | — |
exclude_selectors | string[] | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
results | object[] | Yes | — |
errors | object[] | Yes | — |
request_id | string | No | — |
results full type
results full type
{
url: string,
final_url: string | null,
title: string | null,
description: string | null,
language: string | null,
format: markdown | html | json,
text: string | Record<string, any> | null,
author: string | null,
published_date: string | null,
links?: string[],
image_links?: string[],
iframe_links?: string[],
page_metadata?: Record<string, any>,
latency_ms: number | null,
not_modified?: boolean,
etag?: string,
last_modified?: string,
unmatched_selectors?: string[]
}[]
errors full type
errors full type
{
url: string,
error: string,
status?: number,
unmatched_selectors?: string[],
candidate_selectors?: string[]
}[]
usage
fetch.usage
List recent fetch requests and their outcomes
Risk: read
await corsair.tinyfish.api.fetch.usage({ status: 'completed' });
| Name | Type | Required | Description |
|---|---|---|---|
start_after | string | No | — |
end_before | string | No | — |
status | completed | failed | No | — |
limit | number | No | — |
page | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
items | object[] | Yes | — |
total | number | Yes | — |
limit | number | Yes | — |
page | number | Yes | — |
total_pages | number | Yes | — |
has_more | boolean | Yes | — |
items full type
items full type
{
id: string,
url: string,
final_url: string,
title: string | null,
description: string | null,
language: string | null,
author: string | null,
published_date: string | null,
format: markdown | html | json,
status: completed | failed,
request_origin: string,
request_id: string | null,
text_length: number | null,
links_count: number,
image_links_count: number,
latency_ms: number | null,
not_modified?: boolean,
etag?: string,
last_modified?: string,
created_at: string,
error: string | null
}[]
Profiles
create
profiles.create
Create a Browser Context Profile
Risk: write
await corsair.tinyfish.api.profiles.create({ name: 'Work', set_as_default: true });
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | — |
set_as_default | boolean | No | — |
proxy_country_code | US | GB | CA | AU | DE | FR | IT | ES | NL | JP | SG | BR | IN | null | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
name | string | Yes | — |
proxy_country_code | US | GB | CA | AU | DE | FR | IT | ES | NL | JP | SG | BR | IN | null | No | — |
is_default | boolean | No | — |
fingerprint_seed | string | No | — |
domain_count | number | No | — |
created_at | string | Yes | — |
updated_at | string | No | — |
delete
profiles.delete
Delete a profile and all of its saved cookies and sessions
Risk: destructive · Irreversible
await corsair.tinyfish.api.profiles.delete({ profileId: 'p_...' });
| Name | Type | Required | Description |
|---|---|---|---|
profileId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
deleted | boolean | Yes | — |
get
profiles.get
Get a profile with the domains it has saved state for
Risk: read
await corsair.tinyfish.api.profiles.get({ profileId: 'p_...' });
| Name | Type | Required | Description |
|---|---|---|---|
profileId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
name | string | Yes | — |
proxy_country_code | US | GB | CA | AU | DE | FR | IT | ES | NL | JP | SG | BR | IN | null | No | — |
is_default | boolean | No | — |
fingerprint_seed | string | No | — |
domain_count | number | No | — |
created_at | string | Yes | — |
updated_at | string | No | — |
domains | object[] | Yes | — |
domains full type
domains full type
{
domain: string,
cookie_count: number,
local_storage_origin_count: number,
last_accessed_at: string,
last_written_at: string,
last_written_by_run_id: string
}[]
list
profiles.list
List Browser Context Profiles
Risk: read
await corsair.tinyfish.api.profiles.list({});
| Name | Type | Required | Description |
|---|---|---|---|
profiles | object[] | Yes | — |
profiles full type
profiles full type
{
id: string,
name: string,
proxy_country_code?: US | GB | CA | AU | DE | FR | IT | ES | NL | JP | SG | BR | IN | null,
is_default?: boolean,
fingerprint_seed?: string,
domain_count?: number,
created_at: string,
updated_at?: string,
signed_in_sites?: {
site: string,
claimed_at: string
}[]
}[]
update
profiles.update
Rename a profile or change its proxy country and default flag
Risk: write
await corsair.tinyfish.api.profiles.update({ profileId: 'p_...', name: 'Work laptop' });
| Name | Type | Required | Description |
|---|---|---|---|
profileId | string | Yes | — |
name | string | No | — |
set_as_default | boolean | No | — |
proxy_country_code | US | GB | CA | AU | DE | FR | IT | ES | NL | JP | SG | BR | IN | null | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | — |
name | string | Yes | — |
proxy_country_code | US | GB | CA | AU | DE | FR | IT | ES | NL | JP | SG | BR | IN | null | No | — |
is_default | boolean | No | — |
fingerprint_seed | string | No | — |
domain_count | number | No | — |
created_at | string | Yes | — |
updated_at | string | No | — |
domains | object[] | Yes | — |
domains full type
domains full type
{
domain: string,
cookie_count: number,
local_storage_origin_count: number,
last_accessed_at: string,
last_written_at: string,
last_written_by_run_id: string
}[]
Research
cancel
research.cancel
Cancel a research run
Risk: write
await corsair.tinyfish.api.research.cancel({ researchRunId: 'rr_...' });
| Name | Type | Required | Description |
|---|---|---|---|
researchRunId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
research_run_id | string | Yes | — |
status | RUNNING | COMPLETED | FAILED | CANCELLED | TIMED_OUT | QUEUED | Yes | — |
cancelled | boolean | Yes | — |
get
research.get
Get a research run with its plan, evidence and report
Risk: read
await corsair.tinyfish.api.research.get({ researchRunId: 'rr_...' });
| Name | Type | Required | Description |
|---|---|---|---|
researchRunId | string | Yes | — |
| Name | Type | Required | Description |
|---|---|---|---|
research_run_id | string | Yes | — |
status | RUNNING | COMPLETED | FAILED | CANCELLED | TIMED_OUT | QUEUED | Yes | — |
query | string | Yes | — |
quick_result | object | null | Yes | — |
quick_result_summary | string | null | Yes | — |
deep_result | object | null | Yes | — |
run_ids | string[] | Yes | — |
created_at | string | null | Yes | — |
completed_at | string | null | Yes | — |
error | object | null | Yes | — |
research_plan | object | null | No | — |
evidence | object[] | null | No | — |
iterations | number | null | No | — |
quick_result full type
quick_result full type
{
answer: string,
citations: string[],
actions?: {
id: string,
label: string,
status: running | done | error,
streamingUrl?: string,
kind?: plan | search | fetch | browse | map,
iteration?: number,
url?: string,
query?: string,
details?: string[]
}[],
stats?: {
iterations: number,
sources_searched: number,
sources_fetched: number,
agent_runs: number,
claims_extracted: number,
termination_reason: planner_done | planner_no_queries | max_iterations | deadline | synthesis_failed | abort,
subquestions_covered: number,
subquestions_total: number
}
} | null
deep_result full type
deep_result full type
{
result: string,
citations: string[],
freshness_report?: {
filter_applied?: {
domain_type?: web | news | research_paper,
after_date?: string,
before_date?: string,
recency_minutes?: number
},
latest_published_date?: string,
sources_with_dates: number,
sources_without_dates: number,
sources_in_requested_window: number,
fetched_at_latest?: string
},
termination_reason?: planner_done | planner_no_queries | max_iterations | deadline | synthesis_failed | abort
} | null
error full type
error full type
{
code: string,
message: string,
details?: any | null
} | null
research_plan full type
research_plan full type
{
summary: string,
subquestions: {
id: string,
question: string,
priority: high | medium | low
}[],
search_queries: string[],
done: boolean,
review?: {
id: string,
status: pending | approve | refine | timeout,
expiresAt: number,
feedback?: string,
resolvedAt?: number
}
} | null
evidence full type
evidence full type
{
url: string,
title: string,
language?: string | null,
published_date?: string | null,
fetched_at?: string,
live_fetch?: boolean,
access_method?: fetch | browser | social,
discovered_by_queries?: string[],
search_filters?: {
after_date?: string,
before_date?: string,
recency_minutes?: number
},
subquestions_covered: string[],
claims: {
claim: string,
snippet: string,
subquestion_id: string,
confidence: high | medium | low,
claim_type?: fact | official_statement | reported_claim | estimate | opinion | user_sentiment | unverified
}[],
source_quality: primary | secondary | low
}[] | null
list
research.list
List research runs with status and date filters
Risk: read
await corsair.tinyfish.api.research.list({ status: 'RUNNING' });
| Name | Type | Required | Description |
|---|---|---|---|
status | RUNNING | COMPLETED | FAILED | CANCELLED | TIMED_OUT | QUEUED | No | — |
query | string | No | — |
created_after | string | No | — |
created_before | string | No | — |
sort_direction | asc | desc | No | — |
cursor | string | No | — |
limit | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
data | object[] | Yes | — |
pagination | object | Yes | — |
data full type
data full type
{
research_run_id: string,
status: RUNNING | COMPLETED | FAILED | CANCELLED | TIMED_OUT | QUEUED,
query: string,
quick_result: {
answer: string,
citations: string[],
actions?: {
id: string,
label: string,
status: running | done | error,
streamingUrl?: string,
kind?: plan | search | fetch | browse | map,
iteration?: number,
url?: string,
query?: string,
details?: string[]
}[],
stats?: {
iterations: number,
sources_searched: number,
sources_fetched: number,
agent_runs: number,
claims_extracted: number,
termination_reason: planner_done | planner_no_queries | max_iterations | deadline | synthesis_failed | abort,
subquestions_covered: number,
subquestions_total: number
}
} | null,
quick_result_summary: string | null,
deep_result: {
result: string,
citations: string[],
freshness_report?: {
filter_applied?: {
domain_type?: web | news | research_paper,
after_date?: string,
before_date?: string,
recency_minutes?: number
},
latest_published_date?: string,
sources_with_dates: number,
sources_without_dates: number,
sources_in_requested_window: number,
fetched_at_latest?: string
},
termination_reason?: planner_done | planner_no_queries | max_iterations | deadline | synthesis_failed | abort
} | null,
run_ids: string[],
created_at: string | null,
completed_at: string | null,
error: {
code: string,
message: string,
details?: any | null
} | null,
research_plan?: {
summary: string,
subquestions: {
id: string,
question: string,
priority: high | medium | low
}[],
search_queries: string[],
done: boolean,
review?: {
id: string,
status: pending | approve | refine | timeout,
expiresAt: number,
feedback?: string,
resolvedAt?: number
}
} | null,
evidence?: {
url: string,
title: string,
language?: string | null,
published_date?: string | null,
fetched_at?: string,
live_fetch?: boolean,
access_method?: fetch | browser | social,
discovered_by_queries?: string[],
search_filters?: {
after_date?: string,
before_date?: string,
recency_minutes?: number
},
subquestions_covered: string[],
claims: {
claim: string,
snippet: string,
subquestion_id: string,
confidence: high | medium | low,
claim_type?: fact | official_statement | reported_claim | estimate | opinion | user_sentiment | unverified
}[],
source_quality: primary | secondary | low
}[] | null,
iterations?: number | null
}[]
pagination full type
pagination full type
{
total: number,
next_cursor: string | null,
has_more: boolean
}
start
research.start
Start a cited research run and return its research run ID
Risk: write
await corsair.tinyfish.api.research.start({ query: 'state of browser agents in 2026', mode: 'deep' });
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | — |
mode | deep | max | No | — |
stream | boolean | No | — |
output_language | string | No | — |
weak_sources_enabled | boolean | No | — |
domain_type | web | news | research_paper | No | — |
after_date | string | No | — |
before_date | string | No | — |
recency_minutes | number | No | — |
domain_filter | object | No | — |
prior_run_id | string | No | — |
session_id | string | No | — |
domain_filter full type
domain_filter full type
{
mode: include | exclusive,
domains?: string[],
block?: string[]
}
| Name | Type | Required | Description |
|---|---|---|---|
research_run_id | string | Yes | — |
error | object | null | Yes | — |
error full type
error full type
{
code: string,
message: string
} | null
Search
search
search.search
Search the web with intent, date, domain and academic filters
Risk: read
await corsair.tinyfish.api.search.search({ query: 'open source integration layer', domain_type: 'news', recency_minutes: 1440 });
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | — |
purpose | string | No | — |
location | string | No | — |
language | string | No | — |
include_domains | string | No | — |
exclude_domains | string | No | — |
domain_type | web | news | research_paper | No | — |
after_date | string | No | — |
before_date | string | No | — |
recency_minutes | number | No | — |
pub_year_min | number | No | — |
pub_year_max | number | No | — |
page | number | null | No | — |
include_thumbnail | true | false | No | — |
fetch | string | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | — |
results | object[] | Yes | — |
total_results | number | Yes | — |
page | number | Yes | — |
request_id | string | No | — |
results full type
results full type
{
position: number,
site_name: string,
snippet: string,
title: string,
url: string,
thumbnail_url?: string | null,
fetch?: any | null,
fetch_error?: any | null,
date?: string | null,
publisher?: string | null,
authors?: string[],
venue?: string | null,
year?: number | null,
cited_by_count?: number | null,
pdf_url?: string | null
}[]
usage
search.usage
List recent search requests and their stored results
Risk: read
await corsair.tinyfish.api.search.usage({ status: 'completed', limit: 20 });
| Name | Type | Required | Description |
|---|---|---|---|
start_after | string | No | — |
end_before | string | No | — |
status | completed | failed | No | — |
limit | number | No | — |
page | number | No | — |
| Name | Type | Required | Description |
|---|---|---|---|
items | object[] | Yes | — |
total | number | Yes | — |
limit | number | Yes | — |
page | number | Yes | — |
total_pages | number | Yes | — |
has_more | boolean | Yes | — |
items full type
items full type
{
id: number,
request_id: string,
query: string,
status_code: number,
result_count: number,
results: {
position: number,
site_name: string,
snippet: string,
title: string,
url: string,
thumbnail_url?: string | null,
fetch?: any | null,
fetch_error?: any | null,
date?: string | null,
publisher?: string | null,
authors?: string[],
venue?: string | null,
year?: number | null,
cited_by_count?: number | null,
pdf_url?: string | null
}[] | null,
cached: boolean | null,
response_size_bytes: number | null,
created_at: string
}[]
Vault
list
vault.list
List vault items and the credential IDs a run body can reference
Risk: read
await corsair.tinyfish.api.vault.list({});
| Name | Type | Required | Description |
|---|---|---|---|
items | object[] | Yes | — |
items full type
items full type
{
itemId: string,
connectionId: string | null,
label: string,
vaultName: string,
domains: string[],
fieldMetadata: {
fieldId: string,
label: string,
type: STRING | CONCEALED | OTP
}[],
hasTotp: boolean
}[]
Wallet
get
wallet.get
Get the wallet balance, pending top-up and per-product rates
Risk: read
await corsair.tinyfish.api.wallet.get({});
| Name | Type | Required | Description |
|---|---|---|---|
available_balance | string | Yes | — |
currency | USD | Yes | — |
as_of | string | Yes | — |
auto_reload | any | null | Yes | — |
pending_top_up | object | null | Yes | — |
rates | object | null | Yes | — |
agent_top_up_url | string | No | — |
pending_top_up full type
pending_top_up full type
{
amount: string,
started_at: string
} | null
rates full type
rates full type
{
meters: {
label: string,
unit_amount: string,
currency: USD,
per: string
}[],
as_of: string
} | null