---
title: "List research runs"
method: GET
path: "/v1/research-run"
tags: ["Research"]
---

# List research runs

`GET /v1/research-run`

## Request

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

List saved research runs with optional filtering by status, query text, and date range. Cursors are only valid with the sort direction used to generate them.

## Query parameters

- `status` 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMED_OUT' | 'QUEUED': Filter by research run status
- `query` string: Filter by query text (case-insensitive partial match)
- `created_after` string, date-time: Filter runs created after this ISO 8601 timestamp
- `created_before` string, date-time: Filter runs created before this ISO 8601 timestamp
- `sort_direction` 'asc' | 'desc': Sort order by created_at
- `cursor` string: Cursor for pagination (from previous response). Must be replayed with the same sort_direction used to generate it.
- `limit` integer: Maximum number of results to return (1-100)

## Response `200`

Paginated list of research runs

- object
  - `data` object[], required: Array of research runs
    - `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
  - `pagination` object, required: Pagination information
    - `total` integer, required: Total number of runs matching the current filters
    - `next_cursor` string, nullable, required: Cursor for fetching next page. Null if no more results.
    - `has_more` boolean, required: Whether there are more results after this page

## Other responses

- `400`: Invalid request parameters
- `401`: Unauthorized - Invalid or missing API key
- `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)