API

Every tinyfish.api.* operation is listed below with parameter shapes and return types from the plugin Zod schemas.

New to Corsair? See API access, authentication, and error handling.

Agent

cancelRun

agent.cancelRun Cancel a pending or running run Risk: write

await corsair.tinyfish.api.agent.cancelRun({ runId: 'run_...' });

Input

Name	Type	Required	Description
`runId`	`string`	Yes	—

Output

Name	Type	Required	Description
`run_id`	`string`	Yes	—
`status`	`CANCELLED \| COMPLETED \| FAILED`	Yes	—
`cancelled_at`	`string`	No	—
`message`	`string`	No	—

cancelRuns

agent.cancelRuns Cancel up to 100 runs in one request Risk: write

await corsair.tinyfish.api.agent.cancelRuns({ run_ids: ['run_...'] });

Input

Name	Type	Required	Description
`run_ids`	`string[]`	Yes	—

Output

Name	Type	Required	Description
`results`	`object[]`	Yes	—
`not_found`	`string[]`	No	—

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' });

Input

Name	Type	Required	Description
`runId`	`string`	Yes	—
`screenshots`	`base64 \| url \| none`	No	—
`html`	`url \| none`	No	—

Output

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`	No	—
`finished_at`	`string`	No	—
`num_of_steps`	`number`	No	—
`result`	`object`	No	—
`output_schema`	`object`	No	—
`profile_attached`	`boolean`	Yes	—
`profile_id`	`string`	No	—
`error`	`object`	No	—
`profile_hint`	`object`	No	—
`streaming_url`	`string`	No	—
`browser_config`	`object`	No	—
`video_url`	`string`	No	—
`steps`	`object[]`	Yes	—

result full type

{
}

output_schema 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
}

profile_hint full type

{
  message: string,
  setup_url: string,
  reason: auth_wall | bot_challenge
}

browser_config full type

{
  proxy_enabled?: boolean | null,
  proxy_country_code?: string | null
}

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_...'] });

Input

Name	Type	Required	Description
`run_ids`	`string[]`	Yes	—

Output

Name	Type	Required	Description
`data`	`object[]`	Yes	—
`not_found`	`string[]`	No	—

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?: {
  } | null,
  output_schema?: {
  } | 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_...' });

Input

Name	Type	Required	Description
`runId`	`string`	Yes	—
`stepId`	`string`	Yes	—

Output

Name	Type	Required	Description
`contentType`	`string`	Yes	—
`html`	`string`	Yes	—

getStepScreenshot

agent.getStepScreenshot Get the JPEG screenshot captured at one step of a run Risk: read

await corsair.tinyfish.api.agent.getStepScreenshot({ runId: 'run_...', stepId: 'evt_...' });

Input

Name	Type	Required	Description
`runId`	`string`	Yes	—
`stepId`	`string`	Yes	—

Output

Name	Type	Required	Description
`contentType`	`string`	Yes	—
`base64`	`string`	Yes	—
`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 });

Input

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	—

Output

Name	Type	Required	Description
`data`	`object[]`	Yes	—
`pagination`	`object`	Yes	—

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?: {
  } | null,
  output_schema?: {
  } | 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

{
  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' });

Input

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`	`object`	No	—

agent_config full type

{
  mode?: default | strict,
  cursor_style?: fish | standard | green-pointer,
  max_steps?: number,
  max_duration_seconds?: number
}

capture_config full type

{
  elements?: boolean,
  snapshots?: boolean,
  screenshots?: boolean,
  recording?: boolean,
  html?: boolean
}

proxy_config full type

{
  enabled: boolean,
  country_code?: US | GB | CA | DE | FR | JP | AU | null
}

output_schema full type

{
}

Output

Name	Type	Required	Description
`run_id`	`string`	No	—
`status`	`COMPLETED \| FAILED`	Yes	—
`started_at`	`string`	No	—
`finished_at`	`string`	No	—
`num_of_steps`	`number`	No	—
`result`	`object`	No	—
`error`	`object`	No	—
`profile_hint`	`object`	No	—

result 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
}

profile_hint full type

{
  message: string,
  setup_url: string,
  reason: auth_wall | bot_challenge
}

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' });

Input

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`	`object`	No	—

agent_config full type

{
  mode?: default | strict,
  cursor_style?: fish | standard | green-pointer,
  max_steps?: number,
  max_duration_seconds?: number
}

capture_config full type

{
  elements?: boolean,
  snapshots?: boolean,
  screenshots?: boolean,
  recording?: boolean,
  html?: boolean
}

proxy_config full type

{
  enabled: boolean,
  country_code?: US | GB | CA | DE | FR | JP | AU | null
}

output_schema full type

{
}

Output

Name	Type	Required	Description
`run_id`	`string`	No	—
`error`	`object`	No	—

error full type

{
  code: string,
  message: string
}

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' }] });

Input

Name	Type	Required	Description
`runs`	`object[]`	Yes	—
`profile_id`	`string`	No	—
`output_schema`	`object`	No	—

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?: {
  }
}[]

output_schema full type

{
}

Output

Name	Type	Required	Description
`run_ids`	`string[]`	No	—
`error`	`object`	No	—

error full type

{
  code: string,
  message: string,
  details?: any | 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 });

Input

Name	Type	Required	Description
`url`	`string`	No	—
`timeout_seconds`	`number`	No	—
`proxy_config`	`object`	No	—

proxy_config full type

{
  enabled?: boolean,
  type?: tinyfish | custom,
  country_code?: string,
  url?: string,
  username?: string,
  password?: string
}

Output

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_...' });

Input

Name	Type	Required	Description
`sessionId`	`string`	Yes	—

Output

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 });

Input

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	—

Output

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

{
  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 });

Input

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	—

Output

Name	Type	Required	Description
`results`	`object[]`	Yes	—
`errors`	`object[]`	Yes	—
`request_id`	`string`	No	—

results full type

{
  url: string,
  final_url?: string | null,
  title?: string | null,
  description?: string | null,
  language?: string | null,
  format: markdown | html | json,
  text?: string | {
  } | null,
  author?: string | null,
  published_date?: string | null,
  links?: string[],
  image_links?: string[],
  iframe_links?: string[],
  page_metadata?: {
  },
  latency_ms?: number | null,
  not_modified?: boolean,
  etag?: string,
  last_modified?: string,
  unmatched_selectors?: string[]
}[]

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' });

Input

Name	Type	Required	Description
`start_after`	`string`	No	—
`end_before`	`string`	No	—
`status`	`completed \| failed`	No	—
`limit`	`number`	No	—
`page`	`number`	No	—

Output

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

{
  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 });

Input

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`	No	—

Output

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`	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_...' });

Input

Name	Type	Required	Description
`profileId`	`string`	Yes	—

Output

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_...' });

Input

Name	Type	Required	Description
`profileId`	`string`	Yes	—

Output

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

{
  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({});

Input: empty object Output

Name	Type	Required	Description
`profiles`	`object[]`	Yes	—

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' });

Input

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`	No	—

Output

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

{
  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_...' });

Input

Name	Type	Required	Description
`researchRunId`	`string`	Yes	—

Output

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_...' });

Input

Name	Type	Required	Description
`researchRunId`	`string`	Yes	—

Output

Name	Type	Required	Description
`research_run_id`	`string`	Yes	—
`status`	`RUNNING \| COMPLETED \| FAILED \| CANCELLED \| TIMED_OUT \| QUEUED`	Yes	—
`query`	`string`	Yes	—
`quick_result`	`object`	No	—
`quick_result_summary`	`string`	No	—
`deep_result`	`object`	No	—
`run_ids`	`string[]`	Yes	—
`created_at`	`string`	No	—
`completed_at`	`string`	No	—
`error`	`object`	No	—
`research_plan`	`object`	No	—
`evidence`	`object[]`	No	—
`iterations`	`number`	No	—

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

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
}

error full type

{
  code: string,
  message: string,
  details?: any | null
}

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

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
}[]

list

research.list List research runs with status and date filters Risk: read

await corsair.tinyfish.api.research.list({ status: 'RUNNING' });

Input

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	—

Output

Name	Type	Required	Description
`data`	`object[]`	Yes	—
`pagination`	`object`	Yes	—

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

{
  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' });

Input

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

{
  mode: include | exclusive,
  domains?: string[],
  block?: string[]
}

Output

Name	Type	Required	Description
`research_run_id`	`string`	Yes	—
`error`	`object`	No	—

error full type

{
  code: string,
  message: string
}

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 });

Input

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`	No	—
`include_thumbnail`	`true \| false`	No	—
`fetch`	`string`	No	—

Output

Name	Type	Required	Description
`query`	`string`	Yes	—
`results`	`object[]`	Yes	—
`total_results`	`number`	Yes	—
`page`	`number`	Yes	—
`request_id`	`string`	No	—

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 });

Input

Name	Type	Required	Description
`start_after`	`string`	No	—
`end_before`	`string`	No	—
`status`	`completed \| failed`	No	—
`limit`	`number`	No	—
`page`	`number`	No	—

Output

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

{
  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({});

Input: empty object Output

Name	Type	Required	Description
`items`	`object[]`	Yes	—

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({});

Input: empty object Output

Name	Type	Required	Description
`available_balance`	`string`	Yes	—
`currency`	`USD`	Yes	—
`as_of`	`string`	Yes	—
`auto_reload`	`any`	No	—
`pending_top_up`	`object`	No	—
`rates`	`object`	No	—
`agent_top_up_url`	`string`	No	—

pending_top_up full type

{
  amount: string,
  started_at: string
}

rates full type

{
  meters: {
    label: string,
    unit_amount: string,
    currency: USD,
    per: string
  }[],
  as_of: string
}

Overview

Plugins

Agent

cancelRun

cancelRuns

getRun

getRuns

getStepHtml

getStepScreenshot

listRuns

run

runAsync

runBatch

Browser

createSession

terminateSession

usage

Fetch

fetch

usage

Profiles

create

delete

get

list

update

Research

cancel

get

list

start

Search

search

usage

Vault

list

Wallet

get

​Agent

​cancelRun

​cancelRuns

​getRun

​getRuns

​getStepHtml

​getStepScreenshot

​listRuns

​run

​runAsync

​runBatch

​Browser

​createSession

​terminateSession

​usage

​Fetch

​fetch

​usage

​Profiles

​create

​delete

​get

​list

​update

​Research

​cancel

​get

​list

​start

​Search

​search

​usage

​Vault

​list

​Wallet

​get

Agent

cancelRun

cancelRuns

getRun

getRuns

getStepHtml

getStepScreenshot

listRuns

run

runAsync

runBatch

Browser

createSession

terminateSession

usage

Fetch

fetch

usage

Profiles

create

delete

get

list

update

Research

cancel

get

list

start

Search

search

usage

Vault

list

Wallet

get