---
title: "Get many entries at once"
method: GET
path: "/api/v1/entities"
tags: ["Entries"]
---

# Get many entries at once

`GET /api/v1/entities`

## Request

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

Up to 50 entries in one request: the batch form of `GET /api/v1/entities/{vhid}`. Each key is answered exactly as that route answers it, in the order asked: the entry (`status: "ok"`, the same body), or `status: "not_found"` where it would answer 404. A deleted entry and a key that names nothing look the same. An old name or a merged entry’s key answers with the entry it now leads to; `entity.vhid` says which. A key repeated is answered once. The answer is 200 whatever each key answers: only the request itself is refused. A Wikidata QID is not a key here, as it is not at the single read: `GET /api/v1/search?q=Q42` finds the entries linked to an item. A key that contains a comma (only an old name can) cannot be asked for in a batch: use the single read.

**Rate limit.** Each key counts as one read against the IP address’s budget, so 50 keys cost what 50 single reads cost, and the request is refused (429) when the budget cannot cover it. A response the edge already holds costs nothing.

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

- `ids` string, required

## Response `200`

Each key’s answer.

- EntityBatch: Many entries at once: each key’s answer, in request order.
  - `results` EntityBatchResult[], required: One element per key asked for, in the order asked, a repeated key once (where it first appears).
    - union: What one requested key answers.
      - object
        - `key` string, required: The key as asked for, trimmed.
        - `status` 'ok', required
        - `entity` Entity, required: An entry: the same data its page shows, from the same code. Email addresses are masked. The text is CC0, except a description taken from Wikipedia (`description_license`).
          - `vhid` string, required: The entry’s VHID: 11 digits, permanent.
          - `short` string, nullable, required: The entry’s short name (`/<short>`), if it has one.
          - `title` string, required
          - `subtitle` string, nullable, required
          - `entity_type` string, nullable, required: What it is, from its Wikidata item: `person`, `organization` or `brand`; null when unknown. `entity_kind` says more.
          - `entity_kind` 'person' | 'musical_group' | 'sports_organization' | 'broadcaster' | 'publisher' | 'educational_institution' | 'research_organization' | 'religious_organization' | 'museum' | 'financial_institution' | 'chain' | 'nonprofit' | 'company' | 'organization' | 'show' | 'website' | 'software' | 'brand', nullable, required: The finer kind of thing it is, from its Wikidata item’s classes; null when unknown (an organisation or a brand not yet read since kinds were added reads null until the sync next reads its item). Each kind belongs to one `entity_type`, and `person`, `organization` and `brand` are also the kinds of an entry of that type with no finer one. The kinds, with their type: `person` (person: person), `musical_group` (organization: musical group), `sports_organization` (organization: sports organisation), `broadcaster` (organization: broadcaster), `publisher` (organization: publisher), `educational_institution` (organization: educational institution), `research_organization` (organization: research organisation), `religious_organization` (organization: religious organisation), `museum` (organization: museum), `financial_institution` (organization: financial institution), `chain` (organization: retail or hospitality chain), `nonprofit` (organization: charity or non-profit), `company` (organization: company), `organization` (organization: organisation), `show` (brand: show), `website` (brand: website or app), `software` (brand: software), `brand` (brand: brand). New kinds may be added; treat an unknown value as its `entity_type`.
          - `verified` boolean, required: Verified Handles has verified the entry.
          - `description` string, nullable, required: The description as sanitised HTML, links to other entries named as they are today.
          - `description_source` DescriptionSource, required: The English Wikipedia page an entry’s description was taken from: an article, or a draft (`draft: true`).
            - `kind` string, required: The source’s kind (`wikipedia`).
            - `title` string, required: The page’s title, underscored (`Draft:` first for a draft).
            - `url` string, required: The page.
            - `adapted` boolean: Present and true when the text has been edited on the site since.
            - `revision` integer: The page’s revision the text was taken from: its permalink is `https://en.wikipedia.org/w/index.php?title=<title>&oldid=<revision>`. Absent on a credit from before revisions were kept.
            - `draft` true: Present and true when the page is an English Wikipedia draft (the Draft namespace), not yet an article.
          - `description_license` 'CC-BY-SA-4.0', nullable, required: The description’s licence, as an SPDX id: `CC-BY-SA-4.0` when it was taken from Wikipedia (`description_source` is set), which means crediting the article and sharing alike. Null otherwise: the description is CC0 like the rest of the text.
          - `url` string, required: The entry’s canonical page.
          - `image` string, nullable, required: The lead image (the same as `images[0].url`), or null.
          - `image_rights` ImageRights, required: Who owns an image and how it may be reused. An entry’s text is CC0 (bar a description taken from Wikipedia); its images are licensed separately, by their owners.
            - `source` 'wikimedia_commons' | 'upload', required: Where the image came from.
            - `license` 'cc0-1.0' | 'public-domain' | 'cc-by-4.0' | 'cc-by-sa-4.0' | 'supplied' | 'permission' | 'none', nullable, required: An upload’s licence, by id. Null for a Commons image (see `license_name`) or when none was recorded.
            - `license_name` string, nullable, required: The licence’s name, e.g. "CC BY-SA 4.0". Null until it is known.
            - `license_url` string, nullable, required: The licence’s text.
            - `freely_licensed` boolean, nullable, required: May be reused under a free licence. Null when no licence is recorded.
            - `credit` string, nullable, required: The credit line to show when reusing the image.
            - `source_page` string, nullable, required: The image’s Wikimedia Commons file page, which states its licence and author.
            - `details_url` string, required: The entry’s "About this image" page.
          - `images` EntityImage[], required: Every image the entry shows, the lead first. Empty when it shows none.
            - `url` string, required: The image, as a path on this site (`/img/w/480q75/<id>`).
            - `main` boolean, required: True for the lead image, false for the gallery images after it.
            - `image_rights` ImageRights, required: Who owns an image and how it may be reused. An entry’s text is CC0 (bar a description taken from Wikipedia); its images are licensed separately, by their owners.
              - …
            - `link` string, nullable, required: Where the image links on the entry page instead of opening the full-screen viewer, or null.
          - `handles` Handle[], required
            - `platform` string, required: The platform’s id (`twitter`, `instagram`, `wikidata`, …).
            - `name` string, required: The platform’s display name.
            - `category` 'social' | 'messaging' | 'website' | 'identifier', required: How the entry page groups it.
            - `value` string, nullable, required: The handle as stored (a username, an id, a URL). Null for an email address, which is never published as data.
            - `display` string, nullable, required: The label the entry page shows instead of the value, if an editor set one. Null for email.
            - `url` string, nullable, required: The profile’s address, built from the platform’s URL pattern. Null for email.
            - `verified` boolean, required: Verified Handles has checked that this account belongs to the entry.
            - `checked` object: What Verified Handles’ own handle checker found when it last looked at this account, from the platform’s official API: only on YouTube (channel and handle), Deezer and GitHub, and only for a look at most 7 days old. Absent otherwise. The entry page shows it only for `dead` (“Not found when checked …”) and `renamed`.
              - …
      - object
        - `key` string, required: The key as asked for, trimmed.
        - `status` 'not_found', required: No public entry answers to the key: where the single read answers 404.

## Other responses

- `304`: Unchanged since the ETag sent in `If-None-Match`. No body.
- `400`: `ids_required`: no keys. `too_many_ids`: more than `max` keys after removing repeats. `ids_too_long`: `ids` is over `max` characters.
- `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)