Concepts
Reading a response
A tool's result holds one or more pieces of JSON text in its content. Every piece has the same envelope, so a client reads a filing, a funding rate and a thesis the same way.
The envelope
An insider sale, as get_filings returns it:
{
"entity": { "figi": "BBG000B9XRY4", "cik": "0000320193", "ticker": "AAPL", "name": "Apple Inc." },
"type": "insider_trade",
"direction": "backward",
"event_time": "2026-10-02",
"as_of": "2026-10-05",
"confidence": "confirmed",
"source": {
"name": "SEC EDGAR Form 4",
"url": "https://www.sec.gov/Archives/edgar/data/320193/000114036126038674/",
"license": "public"
},
"data": { "insider_title": "Executive Chair", "txn_code": "S", "shares": 40879, "price": 333.94, "value": 13651133.26 }
}Fields
| Field | Meaning |
|---|---|
entity | The company: ticker, SEC cik, figi and name where known. Perps results name the market. |
type | What the piece is: insider_trade, corporate_event, dividend, valuation, thesis_impact, perps and others. data is shaped by it. |
direction | backward for something that happened, forward for something scheduled or projected. |
event_time | When it happened, or is due to happen. |
as_of | When it became known: the filing or disclosure time, or when a market reading was taken. Kept apart from event_time, because a trade can be filed days after it was made. |
confidence | How sure the fact is; see below. |
source | Where it came from: name, a url to the record itself, and license: public for a public record, computed for OptimistFi's own read of public data. |
data | The fact itself. |
Confidence
| Field | Meaning |
|---|---|
confirmed | Read from a filing or an official record. |
estimated | Derived rather than stated: a next earnings date projected from the company's own filing pattern, or OptimistFi's read of the evidence. A date that is only projected is never marked confirmed. |
reported | As a trading venue publishes it: perpetual futures prices, funding and open interest. |
Absence and gaps
An empty list means the server looked and found nothing. When it could not look, because a source did not answer or a company is not covered yet, the result says so with an error that carries looked: false, so no answer is ever read as “nothing happened” by mistake. See Errors and limits.
When presenting a result, keep its source and dates beside the claim. They are what lets a reader check it.