> ## 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. # Search the web > Search the web and get structured results. Returns ranked results with titles, snippets, and URLs. **Location and language resolution:** - If `location` is set but `language` is not, the language auto-resolves to the most predominantly used language in that country. - If `language` is set but `location` is not, the location auto-resolves to the country where that language is most predominantly used. - If neither `location` nor `language` is set, defaults to `US` and `en`. ## OpenAPI ````yaml https://agent.tinyfish.ai/v1/openapi/search get / openapi: 3.0.0 info: title: TinyFish Search API version: 1.0.0 description: Get structured ranked web results for a query. contact: name: TinyFish Support email: support@tinyfish.ai servers: - url: https://api.search.tinyfish.ai security: [] paths: /: get: summary: Search the web description: >- Search the web and get structured results. Returns ranked results with titles, snippets, and URLs. **Location and language resolution:** - If `location` is set but `language` is not, the language auto-resolves to the most predominantly used language in that country. - If `language` is set but `location` is not, the location auto-resolves to the country where that language is most predominantly used. - If neither `location` nor `language` is set, defaults to `US` and `en`. operationId: search parameters: - schema: type: string minLength: 1 maxLength: 2000 description: Search query example: web automation tools required: true description: Search query name: query in: query - schema: type: string minLength: 1 maxLength: 2000 description: >- Why this search is being run — the underlying goal or task the results will be used for. Used to better rank results against your intent. example: Find an open-source library for parsing PDF invoices in Python required: false description: >- Why this search is being run — the underlying goal or task the results will be used for. Used to better rank results against your intent. name: purpose in: query - schema: type: string description: Country code for geo-targeted results example: US required: false description: Country code for geo-targeted results name: location in: query - schema: type: string description: Language code for result language example: en required: false description: Language code for result language name: language in: query - schema: 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 required: false description: >- Type of search to perform: "web" for standard results, "news" for news articles, "research_paper" for academic papers. Defaults to "web". name: domain_type in: query - schema: type: string description: Return results after this date (YYYY-MM-DD) example: '2024-01-01' required: false description: Return results after this date (YYYY-MM-DD) name: after_date in: query - schema: type: string description: Return results before this date (YYYY-MM-DD) example: '2024-12-31' required: false description: Return results before this date (YYYY-MM-DD) name: before_date in: query - schema: type: integer minimum: 1 maximum: 5256000 description: Return results from the past N minutes (1 to 5,256,000). example: 60 required: false description: Return results from the past N minutes (1 to 5,256,000). name: recency_minutes in: query - schema: type: integer nullable: true minimum: 0 maximum: 10 description: Page number for pagination, starting from 0 (max 10) example: 2 required: false description: Page number for pagination, starting from 0 (max 10) name: page in: query - schema: type: string enum: - 'true' - 'false' description: >- When "true", each result includes a thumbnail_url when available. Defaults to false. example: 'true' required: false description: >- When "true", each result includes a thumbnail_url when available. Defaults to false. name: include_thumbnail in: query - schema: type: string maxLength: 256 description: JSON-encoded fetch configuration object. example: '{}' required: false description: JSON-encoded fetch configuration object. name: fetch in: query responses: '200': description: Search completed successfully. content: application/json: schema: type: object properties: query: type: string description: The search query that was executed example: web automation tools results: type: array items: type: object properties: position: type: integer description: Position in search results example: 1 site_name: type: string description: Site name example: example.com snippet: type: string description: Text snippet from the result example: This is an example snippet... title: type: string description: Page title example: Example Page url: type: string format: uri description: Result URL example: https://example.com/page thumbnail_url: type: string format: uri description: >- Thumbnail image URL, present only when include_thumbnail=true and a thumbnail is available example: https://example.com/thumb.jpg fetch: nullable: true description: >- Fetched page content, present only when fetch param is supplied fetch_error: nullable: true description: >- Fetch error details when fetch was requested. Contains details on failure; may be null when fetching succeeds. date: type: string description: >- Publication date, present for news and some web results publisher: type: string description: >- Publisher name, present for news results when domain_type=news authors: type: array items: type: string description: >- Author list, present for academic results when domain_type=research_paper venue: type: string description: >- Journal or conference name, present when domain_type=research_paper year: type: integer description: >- Publication year, present when domain_type=research_paper cited_by_count: type: integer description: >- Citation count, present when domain_type=research_paper pdf_url: type: string description: >- PDF URL, present when domain_type=research_paper and a PDF is available required: - position - site_name - snippet - title - url description: A single search result description: Array of search results total_results: type: integer description: Total number of results example: 10 page: type: integer description: The current page number, starting from 0 example: 0 required: - query - results - total_results - page description: Search response with results example: query: web automation tools results: - position: 1 site_name: example.com snippet: Top web automation tools for 2026... title: Best Web Automation Tools url: https://example.com/web-automation-tools total_results: 10 page: 0 '400': description: Invalid request - missing or invalid query 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 - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - 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 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 - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - 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 required: - error description: Standard error response format '402': description: >- Payment required - Search API access or an active subscription is required 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 - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - 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 required: - error description: Standard error response format '403': description: Forbidden - Search request forbidden by the upstream service 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 - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - 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 required: - error description: Standard error response format '404': description: Search API is not available 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 - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - 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 required: - error description: Standard error response format '429': description: Rate limit exceeded 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 - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - 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 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 - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - 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 required: - error description: Standard error response format '503': description: Search service 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 - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - 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 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. ````