> ## Documentation Index
> Fetch the complete documentation index at: https://docs.particle.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Search entities

> 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.



## OpenAPI

````yaml /openapi.json get /v1/entities/search
openapi: 3.1.0
info:
  description: Public API for Particle — news intelligence, financial data, and analysis.
  title: Particle API
  version: 0.1.0
servers:
  - url: https://api.particle.pro
security:
  - ApiKeyHeader: []
  - BearerAuth: []
paths:
  /v1/entities/search:
    get:
      tags:
        - Entities
        - tier:standard
      summary: Search entities
      description: >-
        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.
      operationId: search-entities
      parameters:
        - description: Results per page
          explode: false
          in: query
          name: limit
          schema:
            default: 25
            description: Results per page
            format: int64
            maximum: 100
            minimum: 1
            type: integer
        - description: Opaque pagination cursor from previous response
          explode: false
          in: query
          name: cursor
          schema:
            description: Opaque pagination cursor from previous response
            type: string
        - description: >-
            Free-text query: a name, partial name, nickname, stock ticker,
            @handle, or website domain (e.g. 'sam altman', 'coca cola', 'AAPL',
            '@sama', 'apple.com').
          explode: false
          in: query
          name: q
          required: true
          schema:
            description: >-
              Free-text query: a name, partial name, nickname, stock ticker,
              @handle, or website domain (e.g. 'sam altman', 'coca cola',
              'AAPL', '@sama', 'apple.com').
            minLength: 1
            type: string
        - description: >-
            Restrict results to one kind. Omit to search people, companies, and
            knowledge graph entities together.
          explode: false
          in: query
          name: type
          schema:
            description: >-
              Restrict results to one kind. Omit to search people, companies,
              and knowledge graph entities together.
            enum:
              - person
              - company
              - knowledge_graph_entity
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageEntitySearchHit'
          description: OK
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/PlatformError'
          description: Error
      x-codeSamples:
        - label: cURL
          lang: curl
          source: |-
            curl -H "X-API-Key: $PARTICLE_API_KEY" \
              "https://api.particle.pro/v1/entities/search?limit=25&q=%3Cq%3E"
components:
  schemas:
    PageEntitySearchHit:
      additionalProperties: false
      properties:
        cursor:
          description: Pass to next request for more results
          type: string
        data:
          description: List of results
          items:
            $ref: '#/components/schemas/EntitySearchHit'
          type:
            - array
            - 'null'
        has_more:
          description: Whether more results exist
          type: boolean
      required:
        - data
        - has_more
      type: object
    PlatformError:
      additionalProperties: false
      properties:
        detail:
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
          examples:
            - Property foo is required but is missing.
          type: string
        error_code:
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
            - array
            - 'null'
        instance:
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem.
          examples:
            - https://example.com/error-log/abc123
          format: uri
          type: string
        resolve:
          $ref: '#/components/schemas/ErrorResolve'
        status:
          description: HTTP status code
          examples:
            - 400
          format: int64
          type: integer
        title:
          description: >-
            A short, human-readable summary of the problem type. This value
            should not change between occurrences of the error.
          examples:
            - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
            - https://example.com/errors/example
          format: uri
          type: string
      type: object
    EntitySearchHit:
      additionalProperties: false
      properties:
        company:
          $ref: '#/components/schemas/CompanyCompact'
          description: The matched company (when type is 'company').
        knowledge_graph_entity:
          $ref: '#/components/schemas/Entity'
          description: >-
            The matched knowledge graph entity (when type is
            'knowledge_graph_entity').
        match_quality:
          description: >-
            How confidently the result matched the query, strongest to weakest:
            'exact' (a name, identifier, or known alias equals the query),
            'strong' (every query word is present), 'fuzzy' (a typo-tolerant
            similarity match), 'description' (matched only the description
            text), 'speculative' (a weak remaining match). Auto-select the top
            hit on 'exact'; otherwise let the user confirm.
          enum:
            - exact
            - strong
            - fuzzy
            - description
            - speculative
          type: string
        mentions:
          $ref: '#/components/schemas/EntityMentions'
          description: >-
            Where this entity shows up — both a popularity signal and a cue for
            confirming the match is the entity you meant.
        person:
          $ref: '#/components/schemas/PersonCompact'
          description: The matched person (when type is 'person').
        social_links:
          description: >-
            Third-party social profiles (people & companies), with follower
            counts where known — confirms the match.
          items:
            $ref: '#/components/schemas/EntitySocialLink'
          type:
            - array
            - 'null'
        type:
          description: >-
            Which kind of result this is, and which embedded field is populated:
            'person' → /v1/people, 'company' → /v1/companies,
            'knowledge_graph_entity' → /v1/entities.
          enum:
            - person
            - company
            - knowledge_graph_entity
          type: string
      required:
        - type
        - match_quality
        - mentions
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ErrorResolve:
      additionalProperties: false
      properties:
        action:
          type: string
        endpoint:
          type: string
        message:
          type: string
        method:
          type: string
        url:
          type: string
      required:
        - message
      type: object
    CompanyCompact:
      additionalProperties: false
      properties:
        description:
          description: Short company description, when known.
          type: string
        domain:
          description: Primary website domain (e.g. 'nvidia.com'), when known.
          type: string
        id:
          description: Company identifier (domain, slug, or encoded ID)
          type: string
        image_url:
          description: Company logo or image URL
          type: string
        name:
          description: Company name
          type: string
        slug:
          description: >-
            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.
          type: string
        ticker:
          description: Primary stock ticker symbol, when listed.
          type: string
      required:
        - id
        - name
      type: object
    Entity:
      additionalProperties: false
      properties:
        company:
          $ref: '#/components/schemas/EntityCompany'
          description: Linked company record, if this entity is a known company
        description:
          description: Short description
          type: string
        id:
          description: Unique identifier
          type: string
        image_url:
          description: Entity image URL
          type: string
        name:
          description: Entity name
          type: string
        person:
          $ref: '#/components/schemas/EntityPerson'
          description: Linked person record, if this entity is a known person
        slug:
          description: Human-readable slug identifier
          type: string
        type:
          $ref: '#/components/schemas/EntityType'
          description: Category. Omitted when the entity falls outside the supported set.
        wikipedia_url:
          description: Wikipedia URL
          type: string
      required:
        - id
        - slug
        - name
      type: object
    EntityMentions:
      additionalProperties: false
      properties:
        news_articles:
          description: News articles covering this entity — a secondary popularity signal.
          format: int64
          type: integer
        podcast_episodes:
          description: >-
            Distinct podcast episodes mentioning this entity — the primary
            popularity signal.
          format: int64
          type: integer
      required:
        - podcast_episodes
        - news_articles
      type: object
    PersonCompact:
      additionalProperties: false
      properties:
        description:
          description: Short description (e.g. current role), when known.
          type: string
        id:
          description: Encoded Person identifier
          type: string
        image_url:
          description: Canonical headshot URL when one is known for the Person
          type: string
        name:
          description: Display name
          type: string
        slug:
          description: >-
            Stable human-readable handle (e.g. 'satya-nadella'). Recommended
            canonical identifier on every Particle Pro person surface.
          type: string
      required:
        - id
        - name
      type: object
    EntitySocialLink:
      additionalProperties: false
      properties:
        followers:
          description: >-
            Audience size where recorded (followers, or subscribers for video
            platforms); omitted when unknown.
          format: int64
          type: integer
        platform:
          description: Platform slug (e.g. 'twitter', 'instagram', 'youtube').
          type: string
        url:
          description: Profile URL.
          type: string
      required:
        - platform
        - url
      type: object
    EntityCompany:
      additionalProperties: false
      properties:
        domain:
          description: Company website domain
          type: string
        id:
          description: Company identifier
          type: string
        ticker:
          description: Primary stock ticker symbol
          type: string
      required:
        - id
      type: object
    EntityPerson:
      additionalProperties: false
      properties:
        company:
          description: Current company name
          type: string
        id:
          description: Person identifier
          type: string
        image_url:
          description: Person headshot URL
          type: string
        title:
          description: Current role title
          type: string
      required:
        - id
      type: object
    EntityType:
      additionalProperties: false
      properties:
        name:
          description: Human-friendly display label (e.g. 'Company').
          type: string
        slug:
          description: >-
            Stable identifier, safe to pass to the type query parameter (e.g.
            'company').
          type: string
      required:
        - slug
        - name
      type: object
  securitySchemes:
    ApiKeyHeader:
      description: Pass your API key in the X-API-Key header (recommended).
      in: header
      name: X-API-Key
      type: apiKey
    BearerAuth:
      description: Pass your API key as a Bearer token in the Authorization header.
      scheme: bearer
      type: http

````