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 returntext/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 includedeep_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
CallPOST /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.
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.
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.
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
UsePOST /v1/automation/run-research-async to enqueue research and return immediately:
200 with:
GET /v1/research-run/{id}returns current state and saved partial/final results.GET /v1/research-run/{id}/eventsstreams progress; reconnect withLast-Event-ID.POST /v1/research-run/{id}/cancelexplicitly cancels work.
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.