> ## 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 search usage > List search usage records for the authenticated user. Returns paginated results with query details, status, and result counts. ## OpenAPI ````yaml https://agent.tinyfish.ai/v1/openapi/search get /usage 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: /usage: get: summary: List search usage description: >- List search usage records for the authenticated user. Returns paginated results with query details, status, and result counts. operationId: listSearchUsage parameters: - schema: type: string format: date-time required: false name: start_after in: query - schema: type: string format: date-time required: false name: end_before in: query - schema: type: string enum: - completed - failed required: false name: status in: query - schema: type: integer minimum: 1 maximum: 1000 default: 100 required: false name: limit in: query - schema: type: integer minimum: 1 default: 1 required: false name: page in: query responses: '200': description: Search usage retrieved successfully. content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: integer request_id: type: string query: type: string status_code: type: integer result_count: type: integer results: type: array nullable: true 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 cached: type: boolean nullable: true response_size_bytes: type: integer nullable: true created_at: type: string format: date-time required: - id - request_id - query - status_code - result_count - results - cached - response_size_bytes - created_at description: A single search usage record total: type: integer limit: type: integer page: type: integer total_pages: type: integer has_more: type: boolean required: - items - total - limit - page - total_pages - has_more description: Paginated search usage response example: items: - id: 1 request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 query: web automation tools status_code: 200 result_count: 10 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 cached: null response_size_bytes: 4096 created_at: '2026-01-14T10:30:00Z' total: 1 limit: 100 page: 1 total_pages: 1 has_more: false '400': description: 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 '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. ````