---
title: "List search usage"
method: GET
path: "/search/usage"
tags: ["Search"]
---

# List search usage

`GET /search/usage`

## Request

- Base URL: `https://api.search.tinyfish.ai`
- URL: `https://api.search.tinyfish.ai/search/usage`
- Auth: API key in header `X-API-Key`

List search usage records for the authenticated user. Returns paginated results with query details, status, and result counts.

## Query parameters

- `start_after` string, date-time
- `end_before` string, date-time
- `status` 'completed' | 'failed'
- `limit` integer
- `page` integer

## Response `200`

Search usage retrieved successfully.

- object: Paginated search usage response
  - `items` object[], required
    - `id` integer, required
    - `request_id` string, required
    - `query` string, required
    - `status_code` integer, required
    - `result_count` integer, required
    - `results` object[], nullable, required
      - `position` integer, required: Position in search results
      - `site_name` string, required: Site name
      - `snippet` string, required: Text snippet from the result
      - `title` string, required: Page title
      - `url` string, uri, required: Result URL
      - `thumbnail_url` string, uri: Thumbnail image URL, present only when include_thumbnail=true and a thumbnail is available
      - `fetch` unknown
      - `fetch_error` unknown
      - `date` string: Publication date, present for news and some web results
      - `publisher` string: Publisher name, present for news results when domain_type=news
      - `authors` string[]: Author list, present for academic results when domain_type=research_paper
      - `venue` string: Journal or conference name, present when domain_type=research_paper
      - `year` integer: Publication year, present when domain_type=research_paper
      - `cited_by_count` integer: Citation count, present when domain_type=research_paper
      - `pdf_url` string: PDF URL, present when domain_type=research_paper and a PDF is available
    - `cached` boolean, nullable, required
    - `response_size_bytes` integer, nullable, required
    - `created_at` string, date-time, required
  - `total` integer, required
  - `limit` integer, required
  - `page` integer, required
  - `total_pages` integer, required
  - `has_more` boolean, required

## Other responses

- `400`: Invalid query parameters
- `401`: Unauthorized - Invalid or missing API key
- `404`: Search API is not available
- `429`: Rate limit exceeded
- `500`: Internal server error
- `503`: Search service unavailable

---

[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/c48ef855099d?raw)