---
title: "Get research run by ID"
method: GET
path: "/v1/research-run/{research_run_id}"
tags: ["Research"]
---

# Get research run by ID

`GET /v1/research-run/{research_run_id}`

## Request

- Base URL: `https://agent.tinyfish.ai`
- URL: `https://agent.tinyfish.ai/v1/research-run/{research_run_id}`
- Auth: API key in header `X-API-Key`

Retrieve one saved research run, including the plan, evidence, and per-iteration working state.

## Path parameters

- `research_run_id` string, required: Research run identifier

## Response `200`

Research run

- object
  - `research_run_id` string, required: Unique research run identifier
  - `status` 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMED_OUT' | 'QUEUED', required: Current status of the research run
  - `query` string, required: The research query
  - `quick_result` object, nullable, required: Quick answer with citations, available before deep research completes
    - `answer` string, required
    - `citations` string[], required
    - `actions` object[]
      - `id` string, required
      - `label` string, required
      - `status` 'running' | 'done' | 'error', required
      - `streamingUrl` string
      - `kind` 'plan' | 'search' | 'fetch' | 'browse' | 'map'
      - `iteration` integer
      - `url` string
      - `query` string
      - `details` string[]
    - `stats` object
      - `iterations` number, required
      - `sources_searched` number, required
      - `sources_fetched` number, required
      - `agent_runs` number, required
      - `claims_extracted` number, required
      - `termination_reason` 'planner_done' | 'planner_no_queries' | 'max_iterations' | 'deadline' | 'synthesis_failed' | 'abort', required
      - `subquestions_covered` number, required
      - `subquestions_total` number, required
  - `quick_result_summary` string, nullable, required: Short prose summary of the quick result
  - `deep_result` object, nullable, required: Deep research report, available after the run completes
    - `result` string, required: The report text
    - `citations` string[], required
    - `freshness_report` object: How fresh the sources behind this report are
      - `filter_applied` object
        - `domain_type` 'web' | 'news' | 'research_paper': Type of search to perform: "web" for standard results, "news" for news articles, "research_paper" for academic papers. Defaults to "web".
        - `after_date` string: Return results after this date (YYYY-MM-DD)
        - `before_date` string: Return results before this date (YYYY-MM-DD)
        - `recency_minutes` integer: Return results from the past N minutes (1 to 5,256,000).
      - `latest_published_date` string
      - `sources_with_dates` integer, required
      - `sources_without_dates` integer, required
      - `sources_in_requested_window` integer, required
      - `fetched_at_latest` string
    - `termination_reason` 'planner_done' | 'planner_no_queries' | 'max_iterations' | 'deadline' | 'synthesis_failed' | 'abort': Why research stopped; synthesis_failed indicates interim findings
  - `run_ids` string[], required: IDs of the agent runs spawned by this research run
  - `created_at` string, nullable, required: ISO 8601 timestamp when the research run was created
  - `completed_at` string, nullable, required: ISO 8601 timestamp when the research run completed, or null if still running
  - `error` object, nullable, required: Terminal outcome from saved status; null otherwise. Not the provider error.
    - `code` 'MISSING_API_KEY' | 'INVALID_API_KEY' | 'INVALID_INPUT' | 'RATE_LIMIT_EXCEEDED' | 'DAILY_LIMIT_EXCEEDED' | 'INTERNAL_ERROR' | 'RETRY_REQUIRED' | 'UNAUTHORIZED' | 'VAULT_RECONNECT_REQUIRED' | 'FORBIDDEN' | 'NOT_FOUND' | 'FEATURE_NOT_AVAILABLE' | 'SERVICE_BUSY' | 'TIMEOUT' | 'INSUFFICIENT_CREDITS' | 'FREE_ALLOWANCE_EXHAUSTED' | 'CONTENT_POLICY_VIOLATION' | 'MAX_STEPS_EXCEEDED' | 'SITE_BLOCKED' | 'TASK_FAILED' | 'CANCELLED', required: Machine-readable error code
    - `message` string, required: Human-readable error message
    - `details` unknown
  - `research_plan` object, nullable, required: Subquestions and searches the run planned
    - `summary` string, required
    - `subquestions` object[], required
      - `id` string, required
      - `question` string, required
      - `priority` 'high' | 'medium' | 'low', required
    - `search_queries` string[], required
    - `done` boolean, required
    - `review` object
      - `id` string, uuid, required
      - `status` 'pending' | 'approve' | 'refine' | 'timeout', required
      - `expiresAt` integer, required
      - `feedback` string
      - `resolvedAt` integer
  - `evidence` object[], nullable, required: Sources gathered, with the claims they support
    - `url` string, required
    - `title` string, required
    - `language` string, nullable
    - `published_date` string, nullable
    - `fetched_at` string
    - `live_fetch` boolean
    - `access_method` 'fetch' | 'browser' | 'social'
    - `discovered_by_queries` string[]
    - `search_filters` object
      - `after_date` string
      - `before_date` string
      - `recency_minutes` number
    - `subquestions_covered` string[], required
    - `claims` object[], required
      - `claim` string, required
      - `snippet` string, required
      - `subquestion_id` string, required
      - `confidence` 'high' | 'medium' | 'low', required
      - `claim_type` 'fact' | 'official_statement' | 'reported_claim' | 'estimate' | 'opinion' | 'user_sentiment' | 'unverified'
    - `source_quality` 'primary' | 'secondary' | 'low', required
  - `iterations` integer, nullable, required: Number of plan-search-synthesize iterations the run completed

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `403`: Forbidden - the run belongs to another API key
- `404`: Research run not found
- `500`: Internal server error

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/6c73a54df35c?raw)