> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gildea.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List Entities
> Retrieve a paginated list of entities with trend stats
Filter by theme label (see [Themes](/concepts/themes) for valid labels). An unknown label returns `404`, not an empty list.
Filter by entity type (e.g., `organization`, `person`, `model`, `hardware`, `other`). See [Entities](/concepts/entities) for all 8 types.
Filter entities by name (matches names containing this text). For natural-language semantic retrieval, use [`GET /v1/search`](/api-reference/search/search).
Sort field: `signal_count`, `first_seen`, `trend`.
Filter by trend direction: `Rising`, `Stable`, `Declining`, `New`.
Filter by trend significance: `Significant`, `Insignificant`.
Filter by coverage consistency: `Volatile`, `Steady`.
Filter by share-of-voice scale: `Large`, `Medium`, `Small`.
Filter by notability: `High`, `Medium`, `Low`, `Negligible`.
Results per page (1-50).
Opaque pagination cursor from a previous response.
List of entity objects.
Stable, opaque public entity ID (e.g., `gld:/a1b2c3d4e5f6`).
Human-readable entity name.
Entity type (e.g., `organization`, `model`). See [Entities](/concepts/entities) for all 8 types.
Total signals mentioning this entity.
ISO 8601 date of first mention.
ISO 8601 date of most recent mention.
Trend analytics. See [Entities](/concepts/entities#trend-analytics) for field descriptions.
`Large`, `Medium`, or `Small`.
`Rising`, `Stable`, `Declining`, or `New`. Null if fewer than 8 mentions.
`High`, `Medium`, `Low`, or `Negligible`. How much this entity warrants attention right now.
Explanation of the notability assignment.
Signal count by content type (e.g., `{"analysis": 90, "event": 66}`).
Signal count by value chain theme (e.g., `{"Infrastructure": 80}`).
Signal count by market force theme (e.g., `{"Competitive Dynamics": 70}`).
Whether more results exist.
Cursor for the next page.
```bash cURL theme={null}
# List organizations
curl -H "X-API-Key: gld_your_key" \
"https://api.gildea.ai/v1/entities?type=organization&limit=10"
# Find rising entities with statistical significance
curl -H "X-API-Key: gld_your_key" \
"https://api.gildea.ai/v1/entities?direction=Rising&confidence=Significant&sort=trend&limit=10"
```
```python Python theme={null}
import requests
headers = {"X-API-Key": "gld_your_key"}
# List organizations
resp = requests.get(
"https://api.gildea.ai/v1/entities",
headers=headers,
params={"type": "organization", "limit": 10},
)
entities = resp.json()
# Find rising entities with statistical significance
resp = requests.get(
"https://api.gildea.ai/v1/entities",
headers=headers,
params={"direction": "Rising", "confidence": "Significant", "sort": "trend", "limit": 10},
)
rising = resp.json()
```
```javascript JavaScript theme={null}
const headers = { "X-API-Key": "gld_your_key" };
// List organizations
const resp = await fetch(
"https://api.gildea.ai/v1/entities?type=organization&limit=10",
{ headers }
);
const entities = await resp.json();
// Find rising entities with statistical significance
const rising = await fetch(
"https://api.gildea.ai/v1/entities?direction=Rising&confidence=Significant&sort=trend&limit=10",
{ headers }
).then(r => r.json());
```
```json 200 theme={null}
{
"entities": [
{
"entity_id": "gld:/a1b2c3d4e5f6",
"name": "NVIDIA",
"type": "organization",
"signal_count": 156,
"first_seen": "2025-10-03T00:00:00Z",
"last_seen": "2026-02-14T00:00:00Z",
"trend": {
"share_of_voice": 0.12,
"streak": 4,
"current_week": 15,
"prior_week": 10,
"source_diversity": 12
},
"scale": "Large",
"direction": "Rising",
"confidence": "Significant",
"stability": "Steady",
"notability": "High",
"notability_reasoning": "Large-scale entity with confirmed upward trend and consistent coverage; notable upward shift reliably gaining share.",
"content_type_mix": {"analysis": 90, "event": 66},
"value_chain_distribution": {"Infrastructure": 80, "Foundation Models": 45},
"market_force_distribution": {"Competitive Dynamics": 70, "Capital & Investment": 50}
}
],
"has_more": true,
"next_cursor": "eyJzaWduYWxfY291bnQiOjE1Nn0="
}
```
## OpenAPI
````yaml GET /v1/entities
openapi: 3.1.0
info:
title: Gildea API
description: >-
Market intelligence on the AI economy, built for agents. Gildea ingests
expert sources (podcasts, essays, VC memos, X posts, research papers, news)
and decomposes them into verified, source-cited atomic facts: thesis
sentences, argument sentences, summary sentences, and claims.
**Key capabilities:**
- Verified atomic facts with verbatim source citations
- Entity intelligence with trend analytics across 8 entity types
- Theme taxonomy (6 value-chain segments + 6 market forces)
- Search verified text units by free-text query or by similarity to a known
unit
Only `verdict=pass` data is served. Every claim cites the source evidence it
was extracted from.
version: 0.1.0
servers:
- url: https://api.gildea.ai
description: Production
- url: http://localhost:8000
description: Local development
security:
- ApiKeyAuth: []
tags:
- name: signals
description: >-
Market intelligence signals — articles decomposed into verified text
units.
- name: entities
description: >-
Entity intelligence — companies, people, and products with trend
analytics.
- name: themes
description: Taxonomy themes — value chain segments and market forces with trend stats.
- name: search
description: >-
Search Gildea's verified text units — text queries or similarity to a
known unit.
- name: health
description: Service health and status.
- name: admin
description: Administrative operations (requires admin secret).
paths:
/v1/entities:
get:
tags:
- entities
summary: List entities
description: >-
Retrieve a paginated list of entities with trend stats and theme
distributions.
operationId: list_entities_v1_entities_get
parameters:
- name: theme
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter by theme label (see GET /v1/themes for valid labels). An
unknown label returns 404, not an empty list.
title: Theme
description: >-
Filter by theme label (see GET /v1/themes for valid labels). An
unknown label returns 404, not an empty list.
- name: type
in: query
required: false
schema:
anyOf:
- enum:
- organization
- person
- model
- hardware
- location
- event
- regulation_policy
- other
type: string
- type: 'null'
description: >-
Filter by entity type: 'organization', 'person', 'model',
'hardware', 'location', 'event', 'regulation_policy', 'other'.
title: Type
description: >-
Filter by entity type: 'organization', 'person', 'model',
'hardware', 'location', 'event', 'regulation_policy', 'other'.
- name: name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Filter entities by name (matches names containing this text). For
natural-language semantic retrieval, use GET /v1/search.
title: Name
description: >-
Filter entities by name (matches names containing this text). For
natural-language semantic retrieval, use GET /v1/search.
- name: sort
in: query
required: false
schema:
enum:
- signal_count
- first_seen
- trend
type: string
description: 'Sort field: ''signal_count'', ''first_seen'', ''trend''.'
default: signal_count
title: Sort
description: 'Sort field: ''signal_count'', ''first_seen'', ''trend''.'
- name: direction
in: query
required: false
schema:
anyOf:
- type: string
enum:
- Rising
- Stable
- Declining
- New
- type: 'null'
description: 'Filter by direction: ''Rising'', ''Stable'', ''Declining'', ''New''.'
title: Direction
description: 'Filter by direction: ''Rising'', ''Stable'', ''Declining'', ''New''.'
- name: confidence
in: query
required: false
schema:
anyOf:
- type: string
enum:
- Significant
- Insignificant
- type: 'null'
description: 'Filter by confidence: ''Significant'', ''Insignificant''.'
title: Confidence
description: 'Filter by confidence: ''Significant'', ''Insignificant''.'
- name: stability
in: query
required: false
schema:
anyOf:
- type: string
enum:
- Volatile
- Steady
- type: 'null'
description: 'Filter by stability: ''Volatile'', ''Steady''.'
title: Stability
description: 'Filter by stability: ''Volatile'', ''Steady''.'
- name: scale
in: query
required: false
schema:
anyOf:
- type: string
enum:
- Large
- Medium
- Small
- type: 'null'
description: 'Filter by scale: ''Large'', ''Medium'', ''Small''.'
title: Scale
description: 'Filter by scale: ''Large'', ''Medium'', ''Small''.'
- name: notability
in: query
required: false
schema:
anyOf:
- type: string
enum:
- High
- Medium
- Low
- Negligible
- type: 'null'
description: 'Filter by notability: ''High'', ''Medium'', ''Low'', ''Negligible''.'
title: Notability
description: 'Filter by notability: ''High'', ''Medium'', ''Low'', ''Negligible''.'
- name: cursor
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Opaque cursor from a previous response's `next_cursor`. Omit for
the first page.
title: Cursor
description: >-
Opaque cursor from a previous response's `next_cursor`. Omit for the
first page.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 50
minimum: 1
description: >-
Page size (1–50, default 25). These endpoints are
cursor-paginated: pass the returned `next_cursor` as `cursor` to
walk the full result set. (Relevance-ranked GET /v1/search is not
paginated — its `limit` is the total top-N returned, not a page
size.)
default: 25
title: Limit
description: >-
Page size (1–50, default 25). These endpoints are cursor-paginated:
pass the returned `next_cursor` as `cursor` to walk the full result
set. (Relevance-ranked GET /v1/search is not paginated — its `limit`
is the total top-N returned, not a page size.)
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EntityListResponse'
type: object
additionalProperties: true
title: Response List Entities V1 Entities Get
'401':
description: Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
EntityListResponse:
properties:
entities:
items:
$ref: '#/components/schemas/EntityProfile'
type: array
title: Entities
description: Entity profiles matching the query.
has_more:
type: boolean
title: Has More
description: Whether more results are available beyond this page.
next_cursor:
anyOf:
- type: string
- type: 'null'
title: Next Cursor
description: Cursor for the next page; null when `has_more` is false.
type: object
required:
- entities
- has_more
title: EntityListResponse
ErrorResponse:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
EntityProfile:
properties:
entity_id:
type: string
title: Entity Id
description: Stable public entity ID.
examples:
- gld:/a1b2c3d4e5f6
name:
type: string
title: Name
description: Canonical display name.
examples:
- NVIDIA
type:
type: string
title: Type
description: Entity type.
examples:
- organization
signal_count:
type: integer
title: Signal Count
description: Total signals mentioning this entity.
first_seen:
anyOf:
- type: string
- type: 'null'
title: First Seen
description: Earliest signal mention (ISO date).
last_seen:
anyOf:
- type: string
- type: 'null'
title: Last Seen
description: Most recent signal mention (ISO date).
trend:
$ref: '#/components/schemas/EntityTrend'
content_type_mix:
additionalProperties:
type: integer
type: object
title: Content Type Mix
value_chain_distribution:
additionalProperties:
type: integer
type: object
title: Value Chain Distribution
market_force_distribution:
additionalProperties:
type: integer
type: object
title: Market Force Distribution
scale:
anyOf:
- type: string
enum:
- Large
- Medium
- Small
- type: 'null'
title: Scale
description: 'Interpretation: relative scale.'
direction:
anyOf:
- type: string
enum:
- Rising
- Stable
- Declining
- New
- type: 'null'
title: Direction
description: 'Interpretation: trend direction.'
confidence:
anyOf:
- type: string
enum:
- Significant
- Insignificant
- type: 'null'
title: Confidence
description: 'Interpretation: statistical confidence.'
stability:
anyOf:
- type: string
enum:
- Volatile
- Steady
- type: 'null'
title: Stability
description: 'Interpretation: signal stability.'
notability:
anyOf:
- type: string
enum:
- High
- Medium
- Low
- Negligible
- type: 'null'
title: Notability
description: 'Interpretation: foreground vs background.'
notability_reasoning:
anyOf:
- type: string
- type: 'null'
title: Notability Reasoning
type: object
required:
- entity_id
- name
- type
- signal_count
- trend
title: EntityProfile
ErrorDetail:
properties:
code:
type: string
title: Code
description: Machine-readable error code.
examples:
- not_found
message:
type: string
title: Message
description: Human-readable error description.
examples:
- Signal '0001f3a7b9c8d4e5f6a7b8c9d0e1f2a3b4c5d6e7' not found
status:
type: integer
title: Status
description: HTTP status code.
examples:
- 404
field:
anyOf:
- type: string
- type: 'null'
title: Field
description: 'For validation errors: path to the offending parameter.'
examples:
- body.text
request_id:
anyOf:
- type: string
- type: 'null'
title: Request Id
description: Correlation id (also on the X-Request-Id response header).
retry_after:
anyOf:
- type: integer
- type: 'null'
title: Retry After
description: >-
Seconds to wait before retrying (mirrors the Retry-After header).
Present on 429 (rate limited) and 503 (temporarily unavailable).
reset:
anyOf:
- type: integer
- type: 'null'
title: Reset
description: >-
Unix epoch seconds when the exceeded rate-limit window resets.
Present on 429.
type: object
required:
- code
- message
- status
title: ErrorDetail
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
EntityTrend:
properties:
share_of_voice:
type: number
title: Share Of Voice
description: Share of total corpus over the trailing window (0–1).
examples:
- 0.12
streak:
type: integer
title: Streak
description: Consecutive weeks of growth.
examples:
- 4
current_week:
type: integer
title: Current Week
description: Signal count in the current week.
examples:
- 15
prior_week:
type: integer
title: Prior Week
description: Signal count in the prior week.
examples:
- 10
source_diversity:
type: integer
title: Source Diversity
description: Distinct source domains mentioning this entity.
examples:
- 12
type: object
required:
- share_of_voice
- streak
- current_week
- prior_week
- source_diversity
title: EntityTrend
description: >-
Legible trend counts. Raw estimators (Theil-Sen, Mann-Kendall, etc.) are
not exposed — the interpretation fields (scale/direction/...) summarize
them.
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
API key for authentication. Include in every request as `X-API-Key:
gld_your_key_here`.
````