---
title: "Find the entries that list a handle"
method: GET
path: "/api/v1/handles"
tags: ["Entries"]
---

# Find the entries that list a handle

`GET /api/v1/handles`

## Request

- Base URL: `https://verifiedhandles.org`
- URL: `https://verifiedhandles.org/api/v1/handles`
- Auth: none required

Which public entries list this handle: “is x.com/someone an official account, and whose?”. Ask by `platform` and `value`, or by `url`, a profile’s address, which is read as the editor reads a pasted one: the platform whose address it is, and what follows it (`https://x.com/someone?s=20` is `twitter`, `someone`). The value is matched as the site stores and compares a handle: trimmed, case ignored on a platform that ignores it, a leading `@` optional on a platform shown with one, and a website completed to its `https://` address. An entry that lists the handle twice (`@x` and `x`) is answered once. A deleted entry, and a handle on a platform the site does not show, are never answered, nor is a Facebook value that is one of Facebook’s own path words (`pg`, `groups`, `?fref=ts`: no one’s account, and not shown on any entry). Email addresses are not looked up. Nothing found is a 200 with an empty `results`.

Any origin may read it: `Access-Control-Allow-Origin: *`, methods GET and OPTIONS, no credentials. An `OPTIONS` preflight answers 204. No key is needed. A request that sends one (`Authorization: Bearer`) has it checked, so a wrong, revoked or expired key is refused 401, and is counted against the key’s read limit; it gets the same answer, marked `no-store`.

## Query parameters

- `platform` string
- `value` string
- `url` string

## Response `200`

The entries that list the handle, perhaps none.

- HandleLookupResponse: The public entries that list a handle.
  - `platform` string, required: The platform looked on: the one asked, or the one whose address `url` is.
  - `value` string, required: The handle looked up, as the site stores one: from `url`, what follows the platform’s address.
  - `results` HandleHolder[], required: Verified handles first, then by VHID; at most 50. Empty when no public entry lists it.
    - `vhid` string, required: The entry’s VHID.
    - `title` string, required: The entry’s title.
    - `url` string, required: The entry’s page.
    - `value` string, required: The handle as the entry lists it: on a platform that ignores case, its case may differ from the value asked.
    - `verified` boolean, required: Whether the handle itself is verified on this entry (not the entry’s own badge).

## Other responses

- `400`: `platform_required`: neither a platform nor a url. `url_or_platform`: both. `unknown_platform`: not a platform the site lists handles on; `platforms` lists the ones it does. `masked_platform`: `email`. `value_required`, `value_too_long`. `url_not_recognised`: no platform’s address is that one. Each with a `message` saying so.
- `429`: Too many requests from this IP address in the last minute (at a route that takes a key, an admin key’s are counted per key instead, at the limits set on Console → Rate limits). Wait the number of seconds `Retry-After` gives.
- `503`: The site is down for maintenance. The body is the maintenance page, as HTML. Try again later: `Retry-After` gives the seconds.

---

[API](https://skmtc.dev/verifiedhandles/apis/verified-handles-api.md) · [All operations](https://skmtc.dev/verifiedhandles/apis/verified-handles-api/llms.txt) · [OpenAPI document](https://skmtc.dev/verifiedhandles/apis/verified-handles-api/revisions/40720de2e0ec?raw)