> ## 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. # Run research with SSE streaming > Search, evaluate sources, and synthesize a cited report from a natural-language query. Accepted requests always return a Server-Sent Events stream, including when stream is false. ## OpenAPI ````yaml https://agent.tinyfish.ai/v1/openapi/research post /v1/automation/run-research 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/automation/run-research: post: summary: Run research with SSE streaming description: >- Search, evaluate sources, and synthesize a cited report from a natural-language query. Accepted requests always return a Server-Sent Events stream, including when stream is false. operationId: runResearch requestBody: description: Research parameters content: application/json: schema: type: object properties: query: type: string minLength: 1 maxLength: 2000 description: Research question example: Compare long-duration energy storage approaches mode: type: string enum: - auto - standard - deep - max description: >- Depth of research. Omitted selects deep; legacy auto selects standard. Max enables browser agents. example: standard stream: type: boolean description: >- Emit report text through synthesis_delta events as it is written output_language: type: string description: BCP 47 language tag for the report example: ja browser_enabled: type: boolean description: >- Max mode only. Defaults to true in Max mode; set false for search and static fetches only. weak_sources_enabled: type: boolean description: Allow relevant social and community sources domain_type: type: string enum: - web - news - research_paper description: Source pool to research over example: news after_date: type: string format: date description: Include results on or after this date (YYYY-MM-DD) example: '2026-01-01' before_date: type: string format: date description: Include results on or before this date (YYYY-MM-DD) example: '2026-06-30' recency_minutes: type: integer minimum: 1 maximum: 5256000 description: >- Include results from the last 1-5,256,000 minutes. Not combinable with date filters. example: 1440 domain_filter: type: object properties: mode: type: string enum: - include - exclusive description: >- include prioritizes the domains; exclusive restricts results to them domains: type: array items: type: string maxItems: 150 description: Domains to prefer or require block: type: array items: type: string maxItems: 150 description: Domains to always remove required: - mode description: Domain preferences. Each list accepts at most 150 entries. prior_run_id: type: string description: Seed this run with a completed report and its evidence session_id: type: string format: uuid description: >- Continue a standard-mode session. Mutually exclusive with prior_run_id. required: - query responses: '200': description: >- Server-Sent Events stream. Save the run ID from created and stop reading after done. See the Research API reference for the full event catalog. content: text/event-stream: schema: type: string example: |- data: {"event":"created","research_run_id":"019..."} data: {"event":"plan_updated","iteration":1} data: {"event":"final_result","result":"...","citations":[]} data: {"event":"done"} '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 '402': description: Payment required - wallet balance too low to start a run 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 '403': description: Forbidden - Research is not enabled for this account 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 '404': description: Not found - unknown session_id or prior_run_id 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 '429': description: Concurrent-run or daily-completion limit reached headers: Retry-After: description: Seconds to wait before retrying. schema: type: string 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 '503': description: Research is temporarily unavailable 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. ````