Insights
🔍 Insights API¶
Welcome to the Insights API! Insights automatically alert users about potential movements within their portfolios. They are generated by analyzing over 250 underlying indicators across 40,000 global assets to highlight fundamental, technical, macro, and market movements.
Insights show users the condition that is occurring to the asset and the price movement that has historically occurred over different time horizons as a result of that condition.
This documentation guides you through accessing our Insights endpoints, whether you need to retrieve a filtered collection of insights or access details about a specific insight.
🔐 Authentication¶
Our API uses token-based authentication. For details on how to obtain and use your API key, please refer to the Authentication section
🔌 Endpoints¶
1. Get Filtered Insights¶
This endpoint allows you to retrieve insights based on a specific filter criteria specified in the request, such as topics, asset classes, direction, and more.
Endpoint: POST /insights/v1/filter
The Filter Insights request section defines the structure and allowable fields for filtering. If no filter is provided, the API returns the latest insights. Specifically, the from_date field in the filter schema defaults to 6 months before the current date if not explicitly provided, allowing users to retrieve recent insights within the past six months.
Use the page and limit parameters to navigate through the results. Pagination allows you to retrieve a subset of insights per request, reducing the load for large datasets. If these parameters are not provided, the default is set to the first page (page=0) with a limit of 20 items per page (limit=20).
Example: To retrieve the second page of results with 30 items per page, set page=1 and limit=30.
Filter Insights Request¶
Parameters
topicarray of string
The request retrieves insights that match any of the provided topics.
asset_clsarray of enum (integer)
The request retrieves insights that match any of the provided asset classes.
classarray of enum (integer)
The request retrieves insights that match any of the provided classes.
directionarray of enum (integer)
The request retrieves insights with the specified direction.
ecoarray of string
The request retrieves insights that match any of the provided economies.
entityarray of string
The request retrieves insights that match any of the provided entities.
horizonarray of string
The request retrieves insights that match any of the provided horizons.
last_value__ltenumber
The request retrieves insights with last value less than or equal to provided value.
market_cap_usd_bn__gtenumber
The request retrieves insights with market cap greater than or equal to provided value.
market_cap_usd_bn__ltnumber
The request retrieves insights with market cap less than provided value.
median_return__gtenumber
The request retrieves insights with median greater than or equal to provided value.
median_return__ltnumber
The request retrieves insights with median less than provided value.
sectorarray of string
The request retrieves insights associated with any of the specified sectors.
starsarray of integer
The request returns insights that match any of the specified number of stars.
sub_classarray of enum (integer)
from_datedate-time
The request retrieves insights created after the specified date.
Format: YYYY-MM-DDTHH:MM:SSZ
to_datedate-time
The request retrieves insights created before the specified date.
Format: YYYY-MM-DDTHH:MM:SSZ
pageinteger
Specifies the page number of results to retrieve. Pagination starts at 0 for the first page, allowing you to navigate through the result set.
limitinteger
Defines the maximum number of results to include in each page. It controls the size of the result set returned in a single request. If not specified, the default value is 20.
curl https://api.reflexivity.com/insights/v1/filter \
--header 'Authorization: Bearer {token}' \
--data '{
"from_date": "2024-05-26T00:00:00Z",
"entity": ["tsla_nasd"],
"asset_cls": [1,2]
}'
Filter Insights Response¶
Properties
resultarray of insights (object)
HTTP Status Code Summary |
||
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 400 | Bad Request | The request was unacceptable. |
| 401 | Unauthorized | No valid API key provided. |
| 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request. |
{
result: [
{
"conditions": [
{
"entity": "vz_nyse",
"snake": "vz_nyse.pb_ibes_forward_12m",
"condition": 4,
"value": 1.6915602666024252,
"method_sub_cls": "valuation",
"condition_text": "Verizon (VZ:NYSE) Forward P/B, is below 1.69"
},
{
"entity": "vz_nyse",
"snake": "vz_nyse.ibes_roa_forward_12m.ds",
"condition": 4,
"value": 5.011,
"method_sub_cls": "valuation",
"condition_text": "Verizon (VZ:NYSE) RoA 12m Forward, is below 5.01"
}
],
"episodes": [
{
"start_date": "2008-09-15T00:00:00Z",
"end_date": "2008-10-15T00:00:00Z",
"events": [
{
"date": "2008-09-15T00:00:00Z"
},
{
"date": "2008-09-16T00:00:00Z"
}
]
},
{
"start_date": "2010-02-04T00:00:00Z",
"end_date": "2010-02-12T00:00:00Z",
"events": [
{
"date": "2010-02-04T00:00:00Z"
},
{
"date": "2010-02-05T00:00:00Z"
}
]
},
{
"start_date": "2010-05-06T00:00:00Z",
"end_date": "2010-06-10T00:00:00Z",
"events": [
{
"date": "2010-05-06T00:00:00Z"
},
{
"date": "2010-05-20T00:00:00Z"
}
]
},
{
"start_date": "2023-10-25T00:00:00Z",
"end_date": "2024-01-22T00:00:00Z",
"events": [
{
"date": "2023-10-25T00:00:00Z"
},
{
"date": "2023-10-26T00:00:00Z"
}
]
},
{
"start_date": "2024-07-22T00:00:00Z",
"end_date": "2024-07-22T00:00:00Z",
"events": [
{
"date": "2024-07-22T00:00:00Z"
}
]
}
],
"hit_ratio": {
"1m": {
"median": 3.688099857544813,
"hit_ratio": 90.1639344262295
},
"1w": {
"median": 0.482444384883407,
"hit_ratio": 70.96774193548387
}
},
"metadata": {
"type": "Valuation",
"topic": "Valuations",
"asset_cls": 3,
"class": 9,
"direction": 1,
"eco": "us",
"entity": "vz_nyse",
"event": "",
"horizon": "3m",
"last_value": 42.13,
"last_value_date": "2024-10-31T00:00:00Z",
"market_cap": 177351.5,
"median_return": 0.08230307190760633,
"sector": "sector_communication_services",
"stars": 5,
"sub_cls": 18,
"signal_high": 45.80212930374463,
"signal_low": 40.29393534812769,
"high_conviction_report": {
"cross_business_cycles": true,
"frequent": false,
"high_hit_ratio_in_sample": true,
"high_hit_ratio_out_sample": true,
"high_path_risk_return": true,
"high_pnl_draw_down_ratio": false,
"several_episodes": false,
"sparse": true
},
"hit_rate": 1
},
"id": "9c1117f2-4579-43ca-8ff5-8779ee318c81",
"title": "Verizon's value compared to future book value, or 'Forward Price to Book Ratio', hit a low point of 1.69",
"content": [
{
"section_title": "Overview",
"section_content": "Overview section content"
},
{
"section_title": "Insight Projection",
"section_content": "Insight Projection section content"
},
{
"section_title": "Why It Might Move",
"section_content": "Why It Might Move section content"
},
{
"section_title": "Optimal Trade Horizon",
"section_content": "Optimal Trade Horizon section content"
},
{
"section_title": "Past Performance",
"section_content": "Past Performance section content"
}
],
"disclaimer": "Disclaimer:\nThis communication is issued by Knabble, Inc. and/or affiliates of Knabble, Inc...",
"card": {
"name": "Attractive Valuation",
"intuition": "A cheap stock has a current price that is not justified by its earnings outlook: its price-earnings (P/E) ratio is too low. Consequently, traders often start betting on the price to rise eventually."
},
"created_at": "2024-11-01T11:48:08.260524Z",
"charts": [
{
"id": "5a11c908-43a1-49f3-813a-b590ccb1e40b",
"type": "scenario",
"url": "https://img.toggle.ai/charts/en/dark/5a11c908-43a1-49f3-813a-b590ccb1e40b"
},
{
"id": "acb14c00-4ebf-4d2d-a936-323e7908f23a",
"type": "scenario-conditions",
"url": "https://img.toggle.ai/charts/en/dark/acb14c00-4ebf-4d2d-a936-323e7908f23a"
}
]
}
]
}
2. Get Insight¶
This endpoint allows you to retrieve the prediction and metadata for a specific insight using its ID. An insight's ID can either be retrieved using the Get Filtered Insights endpoint above, or from the URL when you open an insight on the Reflexivity web portal.
Endpoint: GET /insights/v1/{id}
Get Insight Request¶
Parameters
idstring
curl https://api.reflexivity.com/insights/v1/{id} \
--header 'Authorization: Bearer {token}'
Get Insight Response¶
Properties
conditionsarray of conditions (object)
episodesarray of episodes (object)
hit_ratioobject
Each key in hit_ratio object represents a horizon.
See example below:
metadataobject
idstring
titlestring
contentarray of sections (object)
disclaimerstring
cardobject
created_atdate-time
Format: YYYY-MM-DDTHH:MM:SSZ
chartsarray of charts (object)
HTTP Status Code Summary |
||
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 401 | Unauthorized | No valid API key provided. |
| 404 | Not found | The requested resource doesn’t exist. |
| 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request. |
{
"conditions": [
{
"entity": "vz_nyse",
"snake": "vz_nyse.pb_ibes_forward_12m",
"condition": 4,
"value": 1.6915602666024252,
"method_sub_cls": "valuation",
"condition_text": "Verizon (VZ:NYSE) Forward P/B, is below 1.69"
},
{
"entity": "vz_nyse",
"snake": "vz_nyse.ibes_roa_forward_12m.ds",
"condition": 4,
"value": 5.011,
"method_sub_cls": "valuation",
"condition_text": "Verizon (VZ:NYSE) RoA 12m Forward, is below 5.01"
}
],
"episodes": [
{
"start_date": "2008-09-15T00:00:00Z",
"end_date": "2008-10-15T00:00:00Z",
"events": [
{
"date": "2008-09-15T00:00:00Z"
},
{
"date": "2008-09-16T00:00:00Z"
}
]
},
{
"start_date": "2010-02-04T00:00:00Z",
"end_date": "2010-02-12T00:00:00Z",
"events": [
{
"date": "2010-02-04T00:00:00Z"
},
{
"date": "2010-02-05T00:00:00Z"
}
]
},
{
"start_date": "2010-05-06T00:00:00Z",
"end_date": "2010-06-10T00:00:00Z",
"events": [
{
"date": "2010-05-06T00:00:00Z"
},
{
"date": "2010-05-20T00:00:00Z"
}
]
},
{
"start_date": "2023-10-25T00:00:00Z",
"end_date": "2024-01-22T00:00:00Z",
"events": [
{
"date": "2023-10-25T00:00:00Z"
},
{
"date": "2023-10-26T00:00:00Z"
}
]
},
{
"start_date": "2024-07-22T00:00:00Z",
"end_date": "2024-07-22T00:00:00Z",
"events": [
{
"date": "2024-07-22T00:00:00Z"
}
]
}
],
"hit_ratio": {
"1m": {
"median": 3.688099857544813,
"hit_ratio": 90.1639344262295
},
"1w": {
"median": 0.482444384883407,
"hit_ratio": 70.96774193548387
}
},
"metadata": {
"type": "Valuation",
"topic": "Valuations",
"asset_cls": 3,
"class": 9,
"direction": 1,
"eco": "us",
"entity": "vz_nyse",
"event": "",
"horizon": "3m",
"last_value": 42.13,
"last_value_date": "2024-10-31T00:00:00Z",
"market_cap": 177351.5,
"median_return": 0.08230307190760633,
"sector": "sector_communication_services",
"stars": 5,
"sub_cls": 18,
"signal_high": 45.80212930374463,
"signal_low": 40.29393534812769,
"high_conviction_report": {
"cross_business_cycles": true,
"frequent": false,
"high_hit_ratio_in_sample": true,
"high_hit_ratio_out_sample": true,
"high_path_risk_return": true,
"high_pnl_draw_down_ratio": false,
"several_episodes": false,
"sparse": true
},
"hit_rate": 1
},
"id": "9c1117f2-4579-43ca-8ff5-8779ee318c81",
"title": "Verizon's value compared to future book value, or 'Forward Price to Book Ratio', hit a low point of 1.69",
"content": [
{
"section_title": "Overview",
"section_content": "Overview section content"
},
{
"section_title": "Insight Projection",
"section_content": "Insight Projection section content"
},
{
"section_title": "Why It Might Move",
"section_content": "Why It Might Move section content"
},
{
"section_title": "Optimal Trade Horizon",
"section_content": "Optimal Trade Horizon section content"
},
{
"section_title": "Past Performance",
"section_content": "Past Performance section content"
}
],
"disclaimer": "Disclaimer:\nThis communication is issued by Knabble, Inc. and/or affiliates of Knabble, Inc...",
"card": {
"name": "Attractive Valuation",
"intuition": "A cheap stock has a current price that is not justified by its earnings outlook: its price-earnings (P/E) ratio is too low. Consequently, traders often start betting on the price to rise eventually."
},
"created_at": "2024-11-01T11:48:08.260524Z",
"charts": [
{
"id": "5a11c908-43a1-49f3-813a-b590ccb1e40b",
"type": "scenario",
"url": "https://img.toggle.ai/charts/en/dark/5a11c908-43a1-49f3-813a-b590ccb1e40b"
},
{
"id": "acb14c00-4ebf-4d2d-a936-323e7908f23a",
"type": "scenario-conditions",
"url": "https://img.toggle.ai/charts/en/dark/acb14c00-4ebf-4d2d-a936-323e7908f23a"
}
]
}
3. Get Insight Predictions¶
This endpoint allows you to retrieve the predictions for a specific insight using its ID.
Endpoint: GET /insights/v1/{id}/predictions
Get Insight Predictions Request¶
Parameters
idstring
curl https://api.reflexivity.com/insights/v1/{id}/predictions \
--header 'Authorization: Bearer {token}'
Get Insight Predictions Response¶
Retrieves array of predictions. See prediction properties below.
Properties
relative_idxstring
horizonstring
meannumber
mediannumber
countinteger
percentilesobject
Represents percentile values of the data, where each key is the percentile (e.g., 10, 20, 30) and the corresponding value is the associated numerical value at that percentile.
highnumber
lownumber
std_devnumber
minnumber
maxnumber
datedate-time
Format: YYYY-MM-DDTHH:MM:SSZ
HTTP Status Code Summary |
||
|---|---|---|
| 200 | OK | Everything worked as expected. |
| 401 | Unauthorized | No valid API key provided. |
| 404 | Not found | The requested resource doesn’t exist. |
| 500 | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request. |
[
{
"relative_idx": 0,
"horizon": "0d",
"mean": 0,
"median": 0,
"count": 7,
"percentiles": {
"10": 0,
"20": 0,
"30": 0,
"40": 0,
"60": 0,
"70": 0,
"80": 0,
"90": 0
},
"high": 0,
"low": 0,
"std_dev": 0,
"min": 0,
"max": 0,
"date": "2024-11-28T00:00:00Z"
},
{
"relative_idx": 1,
"horizon": "1d",
"mean": 0.0016666666666667236,
"median": 0,
"count": 6,
"percentiles": {
"10": -0.02799999999999986,
"20": -0.01399999999999979,
"30": -0.006999999999999895,
"40": 0,
"60": 0,
"70": 0.009000000000000008,
"80": 0.018000000000000016,
"90": 0.03300000000000003
},
"high": 0.018000000000000016,
"low": -0.01399999999999979,
"std_dev": 0.030236842868703484,
"min": -0.041999999999999926,
"max": 0.04800000000000004,
"date": "2024-11-29T00:00:00Z"
}
]