---
title: "Search public Grove creators"
method: GET
path: "/v1/creators/search"
tags: ["creators"]
---

# Search public Grove creators

`GET /v1/creators/search`

Substring search across creator handle, ENS name, basename, and social identity values (X, YouTube, TikTok, etc.). Returns a narrow 'search card' shape — no tip stats. Frontend should call /v1/profiles/{handle} for enrichment on drill-in.

When `q` is omitted, returns the top N creators by all-time USD tipped so the search box has something useful to show on focus. Optional `platform` filter narrows to accounts that have at least one identity of that type.

Public endpoint — no authentication required.

## Query parameters

- `q` string, nullable — Search term. When omitted, returns top N creators by USD tipped (featured mode).
- `platform` string, nullable — Optional identity_type filter (e.g., 'youtube', 'x', 'tiktok'). Narrows results to accounts that have at least one identity of that type.
- `limit` integer — Max results per page.
- `offset` integer — Pagination offset (search mode only).

## Response `200`

Matching or featured creators.

- CreatorSearchResponse — Response model for GET /v1/creators/search.
  - `query` string, nullable — Echo of the search term. Null when the endpoint is used in empty-query 'featured' mode.
  - `platform` string, nullable — Echo of the platform filter, if provided.
  - `entries` CreatorSearchEntry[], required
    - `account_id` string, required — Grove account UUID.
    - `handle` string, required — Grove username (canonical identifier).
    - `avatar_url` string, nullable — Creator's selected avatar URL (sourced from Account.metadata_json).
    - `description` string, nullable — Creator's profile bio (max 280 chars).
    - `ens_name` string, nullable — ENS name linked to one of the creator's wallets, when present.
    - `base_name` string, nullable — Base name linked to one of the creator's wallets, when present.
    - `matched_on` string, nullable — Match-source hint for UI highlighting. One of 'handle', 'ens_name', 'base_name', or a social platform identifier (e.g., 'youtube', 'x', 'bluesky'). Null for featured (empty-query) results.
  - `total_count` integer, required — Total number of results available for this query (for pagination).
  - `has_more` boolean, required — True if another page is available beyond the current offset+limit window.

## Other responses

- `400` — Query term too short (must be at least 2 characters after trimming).
- `422` — Validation Error

---

[API](https://skmtc.net/grove/apis/grove-api.md) · [All operations](https://skmtc.net/grove/apis/grove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grove/grove-api/versions/f286b48a8105/schema)