---
title: "List search usage"
method: GET
path: "/usage"
---

# List search usage

`GET /usage`

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.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tinyfish/tinyfish-web-agent-automation-api/revisions/bea716bc627d/schema)