Research API
The Research API is available on the Space Analyst plan and above. It is available on personal AstraEye Labs accounts only, not on an account provided through a school or another institution.
On the free plan, a connected assistant reads your own reports and the public research library and turns Earnings Radar on or off for a stock you name; everything else it can do needs a plan that includes the Research API.
What it returns is the written prose of your own reports: the executive summary, the discussion, the conclusion, the prepared questions and answers and, where a report has them, its methodology and its test. It never returns charts, tables or data fields. By default it can only read. With the SAGE chat permission and a daily credit limit you set, it can also talk to SAGE and let SAGE act for you, including running research, within that limit.
You can connect AstraEye to ChatGPT, Claude, Gemini, Perplexity, Grok or Glama. Each connection is made from the assistant: you sign in to AstraEye when it asks and choose what it may do.
Each of them connects to the same remote MCP server (Model Context Protocol), listed in the MCP Registry as io.astraeyelabs/research. Its public description is on GitHub.
Step by step: How to use it in ChatGPT.
Step by step: How to use it in Claude.
In ChatGPT, open Plugins, search for AstraEye Labs and install it, or open it directly. Then sign in to AstraEye when it asks and choose what ChatGPT may do. It is separate from your token.
Alternatively, with Claude Code, or any AI assistant setup that can run commands on your computer, use a personal token:
- Create a token in Settings → Research API.
- Keep it on your computer as an environment variable named
ASTRAEYE_TOKEN, so it is never pasted into the conversation. - Ask your assistant, for example:
Using curl with the header "Authorization: Bearer $ASTRAEYE_TOKEN", list my reports from https://astraeyelabs.io/api/v1/research/reports, fetch the latest one, and let's discuss today's market research results.
Your token works only on your own account, and with the SAGE chat permission it can also spend your Astra Credits, so keep it to yourself. Do not paste it into a chat or share it, and revoke it in settings if it is ever exposed. What your assistant reads is for your own research: the sources and disclosures in each report stay with it, and the content is informational, not advice. Terms Section 14.1 sets out exactly what is permitted.
By default the Research API is read-only: it provides programmatic access to your own research projects, to the written prose of each of your finished reports, and to the catalog of analyses and research templates AstraEye offers, with the plan each is on. If a token has the SAGE chat permission (sage:chat) and a positive daily credit limit,it can also ask SAGE questions in your SAGE conversation, and take actions of its own: change your watchlist and research projects, price, start and stop research runs, and refresh your connected balances, each a separate request, spending Astra Credits within that limit. It can never set up or change a schedule, change your settings, security, billing or email, or place or route an order.
Use of this API is governed by Section 14.1 of the Terms of Service, which grants access for your own personal, non-commercial research and for no other purpose. Sections below cite the governing provision wherever a technical rule carries a corresponding contractual obligation.
AstraEye researches crypto and U.S. stocks and ETFs. In the catalog, ETFs belong to the equity asset class with stocks. Analyses about companies (fundamentals, earnings, insider and institutional filings, and analyst actions) describe an operating company and do not describe an ETF, so for ETFs choose analyses of price, volatility, options, distributions and news. Each analysis states the kinds of security it can describe in securityTypes; one that lists only stock is not run for a fund, and a run that holds funds is charged for it on its stocks only, or not at all when it holds no stocks.
Commodities are covered only through commodity ETFs, such as GLD and IAU for gold, SLV for silver, USO for crude oil, UNG for natural gas, CPER for copper, and DBC or PDBC for a broad basket. Research on one describes the fund, which can drift from the commodity it tracks, most of all for funds that hold futures. Commodity prices and futures themselves are not covered. The global market draws its stocks from company indexes, so to research ETFs, name them or add them to your watchlist.
Tokens are issued from Settings → Research API. The token value is displayed once at creation and is not recoverable afterwards. One token may be active per account, and each token expires 90 days after issue. A connection to an AI assistant such as Claude or ChatGPT is separate: it does not count as this token and does not use one.
Under Terms Section 14.1 the token is personal to you. It must be kept confidential and must not be shared, published, sold, transferred, or sublicensed. You are responsible for all activity conducted with it. If a token is exposed, revoke it in settings and issue a replacement, which invalidates the previous token immediately.
Authenticate every request to the endpoints below with your token as a bearer credential. A connection to an AI assistant signs in through that assistant instead; its credentials do not work on these endpoints, and your token does not work for a connection.
curl https://astraeyelabs.io/api/v1/research/projects \ -H "Authorization: Bearer $ASTRAEYE_TOKEN"
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| Authorization | header | string | required | none | Bearer <token>. Requests without a valid credential return 401. |
Automated access is permitted only through this API and within the published limits stated below, in accordance with Terms Section 14.
Returns the research projects belonging to the authenticated account, ordered newest first. Archived projects are never returned.
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| status | query | string | optional | active | Lifecycle state to return: "active", "paused", or "all" for both. Archived projects are not returned, and any other value is refused with a 400. |
| cursor | query | string | optional | none | Opaque cursor from a previous response's nextCursor. Returns the page immediately after it. Omit for the first page. |
| limit | query | integer | optional | 20 | How many projects to return per page, from 1 to 50. |
| Field | Type | Description |
|---|---|---|
| hasMore | boolean | True when more projects exist beyond this page. |
| nextCursor | string | null | Pass as cursor to retrieve the next page. Null on the last page. |
| projects[].id | string | Project identifier. Use as researchId when listing reports. |
| projects[].title | string | Project title as shown in the Lab. |
| projects[].status | string | Current lifecycle state. |
| projects[].createdAt | string (ISO 8601) | When the project was created. |
| projects[].updatedAt | string (ISO 8601) | When the project last changed. |
| projects[].runCount | integer | Number of runs the project has performed. |
| projects[].lastRunAt | string (ISO 8601) | null | When the project's most recent run started. Null if it has never run. |
| projects[].scheduled | boolean | Whether the project has a schedule attached. |
{
"hasMore": false,
"nextCursor": null,
"projects": [
{
"id": "…",
"title": "Crypto majors, weekly",
"status": "active",
"createdAt": "2026-08-01T09:14:22.000Z",
"updatedAt": "2026-08-24T09:14:22.000Z",
"runCount": 12,
"lastRunAt": "2026-08-24T09:00:00.000Z",
"scheduled": true
}
]
}Returns 20 projects per page unless you set limit (at most 50), ordered newest first. Continue by passing nextCursor as cursor until hasMore is false.
Returns an index of finished reports, ordered by generation time, newest first. A report corresponds to one run group, the unit shown on the results page. Only reports in a ready state are returned; pending, generating, failed, and degraded groups are omitted because they carry no dependable summary. Reports of archived projects are not returned, in this list or by id. The first report is the most recently finished run.
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| researchId | query | string | optional | none | Restrict the result to a single project. Accepts a projects[].id value. Omit to list reports across all projects. |
| cursor | query | string | optional | none | Opaque cursor from a previous response's nextCursor. Returns the page immediately after it. Omit for the first page. |
| limit | query | integer | optional | 20 | How many reports to return per page, from 1 to 50. |
| Field | Type | Description |
|---|---|---|
| hasMore | boolean | True when more reports exist beyond this page. |
| nextCursor | string | null | Pass as cursor to retrieve the next page. Null on the last page. |
| reports[].id | string | Report identifier. Use to retrieve the summary. |
| reports[].researchId | string | Identifier of the project the report belongs to. |
| reports[].url | string | null | The report's page in AstraEye, with its charts and figures. It opens only for you when signed in. Null if the address cannot be formed. |
| reports[].generatedAt | string (ISO 8601) | null | The single point in time at which the report was generated, and the field the list is ordered by. This is not a range. Null where a generation timestamp was not recorded. |
| reports[].availableLanguages[] | string[] | Languages this report can be read in, "en" first. Pass one as the language parameter when retrieving the summary, methodology or test. A report with no purchased translation lists "en" alone. |
{
"hasMore": false,
"nextCursor": null,
"reports": [
{ "id": "…", "researchId": "…", "generatedAt": "2026-08-24T09:31:00.000Z",
"url": "https://astraeyelabs.io/research/…/results/…",
"availableLanguages": [ "en", "ru" ] }
]
}Returns 20 reports per page unless you set limit (at most 50). Continue by passing nextCursor as cursor until hasMore is false. The cursor resumes right after the last report you received, so a report generated between two requests cannot push an older one across a page boundary and hide it. Terms Section 14.1 prohibits using repeated or scheduled requests to accumulate content into a dataset or to reconstruct an underlying provider dataset.
Returns the analyses AstraEye can run: the same list as the analysis catalog, with the id SAGE understands. An assistant can use it to name an analysis precisely when it asks SAGE what an analysis measures or asks SAGE to run one. Each analysis states the plan it is on and whether your plan includes it, and the response states your own plan. Prices are not listed: they depend on the run, and SAGE states them when asked.
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| scientist | query | string | optional | none | Only this scientist's analyses, by scientist id, such as atlas. |
| assetClass | query | string | optional | none | Only analyses for "crypto", "equity" or "universal" (both). |
| detail | query | string | optional | summary | "summary" returns the one-line summary of each analysis. "full" adds the full description, which is long; combine it with scientist or assetClass. |
| Field | Type | Description |
|---|---|---|
| count | integer | Number of analyses returned. |
| yourPlan | object | null | Your current plan. Null where it cannot be stated, such as an account with no plan. |
| yourPlan.id | string | The plan id. |
| yourPlan.name | string | The plan name members see on the subscribe page, such as Space Analyst. |
| yourPlan.rank | integer | The plan's position in AstraEye's plan order. A higher number is a higher plan; compare yourPlan.rank with an item's plan.rank. |
| analyses[].id | string | The analysis id, such as ta_momentum_scan. Use it, or the name, with SAGE. |
| analyses[].name | string | The analysis name as the catalog shows it. |
| analyses[].scientist | string | The scientist that runs it, such as atlas. |
| analyses[].assetClass | "crypto" | "equity" | "universal" | What it analyses: crypto runs only on crypto and equity only on stocks and ETFs; universal covers both. An analysis with no asset of its class in a project is skipped and not charged. Which kinds of security it can describe is securityTypes; see What research covers. |
| analyses[].summary | string | null | One-line description. |
| analyses[].readsEarlierFindings | boolean | True when the analysis works from what other analyses found, such as LYRA's consensus. It only sees analyses that finished before it, so it belongs in a later stage or a later phase than them. |
| analyses[].needs | string[] | Present when specific analyses must run before this one: their ids. |
| analyses[].securityTypes | ("stock" | "etf" | "mutual_fund")[] | The kinds of security it can describe. An analysis about companies (fundamentals, earnings, insider and institutional filings, analyst actions, sector rank) lists only "stock": it is not run for an ETF or a mutual fund, and a run is not charged for one. Absent for a crypto-only analysis. |
| analyses[].description | string | null | Full description of what it does. Present only with detail="full". |
| analyses[].plan | object | null | The lowest plan that includes this analysis: id, name and rank, as in yourPlan. Null where it cannot be stated. |
| analyses[].includedInYourPlan | boolean | null | Whether your plan includes this analysis. Null where it cannot be determined, which is not the same as false. |
{
"count": 1,
"yourPlan": { "id": "analyst", "name": "Space Analyst", "rank": 1 },
"analyses": [
{ "id": "ta_momentum_scan", "name": "Momentum Scan", "scientist": "atlas",
"assetClass": "universal", "summary": "…", "description": "…",
"plan": { "id": "freelancer", "name": "Freelancer", "rank": 0 },
"includedInYourPlan": true }
]
}With SAGE chat, an assistant can pass an analysis by name or id straight to SAGE, for example: "Ask SAGE to explain what the Momentum Scan measures" or "Ask SAGE to run a Momentum Scan on my watchlist". SAGE quotes the price first.
Returns one analysis in full, by its id from the list: its name, scientist, asset class, full description and methodology, meaning how it works, the public theory it rests on and what that theory cannot support. Load it when a conversation needs more than the one-line summary. Like the list, it states the plan the analysis is on, whether your plan includes it, and your own plan.
| Field | Type | Description |
|---|---|---|
| analysis.id, name, scientist, assetClass, summary | string | As in the list. summary may be null. |
| analysis.securityTypes | ("stock" | "etf" | "mutual_fund")[] | As in List analyses. |
| analysis.description | string | null | Full description of what it does. |
| analysis.methodology | string | null | How the analysis works and the limits of its method. Null where none is published. |
| analysis.plan, includedInYourPlan | object | null; boolean | null | As in the list. |
| yourPlan | object | null | Your current plan: id, name and rank, as in the list. |
An id that is not in the catalog returns 404 not_found.
Returns the research templates AstraEye offers: prebuilt combinations of analyses you can start a research project from, as the template gallery shows them. Each names the scientists and analyses it combines, the plan it is on and whether your plan includes it, and the response states your own plan. An assistant can use it to find the template that covers a question. Prices are not listed; SAGE states them when asked.
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| assetClass | query | string | optional | none | Only templates whose asset class is exactly "crypto", "equity" or "universal" (both). |
| scientist | query | string | optional | none | Only templates that include this scientist, by scientist id, such as atlas. |
| analysis | query | string | optional | none | Only templates that include this analysis, by its id from the analysis list. |
| Field | Type | Description |
|---|---|---|
| count | integer | Number of templates returned. |
| yourPlan | object | null | Your current plan: id, name and rank, as in List analyses. |
| templates[].id | string | The template id. Pass it to Retrieve a template. |
| templates[].name | string | The template name as the gallery shows it. |
| templates[].summary | string | null | One-line description. |
| templates[].category | string | null | The gallery category, such as technical, fundamental or sentiment. |
| templates[].assetClass | "crypto" | "equity" | "universal" | What it analyses; universal covers both. Each of its analyses runs only on assets of its own class. |
| templates[].scientists[] | { id, name } | The scientists whose analyses it combines, by id and name. |
| templates[].analyses[] | { id, name } | The analyses it runs, by analysis id and the name the template gives it. Each id can be read with Retrieve an analysis. |
| templates[].plan | object | null | The lowest plan that includes this template: id, name and rank. Null where it cannot be stated. |
| templates[].includedInYourPlan | boolean | null | Whether your plan includes this template. Null where it cannot be determined, which is not the same as false. |
{
"count": 1,
"yourPlan": { "id": "analyst", "name": "Space Analyst", "rank": 1 },
"templates": [
{ "id": "tmpl_v2_equity_fundamentals", "name": "Equity Deep Fundamentals",
"summary": "…", "category": "fundamental", "assetClass": "equity",
"scientists": [{ "id": "felix", "name": "FELIX" }],
"analyses": [{ "id": "fundamental_cash_flow_quality", "name": "Cash Flow Quality" }],
"plan": { "id": "trader", "name": "Galactic Merchant", "rank": 2 },
"includedInYourPlan": false }
]
}A template that is not included in your plan is still listed, with includedInYourPlan false, so an assistant can tell you which plan includes it.
Returns one template in full, by its id from the list: its full description, typical cadence and duration, and the analyses it runs, in order, each with the analysis id that Retrieve an analysis reads. Analyses in the same phase run side by side, grouped into workstreams, and a later phase starts once every earlier phase has finished. Within a workstream, a later stage starts once its earlier stages have finished.
| Field | Type | Description |
|---|---|---|
| yourPlan | object | null | Your current plan: id, name and rank, as in the list. |
| template.id, name, summary, category, assetClass, scientists, plan, includedInYourPlan | as in the list | As in the list. |
| template.description | string | null | Full description of what the template is for. |
| template.complexity | string | null | The gallery's complexity label, such as starter or advanced. |
| template.recommendedCadence | string | null | How often the template is meant to be run, such as Daily or Weekly. |
| template.estimatedMinutes | integer | null | Typical time for a run to finish, in minutes. |
| template.analysisCount | integer | Number of analyses the template runs. |
| template.analyses[].id, name, scientist | string | The analysis, by id, name and scientist. |
| template.analyses[].phase | integer | null | 1 for the first phase. Every earlier phase finishes before a later one starts. |
| template.analyses[].workstream | string | null | The group of analyses this one runs in within its phase. |
| template.analyses[].stage | integer | null | 1 for the first stage of its workstream. A workstream's earlier stages finish before a later one starts; analyses in the same stage run together. |
| template.analyses[].stageLabel | string | null | The label the template gives that stage. |
An id that is not a current template returns 404 not_found.
Returns one of your projects, by its id from List research projects, as it will run: every analysis with its phase, workstream and stage, in the same terms as Retrieve a template, and what the project covers. Analyses in the same stage run together; a later stage starts once the earlier ones have finished; workstreams in the same phase run side by side and cannot use each other's findings, and a later phase can use all of them. Use it to check that a project set up through SAGE has the structure you asked for.
| Field | Type | Description |
|---|---|---|
| project.id, title, status | string | The project, as in the list. |
| project.covers.kind | "global_market" | "chosen_assets" | "watchlist" | "holdings_or_watchlist" | What the project covers. |
| project.covers.coverage | string | On the global market: which asset classes it covers, by the coverage choice's name (Crypto and stocks, Stocks only or Crypto only; see List market slices). |
| project.covers.marketSlices | string[] | On the global market: the slice ids it draws from (see List market slices). Empty means each asset class's default. |
| project.covers.marketSliceNames | string[] | The same slices by name, in the same order, as List market slices names them. |
| project.covers.skipsAssetClass | "crypto" | "equity" | null | On the global market: an asset class the project leaves out. |
| project.analyses[].id, name, scientist | string | The analysis, by id, name and scientist. |
| project.analyses[].phase, workstream, stage, stageLabel | as in Retrieve a template | Where the analysis runs. |
| project.analyses[].readsEarlierFindings | boolean | As in List analyses. |
An id that is not one of your projects returns 404 not_found.
The runs of one of your projects, newest first, one page at a time: each run's id, status and times, and whether its report can be read. How far along a run is comes from Retrieve a run. Pass nextCursor back as cursor while hasMore is true; limit is 1 to 50 (default 20).
| Field | Type | Description |
|---|---|---|
| hasMore, nextCursor | boolean, string | null | Paging, as in List research projects. |
| runs[].runGroupId | string | The run's id. It is also its report's id. |
| runs[].projectId | string | The project it ran. |
| runs[].status | string | pending or running while it works; then one of completed, completed_partial, failed, skipped, cancelled, not_started. |
| runs[].finished | boolean | Whether the run will not change again. |
| runs[].startedAt, finishedAt | string | null | ISO 8601 times; finishedAt only once finished. |
| runs[].resultsReady | boolean | A finished run whose report can be read, by the same id, with Retrieve a report. |
An id that is not one of your projects returns 404 not_found.
One run of one of your projects: what it is doing, how far along it is, and whether its report can be read. Progress is the figure AstraEye's own progress bar shows: an analysis that failed or was skipped counts as done, so a finished run is never stuck short of 100, and the figure never goes backwards.
| Field | Type | Description |
|---|---|---|
| run.runGroupId | string | The run's id. It is also its report's id. |
| run.projectId | string | The project it ran. |
| run.status | string | pending or running while it works; then one of completed, completed_partial, failed, skipped, cancelled, not_started. |
| run.finished | boolean | Whether the run will not change again. |
| run.startedAt, finishedAt | string | null | ISO 8601 times; finishedAt only once finished. |
| run.progress.percent | number | null | 0 to 100, as AstraEye's progress bar shows it; null when it cannot be measured yet. |
| run.progress.done, total | number | Units of work finished and in all, the bar's own count. |
| run.analyses[] | object[] | Every analysis dispatched for the run, in run order: id, name, scientist, status (pending, running, completed, failed, skipped or cancelled), part (analysis, or report for a step of SAGE writing the report) and reused. Empty before the first is dispatched. |
| run.resultsReady | boolean | A finished run whose report can be read, by the same id, with Retrieve a report. |
A run that is not one of that project's runs, or a project that is not yours, returns 404 not_found.
When SAGE starts research through Send a message, the run_start action carries the run's runGroupId and its projectId. To follow it:
- Keep both ids. For a run you did not start, find it with List a project's runs.
- Read Retrieve a run. While finished is false the status is pending or running and progress.percent says how far along it is; null means it cannot be measured yet, not zero. Runs take minutes, so check again after a pause rather than in a tight loop.
- When finished is true the status is one of completed, completed_partial, failed, skipped, cancelled, not_started. If resultsReady is true, read the report with Retrieve a report, using the same runGroupId as the report id.
- A run SAGE started also posts a message when it finishes: in Read messages it has kind run_delivery and the same runGroupId and projectId.
The parts of the market a project or run on the global market can be drawn from, such as the largest 25 S&P 500 companies, a sector or the top 100 coins, with the rule that decides what each one includes. Every slice is listed, in AstraEye's order: by market cap from the narrowest up, then the other groups.
The Funds slices (commodity funds, sector funds and broad market funds) hold exchange-traded funds rather than companies. A run on one reads each fund's own shares, and the analyses that describe operating companies, such as fundamentals, earnings and insider filings, do not run on it and are not charged.
A project or run covers at most one slice of each asset class: one stocks slice, one crypto slice, or one of each (for example the S&P 500 and the top 100 coins). To research several slices of the same asset class, such as two sectors or the S&P 500 and the Dow 30, create one project per slice: each project draws your plan's full number of assets from its own slice, so every slice gets complete coverage. When you ask SAGE, name each slice exactly as listed here.
A project on the global market also covers crypto and stocks, stocks only or crypto only. The response names those three choices in coverageChoices, the way the project page does; name the one you want to SAGE in the same words, beside the slice, for example "the global market, Stocks only, Largest 10 by market cap". Which assets a slice holds is decided when a run starts and is not listed here; the report names them.
| Field | Type | Description |
|---|---|---|
| marketSlices[].id | string | The slice id, such as equity_sp500. |
| marketSlices[].name | string | The slice name, such as S&P 500. |
| marketSlices[].assetClass | "crypto" | "equity" | The asset class it draws. |
| marketSlices[].group | object | null | The section it is listed under: id and label, such as By market cap, Indexes, Sectors or Funds. Slices of one group are listed together. |
| marketSlices[].rule | string | What the slice includes, in plain words. |
| marketSlices[].filter | object | The same rule as fields: index (a membership list), rankMax (a market-cap rank ceiling; for stocks, the company's rank within the index, each company counted once), minTurnover (a trading-volume floor) and tickers (a fixed list of funds AstraEye keeps, such as the sector funds). An absent field does not narrow. |
| marketSlices[].default | boolean | True for the slice an asset class draws from when none is chosen. |
| marketSlices[].plan | object | null | The lowest plan that can use this slice: id, name and rank, as in List analyses. Null where it cannot be stated. |
| marketSlices[].includedInYourPlan | boolean | Whether your plan can use this slice. |
| yourPlan | object | null | Your current plan: id, name and rank. |
| coverageChoices[].name | string | Crypto and stocks, Stocks only or Crypto only: which asset classes a global-market project covers, named as the project page names it. |
| coverageChoices[].detail | string | What the choice gives, in plain words. |
| coverageChoices[].assetClasses | ("crypto" | "equity")[] | The asset classes it draws. |
| coverageChoices[].skipsAssetClass | "crypto" | "equity" | null | The class it leaves out, as project.covers.skipsAssetClass states it. |
Returns the written summary of a single finished report belonging to the authenticated account.
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| id | path | string | required | none | Report identifier from reports[].id. A report that does not belong to the account returns 404. |
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| language | query | string | optional | en | The language to return the prose in. Responses are English unless this is passed, so an existing integration is unaffected. Accepts any value from the report's availableLanguages, and a regional form such as en-US resolves to its base language. A language the report does not have returns 400 unsupported_language rather than quietly returning English. |
| Field | Type | Description |
|---|---|---|
| report.id | string | Report identifier. |
| report.researchId | string | Identifier of the project the report belongs to. |
| report.url | string | null | The report's page in AstraEye, with its charts and figures. It opens only for you when signed in. Null if the address cannot be formed. |
| report.generatedAt | string (ISO 8601) | null | When the report was generated. |
| report.language | string | The language of the prose in this response. This is what was actually served, which is not always what was requested - see requestedLanguage below. |
| report.availableLanguages[] | string[] | Every language this report can be read in, "en" first. |
| report.coverage | "complete" | "partial" | Whether every piece of prose in this response reached report.language. A translation frequently settles partially, so "partial" is ordinary rather than exceptional: read the per-item language field to see which pieces did, and englishParagraphs for paragraphs inside a translated piece that stayed in English. |
| report.requestedLanguage | string (present only on a fallback) | The language that was asked for, when it could not be served and English was returned instead. Absent on an ordinary response, so its presence is the signal. |
| report.languageFallbackReason | string (present only on a fallback) | Why the requested language was not served: family_not_translated (this part of the report was not translated), no_translated_units (nothing in this part reached that language), unit_metadata_unavailable (the per-item language record could not be read or verified, so the prose is not presented as translated), or translated_artifact_unreadable. |
| report.summary.title | string | null | Summary title. |
| report.summary.titleLanguage | string | null | The language this piece of prose was actually written in. Null where it is not recorded, which is not the same as English - the language is unknown, and the field says so rather than guessing. |
| report.summary.executiveSummary | string | null | Opening prose summary. |
| report.summary.executiveSummaryLanguage | string | null | The language of the opening prose, on the same terms as titleLanguage. |
| report.summary.sections[] | object | Ordered sections, each { id, heading, body, scientistId, language }. Only body is always present; the others may be null. |
| report.summary.sections[].englishParagraphs | object (present only when some paragraphs are in English) | Paragraphs that stayed in English inside a section whose language is the translation's, as { body: [positions] }. A position counts the body's paragraphs, split on blank lines, from 0. A translated paragraph is kept in English when it could not be published as translated; the rest of the section is still translated, and coverage reads "partial". |
| report.summary.sections[].captions | array (present only when the section has some) | Fixed captions that belong with a paragraph of the body, each { analysisTypes[], afterParagraph, lines[] { language, text } }. Show every line, in order and unchanged, directly after the paragraph at position afterParagraph (counted as for englishParagraphs), or before the body when afterParagraph is null; never in a tooltip, a footnote or a separate page. Today the one caption marks a simulated result (an indicator rule tested on the past closing prices of a crypto asset or of a fund's shares): a statement in English and a line naming what was tested, followed by their translation when the response is translated. Captions are not part of body, so the section's language does not describe them; each line states its own. |
| report.summary.conclusion | string | null | Closing prose. |
| report.summary.conclusionLanguage | string | null | The language of the closing prose, on the same terms as titleLanguage. |
| report.summary.questions[] | object | Prepared questions and answers, each { id, question, answer, scientistId, language }. scientistId and language may be null. |
| report.summary.questions[].englishParagraphs | object (present only when some paragraphs are in English) | As on a section, for the answer: { answer: [positions] }. |
| report.summary.englishParagraphs | object (present only when some paragraphs are in English) | As on a section, for the opening and closing prose: { executiveSummary: [positions], conclusion: [positions] }, each present only when it has some. |
| report.summary.captions | object (present only when there are some) | Captions outside the sections, as on a section: { executiveSummary: [captions], conclusion: [captions], sections: [captions] }, each present only when it has some. Those under executiveSummary and conclusion follow the field's last paragraph; those under sections are shown before the first section. |
| report.summary.disclosures | object | Informational notice, provenance statement, source list, notAdvice flag, and whether SAGE declined the advice part of the run. See Disclosures below. |
{
"report": {
"id": "…",
"researchId": "…",
"generatedAt": "2026-08-24T09:31:00.000Z",
"url": "https://astraeyelabs.io/research/…/results/…",
"language": "ru",
"availableLanguages": [ "en", "ru" ],
"coverage": "partial",
"summary": {
"title": "…",
"titleLanguage": "ru",
"executiveSummary": "…",
"executiveSummaryLanguage": "en",
"sections": [ { "id": "…", "heading": "…", "body": "…", "scientistId": "…",
"language": "ru",
"captions": [ { "analysisTypes": [ "…" ], "afterParagraph": 1,
"lines": [ { "language": "en", "text": "…" },
{ "language": "ru", "text": "…" } ] } ] } ],
"conclusion": "…",
"conclusionLanguage": null,
"questions": [ { "id": "…", "question": "…", "answer": "…", "scientistId": "…",
"language": "ru" } ],
"disclosures": {
"informationalNotice": "…",
"provenanceDisclosure": "…",
"sources": { "notice": "…", "url": "…/data-sources", "credits": [ "…" ] },
"notAdvice": true,
"adviceDeclined": false
}
}
}
}Returns how each analysis in the report was carried out, in written prose. Many reports have no methodology section; those return 404 not_found. Takes the same id and language parameters as the summary.
| Field | Type | Description |
|---|---|---|
| methodology.reportId, researchId, generatedAt | string; generatedAt string | null | As on the summary. |
| methodology.language, availableLanguages, coverage | string, string[], "complete" | "partial" | The same language fields as the summary, including requestedLanguage and languageFallbackReason on a fallback. |
| methodology.analyses[] | object | Each { analysisType, title, scientistId, theorySource, sections[] { heading, body, englishParagraphs, captions }, language }. Only body is always present; the others may be null, and englishParagraphs is present only when part of a section stayed in English inside a translated analysis, as on a summary section ({ heading: [positions], body: [positions] }). An analysis with no written method is left out. theorySource says whether the method comes from a written explanation of the analysis or from the run's own findings. A section's captions, present only when it has some, are shown after its paragraph at afterParagraph, as on a summary section. |
Returns the multiple-choice test written from the report, where it has one; a report without a test returns 404 not_found. Takes the same id and language parameters as the summary. Answers stay hidden until you submit that scientist's part of the test in AstraEye.
| Field | Type | Description |
|---|---|---|
| quiz.reportId, researchId, generatedAt | string; generatedAt string | null | As on the summary. |
| quiz.language, availableLanguages, coverage | string, string[], "complete" | "partial" | The same language fields as the summary, including requestedLanguage and languageFallbackReason on a fallback. |
| quiz.submittedScientists[] | string[] | The scientists whose part of the test you have submitted. "*" means the whole test was submitted at once. |
| quiz.questions[] | object | Each { id, scientistId, source, question, choices[], correctIndex, explanation, answerAvailable, language, englishParagraphs }. scientistId, source and language may be null. While that part of the test is open, answerAvailable is false and correctIndex and explanation are null; explanation can also be null after it is submitted. englishParagraphs is present only when part of a translated question stayed in English, as on a summary section, keyed question, choices.N or explanation (the last only while the explanation is shown). |
Responses contain written prose only: the summary presented on the results page, and the report's methodology and test where it has them. Charts, tables, figures, numeric series, screener output, and underlying market data are not exposed through this API.
Content returned is AstraEye Labs derived research output. It is not raw or redistributed market data, and receipt of it conveys no license, right, title, or interest in any data provider's data. Terms Section 12 continues to govern provider-sourced material, and Section 14.1 confirms that this API is not a data-export feature within the meaning of any provision of Section 12 governing the export of a provider's data. The restrictions in Section 12 applicable to derived output, including the prohibitions on model training and on reconstructing an underlying provider dataset, apply in full.
Terms Section 14.1 authorizes you to make your own research summaries available to an artificial-intelligence assistant, agent, or other tool that you personally operate and control, for your own personal research purposes. That authorization is expressly limited and does not permit:
- using the content to develop, train, fine-tune, evaluate, or improve any model;
- retaining or accumulating the content beyond what your personal use requires, or assembling it into a dataset, index, archive, or corpus;
- using repeated or scheduled requests to reconstruct or approximate any underlying provider dataset;
- making the content available to any other person, including through a shared workspace, assistant, channel, or published output; or
- using the content to build, market, operate, or support any product or service.
You are responsible for the tool you select and for its handling of content you transmit to it. Before transmitting content, satisfy yourself that the tool's terms and data practices are consistent with your obligations, including that it does not train on, retain, or redistribute what it receives.
Each report carries a disclosures object containing an informational notice, a provenance statement, and the source list, provided as structured fields so a client can present them correctly.
adviceDeclined is true when the run was read as a request for advice and SAGE declined that part before giving facts. It is reported as a field rather than as a sentence inside the summary prose, so a client can surface it in its own right; the summary itself always begins with findings.
Under Terms Section 14.1 these must not be removed, altered, obscured, suppressed, or detached from the content they accompany, and must be preserved wherever the content is displayed or read back. AstraEye Labs research is informational and educational only. It is not financial, investment, legal, or tax advice, is not a recommendation or solicitation, and is not personalized to your circumstances. Terms Sections 3 and 4 apply in full to all content returned by this API.
A token created with the SAGE chat permission (sage:chat) can also send text to your own SAGE conversation and read the replies. Messages sent this way appear in your SAGE chat on the web and in the app. Each reply is a SAGE answer and costs Astra Credits as one does, up to the daily credit limit you set when creating the token; limits reset at 00:00 UTC. SAGE only answers here: a message is a question, and SAGE starts, prices and changes nothing because of it. Changes are the separate action requests described below, which your tool makes itself. When a run finishes, the result arrives in the same conversation.
| Field | Type | Description |
|---|---|---|
| clientMessageId | string (UUID) | A new id you generate for each message. Resending the same id returns the same turn instead of asking again; reusing it for a different message returns 409. |
| text | string | Your message: up to 1,000 characters, and not blank. |
| conversationId | string (UUID), optional | A conversation returned by this API. Omitted, your current SAGE conversation is used. |
Waits up to 50 seconds for the reply. Returns 200 with { turnId, conversationId, status: "completed", reply: { role, text } }, or 202 with status: "generating" when the answer is still being written.
The state of one turn: generating, completed (with reply) or failed.
Messages in a conversation, oldest first. Parameters: conversationId (optional), cursor (from nextCursor, to receive only newer messages) and limit (1 to 50, default 20). Each message has id, role, text, createdAt, ordinal and kind: run_delivery (with runGroupId) for a finished run's result, chat otherwise. delivery: "unavailable" means finished runs could not be checked on this call; try again shortly.
Through your connected assistant the tool is ask_sage; with a token, POST /api/v1/sage/messages. Say it the way you would in the app. For example:
- Understand your research: "Ask SAGE what my latest report says about Bitcoin's momentum", or "how the Momentum Scan reached its result".
- Choose what to run: "Ask SAGE which analysis would show who is holding ETH", or "what the Crypto Perpetuals Positioning template would tell me about BTC".
- Read first, then ask: "Read my latest report, then ask SAGE what its most important finding is". Your assistant reads your reports itself and brings the question to SAGE.
- Learn the concepts: "Ask SAGE what the RSI measures".
- In your language: ask in English, Russian or Spanish, and SAGE answers in the same language.
SAGE explains research and never tells you what to buy or sell. When a message asks for a change, SAGE says so and names the action that makes it; it does not make it. Schedules and support requests are handled in AstraEye on the web or in the SAGE app.
ChatGPT, for now: until ChatGPT supports the separate actions, a ChatGPT connection's messages to SAGE can still act as they did before, as Terms Section 14.1 describes: what a message asks for outright happens at once, and what SAGE proposes happens when the next message agrees, carrying pendingAction and actions on the reply. This ends when ChatGPT supports the separate actions.
With the SAGE chat permission your tool can change your research itself, one separate request per action, each carried out at once. Through a connected assistant each action is a tool of the same name, described to the assistant for what it does, so it can ask you before it calls one; whether it asks is set in the assistant. Every action is recorded and shown in your API activity in Settings. Assets are named by assetId, projects by projectId, analyses and templates by their ids from the catalog.
find_assets. One to 20 names or tickers, repeated as name. Each comes back found with its asset, choose with candidates when several assets share it (ask which one), or not_found with a reason. An asset is { assetId, symbol, name, assetClass, kind, onWatchlist }, where kind is crypto, stock, etf or mutual_fund.
list_watchlist. The assets on your watchlist, each as above. Never a quantity, cost basis or note. Research covers only watchlist assets.
add_to_watchlist. { assetIds } (1 to 25), or { marketSliceId } for every member of a market slice with a fixed list. All are added together, or none. Returns added, and alreadyDone for any already there.
remove_from_watchlist. { assetIds }. Removing an asset also deletes the quantity, cost basis and note you recorded for it. All are removed together, or none.
create_research_project. title, the work (analysisIds or a templateId), covers (chosen_assets with assetIds, watchlist, holdings_or_watchlist, or global_market with marketSliceIds and skipsAssetClass), and optionally a description and reportOptionsOn ( methodology, audio_methodology, quiz, visual_brief, audio, questions). Analyses that read earlier findings are placed after what they read. It only creates: nothing is priced, run or spent. Returns project; price it with quote_research_run. Assets must already be on your watchlist.
update_research_project. projectId and any of: title, description, addAnalysisIds with placement (auto, new_stage or new_workflow), removeAnalysisIds, what it covers, reportOptionsOn and reportOptionsOff. The changes are made one after another: if one fails, the answer is 409 not_done with kept, the changes already made, which stay. Starts nothing.
archive_research_project and restore_research_project. { projectId }. Archiving what is archived, or restoring what is not, returns outcome: "unchanged".
quote_research_run. A saved project as it stands ({ projectId }); for new work, create the project first. Nothing in the project changes. Returns quote: { quoteId, priceCredits, projectId, projectTitle, covers, analyses, expiresAt, dailyLimit, startable }. startable is null, with startableUnknown saying why, when today's limit could not be read; the start checks it. A newer quote can replace an earlier unstarted one (quote_replaced), so one run never starts twice.
start_research_run. { quoteId, priceCredits, clientRequestId }, where priceCredits is the price you agreed to. A run never starts above it (price_higher); if the price fell, it starts at the lower one. Returns run: { runGroupId, projectId, priceCredits, admission }; follow it with get_research_run.
stop_research_run. { projectId }. What the run found so far is kept; stopping a run does not refund the part that did not run.
refresh_connected_balances. Refreshes your balances from the exchanges you connected in AstraEye, with the keys you stored there. Free. Returns exchanges, each refreshed or failed, never an amount.
Through a connected assistant, on every plan including the free plan. turn_on_earnings_radar and turn_off_earnings_radar. { assetId }, one U.S. stock. They work exactly as the switch in Settings: turning a stock on also turns the Earnings Radar email on, and a refusal says why in the same words. Returns outcome and earningsRadar (on or off).
get_earnings_calendar. Your Earnings Radar stocks, each with the next report date AstraEye has (announced or projected), the days until it, and the Radar reports already delivered. The research figures stay in the reports.
list_public_reports. The reports in the public research library, newest first; get_research_report reads one by its id.
Every change takes an optional clientRequestId, a UUID you generate (required to start a run). Sending the same request again with the same id returns its first result instead of acting twice, for 7 days; the same id with different arguments returns 409 idempotency_conflict. A refusal changes nothing and is not kept, so the same request with the same id can be sent again once what stopped it has cleared; an answer after which part of the request stands (not_done with partial, or outcome_unknown) is kept, so a retry never does it twice. A successful action returns outcome: done, unchanged (with a message), priced or started.
Setting up, changing or removing a schedule is never available through the API; schedules are managed in AstraEye.
- A run's price is held before it is launched, against this access's daily credit limit and your account's total API spending today.
- It is charged only when the Research Lab accepts the run.
- If the Research Lab rejects it, or it expires or is cancelled before it starts, the held credits are released. If the outcome cannot be confirmed, they stay held for that day.
- If the price does not fit in what is left of the limit, nothing starts (daily_limit_reached).
- Stopping a run does not refund the part that did not run: the credits it was charged stay spent.
- For each run started this way, AstraEye sends an in-app notice and an email with what it cost, and its results arrive in your SAGE conversation when it finishes.
| Operation | Short window | Daily |
|---|---|---|
| List projects, reports, analyses or templates, or read one analysis or template (per token or connection) | 60 per 5 minutes | 2,000 |
| Retrieve a report summary, methodology or test (per token / per account) | 40 / 60 per 5 minutes | 300 / 400 |
| Send a SAGE message (per token / per account) | 60 / 90 per 5 minutes | 1,000 / 1,500 |
| Check a SAGE turn (per token / per account) | 120 / 180 per 5 minutes | 5,000 / 8,000 |
| Read SAGE messages (per token / per account) | 60 / 90 per 5 minutes | 2,000 / 3,000 |
| Take an action (per token / per account) | 30 / 45 per 5 minutes | 500 / 750 |
| Refresh connected balances (per token / per account) | 6 / 6 per hour | 48 / 48 |
Listing, finding assets and reading the watchlist are limited per token, or per connection for a connected assistant. Report reads (summary, methodology and test) share one allowance, and SAGE operations and actions have the ones in the table; a balance refresh counts as an action too. Both are limited per token or connection and also per account, across your token and any assistant you have connected. A request exceeding a limit returns 429 with a Retry-After header in seconds; honour that interval before retrying. Through a connected assistant, a limit comes back as an error in the tool result instead. These are the published limits referred to in Terms Section 14, and AstraEye Labs may adjust them under Section 14.1.
Errors are returned as { "error": { "code": "…", "message": "…" } }. A failure is never represented as an empty result set.
| Status | Code | Condition |
|---|---|---|
| 401 | invalid_token | The credential is missing, malformed, unrecognized, revoked, or expired. Issue a new token in settings. |
| 400 | unsupported_language | The language parameter names a language this report is not available in. The message lists the languages that are, and the same list is on the report index as availableLanguages. |
| 403 | tier_required | The account's plan does not include the Research API. The message names the plans that do. |
| 403 | account_ineligible | The account is not currently eligible, for example where it is suspended or a legal disclosure requires acceptance in the browser. |
| 404 | not_found | The Research API is not enabled for this account, the requested report does not belong to it, or the report has no summary, methodology or test to return. |
| 422 | unavailable_for_export | The report cannot be delivered through the API because part of it is not written prose. It is available in full on the results page in the browser. |
| 429 | rate_limited | A rate limit was exceeded, or SAGE is busy for this account. Honour the Retry-After header when it is present. |
| 503 | upstream_unavailable | The research service is temporarily unreachable. Retry after a short interval. |
| 400 | invalid_request | The SAGE message body is not exactly { clientMessageId, text, conversationId? }, an action's body is not as documented above, or a parameter is out of range. |
| 400 | invalid_cursor | The cursor does not belong to this conversation. |
| 402 | daily_limit_reached | This access's daily credit limit, counted against your account's total API spending today, is reached or is 0. It resets at 00:00 UTC. |
| 402 | insufficient_credits | The account does not have enough Astra Credits for a SAGE reply. |
| 403 | insufficient_scope | The token was not created with the sage:chat permission. |
| 404 | conversation_not_found | The conversation does not exist or is not yours. |
| 404 | turn_not_found | The turn does not exist or is not yours. |
| 409 | idempotency_conflict | This clientMessageId or clientRequestId was already used for a different message or request. |
| 409 | request_in_progress | A request with this clientRequestId is still being carried out. Retry it in a moment. |
| 404 | unknown_asset | An assetId is not an asset research can cover. The ids are listed; look them up with find_assets. |
| 409 | not_on_watchlist | An asset is not on your watchlist. Add it with add_to_watchlist first. |
| 422 | refused | The request cannot be carried out as a whole; reasons lists every reason, and nothing was done. |
| 422 | nothing_to_do | The request asks for nothing to be changed. |
| 409 | not_done | A step failed part way. takenBack says whether watchlist additions and a project it created were taken back; kept lists the changes that were already made and stay (partial: true). A retry with the same clientRequestId returns this answer. |
| 503 | runs_unavailable | Whether a run is in progress could not be read, so nothing was stopped. Try again shortly. |
| 409 | project_archived | The project is archived. Restore it with restore_research_project first. |
| 404 | quote_not_found | No quote with that id belongs to this account. |
| 409 | quote_expired | The quote expired. Get a new one. |
| 409 | quote_replaced | A newer quote replaced this one. |
| 409 | price_higher | The quote now costs more than the priceCredits sent, so nothing started. |
| 409 | already_started | This quote's run was already started. |
| 409 | price_changed | The price changed before the run was admitted, so it did not start and nothing was charged. Get a new quote. |
| 409 | scope_changed | What the project covers changed after it was priced. Get a new quote. |
| 409 | preparing_context | The project is still being prepared. Try again in a minute. |
| 409 | not_started | The run did not start, and nothing was charged. |
| 502 | outcome_unknown | Whether the run started, or how much of the request was done before an error, could not be confirmed. A run's credits stay held for the day until the Research Lab's record says; check the project or the watchlist before sending it again under a new clientRequestId. |
| 502 | not_priced | The run could not be priced just now. |
| 502 | action_failed | The action could not be done just now. Try again. |
| 403 | not_available | Refreshing connected balances is not available for this account. |
| 503 | credits_unavailable | The Astra Credit balance could not be checked, so nothing was charged. Retry shortly with a new clientMessageId. |
| 503 | account_unavailable | The account cannot use SAGE right now. Sign in to AstraEye to review it. |
| 502 | sage_unavailable | SAGE could not answer. Send the message again with a new clientMessageId. |
One token may be active per account. Issuing a replacement invalidates the previous token immediately. Tokens expire 90 days after issue, and a notice is sent in advance of expiry. Settings displays recent API activity for the account; where activity is not recognized, revoke the token there. Token creation and revocation each generate a security notification, and resetting your password or signing out of all sessions also revokes the token and ends every assistant connection. Connections are otherwise separate from the token, and each can be disconnected on its own in Settings.
AstraEye Labs may limit, suspend, or discontinue the Research API, revoke any token, and adjust rate limits and quotas, including where it reasonably believes Terms Section 14.1 has been breached or where required by a data provider's terms. Breach of Section 14.1 is a breach of the Terms of Service and may result in termination under Section 21.