get_entity_state
Return what is true RIGHT NOW about one A-share listed company or one shareholder entity, folded from its regulatory filings: pending and executed share-reduction plans, administrative-penalty proceedings, and exchange inquiry letters. Call this when you need the current situation of a specific subject — for example 'is this shareholder still selling', 'is this company under investigation', 'has it replied to the inquiry letter'.
Do NOT call this to find out what happened across the market recently — use scan_recent_events or whats_new for that. Do NOT pass both (code, market) and aent_; pick one addressing mode.
Read the response in this order and stop at the first match: (1) found=false -> we do not cover this security/entity, do not retry; (2) visibility='hidden_unverified' -> the entity exists but its identity is not human-verified, so its name is withheld; query by code+market instead; (3) resolved_as='listed_company' -> your aent_ denoted the company itself and the request was redirected, use the returned code/market; (4) has_events=false -> the security EXISTS but had no covered filings in the covered period (this is the common case, ~85% of valid lookups) — report 'no filings in period', never 'company not found'; (5) companies=[...] -> a shareholder active across one or more companies, read each entry; (6) otherwise the state machines apply to that one company.
Fields that separate 'did not happen' from 'we do not know' are load-bearing: current_holding_reason, window_status ('expired_no_closure' = the plan window lapsed with no closing filing), entity_link, entities_status, plan_pairing ('unresolved' = several open plans and we refuse to guess the pairing), and unclassified_count. Never collapse them into 'nothing there'. Values are objective extractions with a source PDF link; we never rate, score or attribute.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Security code, e.g. '000029'. Must be given together with market. | |
| aent_ | No | Opaque entity id taken from a previous response. Never construct or guess one. Mutually exclusive with code/market. | |
| locale | No | Language of human-readable data labels only; errors and this description are always English. | en |
| market | No | One of ['SH', 'SZ', 'BJ']. Required when code is given. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| found | Yes | False means we do not have this security/entity at all. | |
| reason | No | Present only when found=false: 'unknown_security' or 'unknown_entity'. | |
| companies | No | Present for shareholder entities: one entry per company, each carrying the same state machines. An empty list means the entity exists but has no linked filings — not that the person did nothing. | |
| disclaimer | Yes | Always present. Objective facts only, no ratings. | |
| has_events | No | False means the security EXISTS but has no filings of the covered types in the covered period. This is NOT the same as found=false. | |
| visibility | No | Entity exists but its identity is not human-verified; its name and linked filings are withheld. Query by (code, market) instead. | |
| resolved_as | No | The aent_ you passed denotes the listed company itself; the request was redirected. Use the returned code/market to attribute this state. | |
| coverage_since | No | Earliest filing date we cover. Data before this is absent. |