---
title: "Retrieve Entity"
method: POST
path: "/v0/search/retrieve_entity"
tags: ["V0", "Search", "HAS_MCP_EQUIVALENT"]
---

# Retrieve Entity

`POST /v0/search/retrieve_entity`

## Request

- Base URL: `https://api.ultralayer.ai`
- URL: `https://api.ultralayer.ai/v0/search/retrieve_entity`
- Auth: HTTP bearer

Realtime context package for one entity.

## Request body

- RetrieveEntityParams
  - `entity` string, required: Entity name

## Response `200`

Successful Response

- EntityDataPackage: Realtime context package for one Ultralayer entity.
  - `timestamp` string, date-time, required: Canonical system timestamp when this package was assembled.
  - `entity` EntitySummary, required: Resolved entity identity.
    - `entity_id` integer, required: Root entity id.
    - `canonical_name` string, required: Root entity name.
    - `entity_type` string, nullable, required
  - `recent_wire_items` EntityRecentWireItem[], required: Most recent non-duplicate wire items where this entity is primary or significant.
    - `wire_id` integer, required
    - `source_timestamp` string, date-time, required
    - `headline` string, required: Wire headline.
    - `novelty` 'new' | 'update' | 'correction', required: Novelty label.
    - `relevance` 'primary' | 'significant', required: Entity relevance.
  - `sentiment_chart` EntitySentimentBar[], required: Calendar-day bars (oldest first). Empty days are null, not omitted.
    - `end_timestamp` string, date-time, required: Exclusive end of this UTC calendar-day bar.
    - `weighted_sentiment` number, nullable, required: Relevance-weighted average sentiment in [-1, 1] for the day. Null when there were no observations.
    - `weighted_std` number, nullable, required: Relevance-weighted standard deviation of sentiment for the day. Null when there were no observations.
    - `mention_count` integer, required: Number of wire items contributing to this bar.
  - `co_mentions` EntityCoMention[], required: Top co-mentioned entities from a bounded recent sample of primary/significant wire items.
    - `entity_id` integer, required: Entity id of the co-mentioned entity.
    - `canonical_name` string, required: Entity name of the co-mentioned entity.
    - `share` number, required: Fraction of the co-mention sample wire items that also mention this entity at primary or significant relevance.

## Other responses

- `422`: Validation Error

---

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