> ## Documentation Index > Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt > Use this file to discover all available pages before exploring further. # List research runs > 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. ## OpenAPI ````yaml https://agent.tinyfish.ai/v1/openapi/research get /v1/research-run openapi: 3.0.0 info: title: TinyFish Research API version: 1.0.0 description: Create source-backed research reports and stream their progress. contact: name: TinyFish Support email: support@tinyfish.ai servers: - url: https://agent.tinyfish.ai security: [] paths: /v1/research-run: get: summary: List research runs description: >- 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. operationId: listResearchRuns parameters: - schema: type: string enum: - RUNNING - COMPLETED - FAILED - CANCELLED - TIMED_OUT description: Filter by research run status example: COMPLETED required: false description: Filter by research run status name: status in: query - schema: type: string maxLength: 500 description: Filter by query text (case-insensitive partial match) example: AI safety required: false description: Filter by query text (case-insensitive partial match) name: query in: query - schema: type: string format: date-time description: Filter runs created after this ISO 8601 timestamp example: '2026-01-01T00:00:00Z' required: false description: Filter runs created after this ISO 8601 timestamp name: created_after in: query - schema: type: string format: date-time description: Filter runs created before this ISO 8601 timestamp example: '2026-02-01T00:00:00Z' required: false description: Filter runs created before this ISO 8601 timestamp name: created_before in: query - schema: type: string enum: - asc - desc default: desc description: Sort order by created_at example: desc required: false description: Sort order by created_at name: sort_direction in: query - schema: type: string description: >- Cursor for pagination (from previous response). Must be replayed with the same sort_direction used to generate it. required: false description: >- Cursor for pagination (from previous response). Must be replayed with the same sort_direction used to generate it. name: cursor in: query - schema: type: integer minimum: 1 maximum: 100 default: 20 description: Maximum number of results to return (1-100) example: 20 required: false description: Maximum number of results to return (1-100) name: limit in: query responses: '200': description: Paginated list of research runs content: application/json: schema: type: object properties: data: type: array items: type: object properties: research_run_id: type: string description: Unique research run identifier example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 status: type: string enum: - RUNNING - COMPLETED - FAILED - CANCELLED - TIMED_OUT description: Current status of the research run example: COMPLETED query: type: string description: The research query example: What are the latest AI safety papers? quick_result: type: object nullable: true properties: answer: type: string citations: type: array items: type: string actions: type: array items: type: object properties: id: type: string label: type: string status: type: string enum: - running - done - error streamingUrl: type: string kind: type: string enum: - plan - search - fetch - browse - map iteration: type: integer minimum: 0 url: type: string query: type: string required: - id - label - status required: - answer - citations description: >- Quick answer with citations, available before deep research completes quick_result_summary: type: string nullable: true description: Short prose summary of the quick result deep_result: type: object nullable: true properties: result: type: string description: The report text citations: type: array items: type: string freshness_report: type: object properties: filter_applied: type: object properties: domain_type: type: string enum: - web - news - research_paper description: >- Type of search to perform: "web" for standard results, "news" for news articles, "research_paper" for academic papers. Defaults to "web". example: news after_date: type: string description: >- Return results after this date (YYYY-MM-DD) example: '2024-01-01' before_date: type: string description: >- Return results before this date (YYYY-MM-DD) example: '2024-12-31' recency_minutes: type: integer minimum: 1 maximum: 5256000 description: >- Return results from the past N minutes (1 to 5,256,000). example: 60 latest_published_date: type: string sources_with_dates: type: integer minimum: 0 sources_without_dates: type: integer minimum: 0 sources_in_requested_window: type: integer minimum: 0 fetched_at_latest: type: string required: - sources_with_dates - sources_without_dates - sources_in_requested_window description: How fresh the sources behind this report are required: - result - citations description: >- Deep research report, available after the run completes run_ids: type: array items: type: string description: IDs of the agent runs spawned by this research run example: - a1b2c3d4-e5f6-7890-abcd-ef1234567890 created_at: type: string nullable: true description: ISO 8601 timestamp when the research run was created example: '2026-01-01T12:00:00Z' completed_at: type: string nullable: true description: >- ISO 8601 timestamp when the research run completed, or null if still running example: '2026-01-01T12:05:00Z' required: - research_run_id - status - query - quick_result - quick_result_summary - deep_result - run_ids - created_at - completed_at description: Research run description: Array of research runs pagination: type: object properties: total: type: integer description: Total number of runs matching the current filters example: 142 next_cursor: type: string nullable: true description: >- Cursor for fetching next page. Null if no more results. example: >- eyJpZCI6ImFiYyIsImNyZWF0ZWRBdCI6IjIwMjYtMDEtMDFUMTI6MDA6MDBaIn0= has_more: type: boolean description: Whether there are more results after this page example: true required: - total - next_cursor - has_more description: Pagination information required: - data - pagination '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication. Get your key from the API Keys page. ````