---
title: "Entities"
method: POST
path: "/v1/entities/{entity_id}"
tags: ["API v1", "Entities"]
---

# Entities

`POST /v1/entities/{entity_id}`

Get typed entity data by its numeric UUID — company, person, place, law, financial instrument, and
more (the schema spans many domains, illustrative not exhaustive) — in two modes:


- **Coarse (no body):** returns only the default property set. No relationships, no numerical
  observations. Use only when a rough profile is enough.

- **Projection (body):** name exact `properties`, `relationships`, and `numerical_observations` to
  get back. The only way to get relationships or time-series data, and the most token-efficient
  read. Available fields vary by entity type and must be *queryable* for that specific entity — run
  `entity_introspection` first to discover them; projecting blind wastes round-trips and may hit
  empty or non-queryable edges.


Pass the entity UUID in the URL path (e.g. `POST /entities/{entity_id}`). Optionally send a JSON body
to specify which properties and relationships to return; if omitted, default properties are returned.

Examples (path + optional body):

`POST /entities/c6772802-bdbc-4778-91e9-cd3d27d008d5`

Optional body: `{"properties": ["name", "aliases", "registered_address", "employee_count"], "relationships": {"outgoing": {"IS_ULTIMATE_PARENT": {"limit": 5}}, "incoming": {"IS_CEO_OF": {}}}}`


Use this when: You already have an entity UUID (from `entity_search`, `knowledge_search`, or `knowledge_query`
results) and need entity data. Use `entity_search` first if you only have a name, and `entity_introspection`
first if you need a projection.

## Path parameters

- `entity_id` string, uuid, required

## Request body

- EntityQuery
  - `properties` string[] — List of entity property names to query
  - `relationships` EntityQueryRelationships
    - `outgoing` object — Outgoing relationship
    - `incoming` object — Incoming relationship
  - `numerical_observations` object — UUIDs of the numerical observations to query

## Response `200`

Successful Response

- GetEntityResponse — Response containing full entity profile
  - `id` string, uuid, required — The ID of the entity
  - `name` string, required — The name of the entity
  - `entity_type` 'Entity' | 'Animal' | 'Award' | 'Organization' | 'Company' | 'EducationalInstitution' | 'IntergovernmentalOrganization' | 'Person' | 'Event' | 'GPE' | 'Country' | 'CountrySubdivision' | 'DependentTerritory' | 'Municipality' | 'Continent' | 'Currency' | 'Industry' | 'FinancialMetric' | 'Group' | 'CorporateEvent' | 'PrivateCompanyFundingRound' | 'Facility' | 'Location' | 'Organism' | 'Plant' | 'Product' | 'Sanction' | 'WorkOfArt' | 'Law' | 'Language' | 'Exchange' | 'Future' | 'Commodity' | 'PositioningMetric' | 'MacroIndicatorPublication' | 'MacroIndicator' | 'ForeignExchangeRate' | 'CountryRegion', required — The type of the entity
  - `description` string, nullable — A short description of the entity
  - `properties` object, required — List of property names available for this entity (e.g. id, name, currency).
  - `relationships` EntityRelationships, required — Outgoing and incoming relationship types for an entity.
    - `outgoing` object — Outgoing relationship type names.
    - `incoming` object — Incoming relationship type names.
  - `numerical_observations` unknown[] — Numerical observations keyed by observation type.
    - unknown

## Other responses

- `422` — Validation Error
- `429` — Too many requests (rate limit exceeded)

---

[API](https://skmtc.net/cala/apis/cala-ai.md) · [All operations](https://skmtc.net/cala/apis/cala-ai/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cala/cala-ai/versions/ee1ba9729aeb/schema)