---
title: "Search entities"
method: GET
path: "/v1/entities/search"
tags: ["Entities", "tier:standard"]
---

# Search entities

`GET /v1/entities/search`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/entities/search`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Find a person, company, or knowledge graph entity by free-text query — a name, partial name, nickname, stock ticker, @handle, or website domain. Returns the best matches ranked by relevance, each tagged with a `match_quality` so you can tell an exact identification from a fuzzy guess. Use it to turn what a user typed into a specific entity — for example before creating an alert to watch it for podcast mentions. Unlike a knowledge graph entity, a result's top-level `type` may be `person`, `company`, or `knowledge_graph_entity`; pass its `id` or `slug` to the matching resource endpoint (/v1/people, /v1/companies, /v1/entities), or its `id` to alert creation.

## Query parameters

- `limit` integer: Results per page
- `cursor` string: Opaque pagination cursor from previous response
- `q` string, required: Free-text query: a name, partial name, nickname, stock ticker, @handle, or website domain (e.g. 'sam altman', 'coca cola', 'AAPL', '@sama', 'apple.com').
- `type` 'person' | 'company' | 'knowledge_graph_entity': Restrict results to one kind. Omit to search people, companies, and knowledge graph entities together.

## Response `200`

OK

- PageEntitySearchHit
  - `cursor` string: Pass to next request for more results
  - `data` EntitySearchHit[], nullable, required: List of results
    - `company` CompanyCompact
      - `description` string: Short company description, when known.
      - `domain` string: Primary website domain (e.g. 'nvidia.com'), when known.
      - `id` string, required: Company identifier (domain, slug, or encoded ID)
      - `image_url` string: Company logo or image URL
      - `name` string, required: Company name
      - `slug` string: Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Companies have no slug of their own; prefer this for display and pass it (or id) to /v1/companies.
      - `ticker` string: Primary stock ticker symbol, when listed.
    - `knowledge_graph_entity` Entity
      - `company` EntityCompany
        - `domain` string: Company website domain
        - `id` string, required: Company identifier
        - `ticker` string: Primary stock ticker symbol
      - `description` string: Short description
      - `id` string, required: Unique identifier
      - `image_url` string: Entity image URL
      - `name` string, required: Entity name
      - `person` EntityPerson
        - `company` string: Current company name
        - `id` string, required: Person identifier
        - `image_url` string: Person headshot URL
        - `title` string: Current role title
      - `slug` string, required: Human-readable slug identifier
      - `type` EntityType
        - `name` string, required: Human-friendly display label (e.g. 'Company').
        - `slug` string, required: Stable identifier, safe to pass to the type query parameter (e.g. 'company').
      - `wikipedia_url` string: Wikipedia URL
    - `match_quality` 'exact' | 'strong' | 'contained' | 'fuzzy' | 'description' | 'speculative', required: How confidently the result matched the query, strongest to weakest: 'exact' (a name, identifier, or known alias equals the query, and a query written as separate words also matches a name written as one — 'open ai' is OpenAI; a name ranks ahead of an alias of similar popularity), 'strong' (every query word is present, or the query is an alias of 3 or fewer characters, or an all-caps code of up to 6 characters, such as 'SAM', that several entities share), 'contained' (the result's whole name appears inside a longer query — the query likely names several things; let the user pick), 'fuzzy' (a typo-tolerant similarity match), 'description' (matched only the description text), 'speculative' (a weak remaining match). Auto-select the top hit when it is the only 'exact' result and has_more is false (or a later page holds no other 'exact' result); when several are 'exact' (name twins such as 'Mercury'), or the top hit is weaker, let the user confirm.
    - `mentions` EntityMentions, required
      - `news_articles` integer, required: News articles covering this entity — a secondary popularity signal.
      - `podcast_episodes` integer, required: Distinct podcast episodes mentioning this entity — the primary popularity signal.
    - `person` PersonCompact
      - `description` string: Short description (e.g. current role), when known.
      - `id` string, required: Encoded Person identifier
      - `image_url` string: Canonical headshot URL when one is known for the Person
      - `name` string, required: Display name
      - `slug` string: Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface.
    - `social_links` EntitySocialLink[], nullable: Third-party social profiles (people & companies), with follower counts where known — confirms the match.
      - `followers` integer: Audience size where recorded (followers, or subscribers for video platforms); omitted when unknown.
      - `platform` string, required: Platform slug (e.g. 'twitter', 'instagram', 'youtube').
      - `url` string, required: Profile URL.
    - `type` 'person' | 'company' | 'knowledge_graph_entity', required: Which kind of result this is, and which embedded field is populated: 'person' → /v1/people, 'company' → /v1/companies, 'knowledge_graph_entity' → /v1/entities.
  - `has_more` boolean, required: Whether more results exist

## Other responses

- `402`: Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent.
- `default`: Error

---

[API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)