Skip to main content

Endpoints

All endpoints use https://agent.tinyfish.ai and require the X-API-Key header.
Research must be enabled for the API key’s account. POST /v1/automation/run-research returns 403 when it is not.

Modes

An omitted mode selects deep. Both modes research with search and static fetches.

Request Body

session_id and prior_run_id are mutually exclusive. See continuation examples.

Errors

Event Stream

Accepted requests return text/event-stream, including when stream is omitted or false. Invalid input and other pre-run failures return the standard JSON error body. Ignore event types you don’t recognise; new ones may be added. Ordered synthesis_delta values reconstruct their matching summary or final result. Discard a provisional partial checkpoint after synthesis_discarded. Heartbeats keep long-running connections open. Every stream response carries an X-Research-Run-Id header with the run ID. Retained progress events expire 1 hour after they are written; after that, read saved results with GET /v1/research-run/{research_run_id}.

Run Statuses

COMPLETED, FAILED, CANCELLED, and TIMED_OUT are terminal. Both modes share the same 45-minute budget.

List Saved Runs

GET /v1/research-run supports status, query, created_after, and created_before. Pagination uses limit from 1–100 (default 20), sort_direction=asc|desc (default desc), and the returned next_cursor. Reuse a cursor only with the same sort direction.
quick_result holds answers from runs made before standard mode was removed; deep_result holds the report. Both are objects: read the report from deep_result.result, not from deep_result itself. quick_result_summary is the one plain string. run_ids lists the Agent runs a Max run started. Fields that do not apply to the run are null.

Retrieve One Run

GET /v1/research-run/{research_run_id} returns the list fields plus the working state kept for the run.
A run that does not exist returns HTTP 404. A run owned by another user returns HTTP 403. Any API key of the user who started the run can read it.

Completion Metadata

Saved reports can include deep_result.termination_reason and deep_result.freshness_report. Both fields are optional on older runs. The SSE final_result event includes the termination reason; retrieve the saved run for the freshness report. COMPLETED describes the saved run status. Check the termination reason before treating the report as a full final synthesis, especially when it is synthesis_failed. Freshness describes source-date coverage, not accuracy or credibility. Dates come from source metadata or extraction and may be missing. Current requests do not accept date-window filters. deep_result.follow_up_suggestions lists up to three short follow-up questions written from the report, for runs started from the TinyFish app in ChatGPT or Claude. It is absent on other runs and when none could be generated. For example, a saved deep_result can contain:

Cancel a Run

Call POST /v1/research-run/{research_run_id}/cancel to cancel a running research run. The response reports whether this request changed the run to CANCELLED and includes its current status.
Cancellation is idempotent. A run that is already terminal returns HTTP 200 with cancelled: false and its current status. A missing run, or a run owned by another user, returns HTTP 404.

Limits

Limits apply per user across all your API keys, MCP, CLI, SDKs and the dashboard. Pricing. Each completed run is charged to your wallet: deep costs $2 per run and `max` $3 per run. A run is charged when it completes; failed, timed-out and cancelled runs are not charged. Follow-ups. Each follow-up creates a new research run and costs the selected mode’s normal rate. Continuing a session does not make the run free or discounted. See continuation examples. Concurrent runs. You can have up to 5 runs in progress by default. Contact support if you need higher limits. Overdraft. Admission checks your balance when a run starts; the charge happens when it completes. Runs already admitted are never stopped. If several runs are in flight, all of them are charged even if that takes your balance below zero. Starts need a positive wallet balance. With a balance of zero or below, starts return HTTP 402 with error.code set to INSUFFICIENT_CREDITS until you add funds at the wallet page. The body has no details.
Starting a run beyond the concurrent limit returns HTTP 429 with error.code set to RATE_LIMIT_EXCEEDED and a Retry-After: 30 header. No run is created. This check runs after the balance check, so a 402 takes precedence. details.active_research_run_ids lists up to 10 of your queued or running runs, newest first, so you can poll them before starting another.
HTTP 503 with error.code set to SERVICE_BUSY means billing or the concurrency store is temporarily unavailable; retry after a short pause. If the billing check does not answer in time, the run starts and is billed normally when it completes.

Start asynchronously

Use POST /v1/automation/run-research-async to enqueue research and return immediately:
After durable dispatch, the endpoint returns HTTP 200 with:
This follows TinyFish’s asynchronous automation convention. Poll by ID to retrieve current status and results; the worker may already be running when you receive it.
  • GET /v1/research-run/{id} returns current state and saved partial/final results.
  • GET /v1/research-run/{id}/events streams progress; reconnect with Last-Event-ID.
  • POST /v1/research-run/{id}/cancel explicitly cancels work.
States are QUEUED, RUNNING, COMPLETED, FAILED, CANCELLED, and TIMED_OUT. The last four are terminal; stop polling when one is returned. Partial results can exist on unsuccessful runs, so inspect status before treating a report as complete. Disconnecting an event stream does not cancel the job. Retained progress events expire; polling remains the durable source for saved results. For a single-request stream, keep using POST /v1/automation/run-research. The request field stream controls synthesis text deltas, not async versus SSE delivery. Both start endpoints accept the same research parameters and limits. Polling responses also include error: null for queued, running, or completed runs, otherwise {code, message} with TASK_FAILED, CANCELLED, or TIMEOUT. These describe the persisted terminal outcome, not a detailed provider failure. Existing result fields remain available, including partial reports. Async starts are not idempotent. Retrying a POST after a timeout can create a second run and incur additional usage. Keep the returned research_run_id and poll or reconnect to that run. If no ID was received, the run may still have been accepted; check your run list before starting another. Incompatible optional fields in older saved runs return null and are logged; other valid report fields remain readable.